Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions content/work/api-developer-portal.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: "A developer portal for a bank's partner APIs"
summary: "The approach for opening a bank's APIs to business partners: onboarding, sandbox, go-live approval and fees, and a review of the bank's own high-level design."
sector: "Banking"
role: "Solution architect"
themes: ["architecture-integration", "domain-modeling-rules"]
kind: "solution-design"
period: "2026"
date: "2026-08-10"
stack: [".NET", "React", "Keycloak", "API gateway", "PostgreSQL"]
---

## Context

A bank wanted to open its APIs to business partners through a developer
portal: partners sign up, try the APIs in a sandbox, get certified, go live and
are charged for use. Behind it sat an existing API gateway and the core banking
system.

I worked through the bank's requirements, about 165 of them, mapped each to a
part of the solution, proposed the approach and the target architecture, and
reviewed the bank's own high-level design against them.

<Flow
title="A partner's journey"
steps="Register: company and people | Sandbox: try the APIs | Build: keys and test data | Certify: go-live checks | Live: production access | Operate: usage, fees, changes"
notes="The partner company and its users are registered and approved by the bank. | The partner tries the APIs in a sandbox before any production access. | The partner gets credentials and builds against the sandbox. | Going live is an approval, not a checkbox: the partner passes defined checks, and a person at the bank signs off. | Access is provisioned to the bank's existing API gateway. | Usage is reported, fees are charged, and changes go through approval again."
/>

## What I proposed

- **One approval component.** Partner sign-up, product access, go-live and
changes all need approval by someone other than the requester, sometimes in
several stages. One shared maker-checker component instead of an approval
flow per screen.
- **Provisioning that survives a failing gateway.** Changes to the gateway go
through an outbox with retries, and a nightly job reconciles what the portal
thinks is live with what the gateway actually has.
- **Protect the core.** Calls to the core banking system go through a circuit
breaker and a cache, so a slow core doesn't take the portal down.
- **Scheduled jobs that run once.** A single-run scheduler with idempotent jobs,
so a job never runs twice when the portal runs on more than one node.

## What the design review found

The review was about questions the design left open, the ones that turn into
incidents later:

- The session scope of the one-time-password step-up was not defined.
- The sandbox topology was not decided.
- Where fee collection ends and the bank's systems begin was not documented.
- The non-functional requirements had no numbers.
- Reports would run against the live database.

Each finding came with a recommendation, so the review could be acted on, not
just read.
58 changes: 58 additions & 0 deletions content/work/location-tracking-platform.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
---
title: "Location tracking for a mobile operator's business customers"
summary: "The architecture for a platform that lets companies locate their employees' lines and get alerts at geofences, running entirely inside the operator's data centre."
sector: "Telecom"
role: "Solution architect"
themes: ["architecture-integration", "workflow-orchestration"]
kind: "solution-design"
period: "2026"
date: "2026-08-25"
stack: [".NET", "SignalR", "YARP", "Kafka", "PostgreSQL", "PostGIS", "Redis", "MapLibre", "OpenStreetMap"]
---

## Context

A mobile operator wanted to offer its business customers a service to locate
the lines of their field staff, draw areas on a map, get an alert when a line
enters or leaves one, and report on all of it. Every company sees only its own
lines; the operator manages them all from a separate panel. It had to run
entirely inside the operator's own data centre.

I wrote the solution architecture for the proposal: the analysis, the
architecture and its decision records, a component guide, a comparison of map
sources, a working map demo and the resource estimate.

## The constraint that shaped everything

Locations come from the operator's network API, which allows ten queries a
second. At fifty thousand lines, one full sweep takes about 83 minutes, and
adding more servers doesn't make it faster. So the design had to separate the
work that waits on that API from everything else.

<SystemMap
title="Target architecture"
columns="People: Company panel; Operator panel | Entry: Gateway and BFF | Services: Portal API; Live updates | Workers: Collection, rate-limited; Processing, CPU-bound; Batch, reports | Data: Event backbone; PostgreSQL with PostGIS; Redis; Map tiles from files"
/>

## The decisions

- **Workers split by what slows them down.** Collection is limited by the
upstream API, processing by CPU, batch jobs by time. Six workers ship as one
image, in three deployment groups, so the nightly report never delays a
geofence alarm.
- **A self-hosted map stack.** Map data is processed once a month into a single
tile file that the live system only reads. No fee per tile, per user or per
request, and nothing leaves the data centre.
- **Tenant isolation in five places.** Sign-in, gateway, API query filters,
row-level security in the database, and separate channels for live updates.
If the application forgets a filter, the database still refuses.
- **Two sites, active and passive.**
- **Reuse what the operator already runs.** Moving the event backbone onto the
operator's central platform removed a whole cluster from the hardware
request.

## What I learned from it

The numbers decided the architecture before any technology did. Once the rate
limit was on the table, splitting the workers, sizing the hardware and
promising alert times all followed from it.
Loading