RabbinatixDocs
Sign inGet started

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

The Type picks the icon and what the system can hold: a database, a queue or an external API gets Resources.

  1. 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. 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. 3.

    Open More actions (⋯) in the toolbar and click Arrange automatically.

Check: Seven systems, each with its own icon, and no lines yet.

Part 2: Declare what each service provides

  1. 1.

    Open Catalog Service → APIs → Add an API. Provided, GET, /api/v1/products, summary Products for the shop pages, lifecycle Deployed. 200 body:

    items: { id: integer, name: string, price: number }[]
  2. 2.

    Click Create endpoint.

  3. 3.

    Open Checkout Service → APIs → Add an API. Provided, POST, /api/v1/checkout, lifecycle Deployed. Request body:

    cartId: string
    paymentToken: string
  4. 4.

    The 200 body, then Create endpoint:

    orderId: integer
    status: enum(paid, failed)
  5. 5.

    Open Payments Provider → APIs → Add an API. Provided, POST, /v1/charges, lifecycle Deployed. Request body amount: number and token: string; 200 body chargeId: string.

    An External API is someone else’s service. You declare only the part you call.

Part 3: Draw the connections

  1. 1.

    On the map, hover Storefront and drag its + handle onto Catalog Service. The Connect systems dialog opens with both sides filled in.

  2. 2.

    Tick GET /api/v1/products and click Connect 1 API.

  3. 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: Four green lines. The legend in the corner says what each colour and line style means.

Part 4: Read the map

  1. 1.

    In the Filter & view tab on the left, type checkout in Find system or API…. Only the systems that match stay lit. Clear the box.

  2. 2.

    Pick Unresolved & planned under Filter. Nothing shows yet: every API exists and is deployed. Click All.

  3. 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. 4.

    Switch to Connections: one row per pair of systems, with the APIs between them. Switch back to Canvas.

  5. 5.

    Click the line from Storefront to Checkout Service. It opens the connection: each API, and each field both sides agree on.

Check: You can find any system or API in three clicks: map, line, field.