Development & architecture diagrams · Rev 0.1 · 2026-08-28
MVGO Architecture
The build blueprint behind the playbook: system context, containers and
modules, the event-sourced order lifecycle, the two sequences that define the product,
where every rufiyaa moves, how it deploys, and how the first year of development is
sequenced. Companion to 04-technical-architecture.md in the docs package.
Section 1 · who talks to what
System context
Five kinds of people touch the platform, and six external systems make it work.
The one unusual actor is the Ministry of Transport: Maldivian law makes its
read-only live dashboard a launch requirement, so it is drawn as a first-class
consumer, not an afterthought.
Fig 1 — System context. Everything the platform must integrate on day
one sits on the right in solid boxes; the dashed boat-ticketing edge is the Phase-3
boats seam. The coral edge is the legally mandated Ministry data feed — read-only,
out of the platform, never into it.
Section 2 · what runs
Containers & modules
One Go modular monolith carries every domain module — Grab's patterns at a
six-engineer scale. The module boundaries are drawn so any one of them can be split
into its own service later without rewriting its neighbours.
Fig 2 — Containers. Clients never touch a datastore; the gateway is
the single front door. The starred modules (orders, payments) are event-sourced from
day one — every state change is an immutable event on JetStream that the ops console,
Ministry portal and analytics replay as projections.
Module dependencies
Fig 3 — Dependency rule. Solid edges are synchronous calls inside a
request; dashed edges are async event consumption. Authority, analytics, comms and
trust never sit on the booking hot path — if they are down, rides still book.
Section 3 · one machine for every vertical
The order lifecycle
Rides, food, mart, express and (later) boat tickets all run the same event-sourced
state machine with per-vertical configuration. The one deliberate deviation from the
Grab default: food money is only captured after the merchant confirms — the
structural fix for the cancellation trap their users hate most.
Fig 4 — One lifecycle, five verticals. RIDE skips the merchant leg
(a taxi-centre auto-confirm), EXPRESS adds a jetty hand-off inside IN_PROGRESS, BOAT
delegates CONFIRMED to the operator's API. Cancellation is free everywhere left of
ASSIGNED — a product commitment enforced by the state machine, not by support staff.
Section 4 · the two flows that define the product
Sequences
Ride dispatch — request to driver in under 20 seconds
Fig 5 — Dispatch. Steps 6–8 are the marketplace: candidates come from
Redis GEO filtered by zone adjacency, ranked by OSRM road ETA (Malé's one-way maze
makes straight-line distance lie), then offered exclusively for 12 seconds each.
The far-pickup cap is enforced at step 6, not apologised for at step 9.
Food payment — the anti-cancellation-trap timing
Fig 6 — Food payment timing. The teal edges are the contract: a
kitchen's confirmation is the event that takes the customer's money. Grab charges
first and makes cancellation the customer's problem; this ordering makes a closed
restaurant or a sold-out dish structurally free for the customer.
Section 5 · where every rufiyaa goes
Ledger money flow
All money movement is double-entry journal entries tied to order events — the same
design the MMA will audit when the wallet licence is filed. One worked example, the
MVR 145 order with a MVR 10 delivery fee:
Fig 7 — Double-entry from day one. Every arrow is a journal entry
referencing the order event that caused it; account balances are projections. Refunds
reverse journals — they never "adjust" a balance. Amounts in integer laari internally.
Section 6 · where it runs
Deployment
Single region (Mumbai — ~35 ms from Malé), managed data stores, one Kubernetes
cluster. The Ministry portal gets its own ingress with an IP allowlist so regulatory
access never shares a front door with the public apps.
Fig 8 — Deployment. Everything stateful is managed (RDS, Redis,
object storage); the cluster only runs replaceable pods. The coral path is the
regulator's: separate ingress, allowlist, full audit log — provable isolation.
Section 7 · how it gets built
Delivery pipeline & roadmap
CI/CD — two lanes, one gate
Fig 9 — Pipeline. One human gate (prod approve) and one hard
technical gate (schema migrations run and verified on staging first). Everything
else is automatic, so a six-person team ships daily without a release manager.
Roadmap — four workstreams, four milestones
Fig 10 — Delivery roadmap. The critical path runs through the coral
diamonds: Ministry approval gates every ride, the MMA licence gates the wallet. Both
are worked from week 1 — the engineering is sequenced so it is never the blocker.