Example
Map an online shop
Put every app and service of a small online shop on the map: a website, a mobile app, the services behind them, a database, an event bus and an outside payment provider. Then read the map three ways: as a canvas, as tables and as connections.
You will build
- 7 systems on the map, one of each common kind
- 4 APIs, each connected to the apps that use it
- A map you can filter, search and lay out
System map
- StorefrontCatalog ServiceGET /api/v1/products
- Shop AppCatalog ServiceGET /api/v1/products
- StorefrontCheckout ServicePOST /api/v1/checkout
- Checkout ServicePayments ProviderPOST /v1/charges
Part 1: Add the systems
- 1.
Open System map in the sidebar and click System in the toolbar. Fill in and click Create system: - Name
- Storefront
- Type
- Web frontend
- Tags
- shop
- 2.
Add the rest the same way: - Shop App
- Mobile app
- Catalog Service
- Backend service
- Checkout Service
- Backend service
- Shop DB
- Database
- Order Events
- Queue / event bus
- Payments Provider
- External API
- 3.
Open More actions (⋯) in the toolbar and click Arrange automatically.
Check:
Part 2: Declare what each service provides
- 1.
Open Catalog Service → APIs → Add an API. Provided, GET,/api/v1/products, summaryProducts for the shop pages, lifecycleDeployed. 200 body:items: { id: integer, name: string, price: number }[] - 2.
Click Create endpoint. - 3.
Open Checkout Service → APIs → Add an API. Provided, POST,/api/v1/checkout, lifecycleDeployed. Request body:cartId: string paymentToken: string
- 4.
The 200 body, then Create endpoint: orderId: integer status: enum(paid, failed)
- 5.
Open Payments Provider → APIs → Add an API. Provided, POST,/v1/charges, lifecycleDeployed. Request bodyamount: numberandtoken: string; 200 bodychargeId: string.An External API is someone else’s service. You declare only the part you call.
Part 3: Draw the connections
- 1.
On the map, hover Storefront and drag its + handle onto Catalog Service. The Connect systems dialog opens with both sides filled in. - 2.
Tick GET /api/v1/productsand click Connect 1 API. - 3.
Do the same from Shop App to Catalog Service ( GET /api/v1/products), from Storefront to Checkout Service (POST /api/v1/checkout) and from Checkout Service to Payments Provider (POST /v1/charges).
Check:
Part 4: Read the map
- 1.
In the Filter & view tab on the left, type checkoutin Find system or API…. Only the systems that match stay lit. Clear the box. - 2.
Pick Unresolved & planned under Filter. Nothing shows yet: every API exists and is deployed. Click All. - 3.
Further down the same tab, switch Map view to Table: the same map as a list of systems and connections, good for a screen reader or a long list. - 4.
Switch to Connections: one row per pair of systems, with the APIs between them. Switch back to Canvas. - 5.
Click the line from Storefront to Checkout Service. It opens the connection: each API, and each field both sides agree on.
Check:
