---
name: map-to-flozu
description: Map a codebase into Flozu. Use when asked to map, diagram or draw the architecture of a repository, its services, modules or tables, for Flozu.
---

# Map a codebase into Flozu

You're turning a codebase into a Flozu map: the parts of the system, the lines between them, the
zones they sit in, how busy it all gets, and the story it tells. Read the code where it is. Never
send code to Flozu: the map is the only thing that leaves this computer.

Write an **outline**, a JSON file that says what's on the map and how it looks. Flozu lays it out
itself, so leave positions out. An outline can set everything the editor can: card layouts and
sizes, drawings, colours, line styles and routes, traffic and limits, notes, views, scenarios and
stories. Use them: a map that shows where load goes and tells its own story is what people come
to Flozu for.

This guide covers:

- `method`: How to map a codebase. The steps, from picking a scope to sending it.
- `parts`: Parts. Every kind of part, and the ready-made presets.
- `looks`: How it looks. Card layouts and sizes, the drawing library, colours and edges.
- `lines`: Lines. What a line carries, the sides it meets, how it runs and how it's drawn.
- `traffic`: Traffic and limits. People, rates, capacity, limits, buffers, scaling, latency and cost.
- `story`: Notes, views, scenarios and stories. Telling the map's story to different people, and testing it under load.
- `projects`: Projects, closer looks and mapping again. Several repositories in one project, a map inside a part, and mapping a repository again as a proposal.
- `checklist`: Check it. What to check before you send it.
- `reference`: The outline, field by field. Every field, its values and limits.
- `example`: A full example. An outline that uses most of it.

## How to map a codebase

### 1. Pick what the map is about

One map should read in a minute: aim for 8 to 40 parts. Ask the person what they want to see if
it isn't clear, such as the whole platform, one service, or how a request travels.

- **A system of several apps or services:** each deployable thing is a part: services, workers,
  functions, scheduled jobs, apps, plus the databases, caches, queues and buckets they use, and
  the outside services they call.
- **One app or service:** its modules or packages are parts (`module`, `library`,
  `interface`), with the stores and services it talks to around them.
- **A database:** its tables are parts (`table`), linked by their foreign keys.

For a large system, make one map for the whole and suggest a map for each big service after it,
which its part on the first map opens into. For several repositories, see Projects.

### 2. Find the parts

Look first at what says what runs, then at the code:

- Workspace and package files (`package.json`, `pnpm-workspace.yaml`, `go.mod`,
  `Cargo.toml`, `pyproject.toml`), and folders such as `apps/`, `services/` and
  `packages/`.
- How it's run and deployed: `Dockerfile`s, `docker-compose.yml`, Kubernetes and Helm files,
  Terraform, Pulumi, CDK, `serverless.yml`, `wrangler.toml`, `fly.toml`, `vercel.json`,
  Procfiles and CI workflows.
- Which outside services it uses: client libraries and SDKs (`pg`, `redis`, `stripe`,
  `@aws-sdk/*`, `openai`), and the names of settings and environment variables, such as
  `DATABASE_URL` or `STRIPE_KEY`. Use their names, never their values.
- What starts work: HTTP routes, queue consumers, topic subscriptions, cron schedules and
  webhooks.

Give each part a `kind` or a ready-made `preset` (see Parts), a plain `name` ("Orders API",
not `orders_svc_v2`), its `technology`, `external: true` if another company runs it, `code`
for where it lives, and a one-sentence `description` when the name doesn't say what it does.
Add a `person` for each kind of user and a `client` for each app they use, so the map starts
where traffic starts.

### 3. Link them

A link goes from the part that calls, sends or depends to the part it reaches. Every link should
be something you saw in the code or its settings. Give it a short `label` for what it carries
and a `protocol` when you know it. See Lines.

### 4. Put them in zones

Zones are boxes around parts that belong together: a `system`, a cloud `region`, a private
`network`, what one `team` owns (from `CODEOWNERS`), or any other `zone`. A zone can sit
inside another with `parent`. Keep it to two or three levels. Parts outside every zone are
fine, such as people, apps and outside services.

### 5. Make it look like the system

A map where every card and line looks the same is hard to read. Choose, from what the code says:

- **What matters most** is bigger: one to three parts at `large`, the busy path's lines `bold`.
- **What supports it** is quieter: `slim` cards for caches, topics, libraries and outside
  services, so the main path stands out.
- **Each part's drawing** says what it does: a cache shows its hit rate, a payment service a card,
  a rate limiter a token bucket.
- **Colour has one meaning per map**, such as the main path, or which team owns what. Most parts
  stay uncoloured.

See How it looks, and Lines.

### 6. Add traffic

Put how many people use it on the parts traffic starts at, a rate on each line, and capacity on
the parts that can run out. Take numbers from the code and its settings where they're there, and
make fair estimates where they aren't, so the map shows where load goes and which part gives
first. See Traffic and limits.

### 7. Tell its story

Add a story of three to seven steps along the main journey, a normal day and the busy moment
the business worries about as scenarios, a view in plain words for people who don't build it, and
a note or two where something needs explaining. See Notes, views, scenarios and stories.

### 8. Check it and send it

Go through Check it. Then, if you have Flozu's MCP tools, call `list_maps` and look for a map
of this repository made before. If there is one, map it again with `update_map` (see Projects);
if not, call `create_map` with the outline. Without the tools, save it as
`<name>.flozu-outline.json`, and the person imports it with **Import** on Flozu's home
page. If Flozu says the outline can't be drawn, the message names what's wrong and where: fix that
and try again.

Then tell the person what's on the map, what you left out and why, which numbers are estimates,
and what you weren't sure of.

## Parts

Every part has a `kind`, which says what it is and how traffic moves through it. Pick the
closest; use `other` only when nothing fits.

- `person`: Someone who uses the system, such as a customer, an admin or a support agent. Its own drawing: `crowd`.
- `client`: An app people use: a website, a mobile app, a desktop app or a device. Its own drawing: `browser`.
- `dns`: Turns names like shop.example.com into the addresses traffic is sent to. Its own drawing: `records`.
- `cdn`: Serves content from close to people and absorbs traffic before it reaches you. Its own drawing: `globe`.
- `firewall`: Lets allowed traffic through and blocks the rest, such as attacks and bots. Its own drawing: `rules`.
- `gateway`: The front door for requests. It checks who's calling and routes each request. Its own drawing: `lanes`.
- `sign-in`: Checks who people are and hands out the tokens other parts trust. Its own drawing: `password`.
- `load-balancer`: Shares traffic between copies of a service so none of them gets swamped. Its own drawing: `shares`.
- `rate-limiter`: Lets a set amount through each second and turns the rest away. Its own drawing: `gauge`.
- `service`: A running program that answers requests, such as an API or a web server. Its own drawing: `activity`.
- `worker`: Works through jobs in the background, usually taking them from a queue. Its own drawing: `jobs`.
- `function`: Code that runs when it's called and scales up and down by itself. Its own drawing: `warm`.
- `scheduler`: Starts jobs on a timetable, such as a nightly export or a reminder every hour. Its own drawing: `clock`.
- `ai-model`: A language or machine learning model that the system calls. Its own drawing: `tokens`.
- `queue`: Holds work in line until something is free to take it. Each item goes to one taker. Its own drawing: `line`.
- `topic`: Broadcasts each event to every part that subscribes. Its own drawing: `fan-out`.
- `database`: Keeps the system's records, such as orders, customers and stock. Its own drawing: `faders`.
- `cache`: Keeps popular data in memory so it can be read quickly. Its own drawing: `hit-rate`.
- `search`: An index that finds records by their words, such as products in a shop. Its own drawing: `results`.
- `storage`: Holds files such as images, exports and backups. Its own drawing: `bucket`.
- `data-warehouse`: Gathers data from across the system so people can report on it and analyse it. Its own drawing: `bars`.
- `endpoint`: A way into a service that others call, such as an HTTP route, an RPC method or an event handler. Its own drawing: `route-list`.
- `module`: A part of a service's code with one job, such as a package or a folder. Its own drawing: `module-graph`.
- `file`: One source file, named by its path. Its own drawing: `source`.
- `interface`: A contract code depends on rather than a thing that runs, such as a TypeScript interface or an API spec. Its own drawing: `contract`.
- `library`: A package the code is built on, such as stripe-node or a Go module. Its own drawing: `package`.
- `table`: A table, collection or index inside a store, where a service keeps its records. Its own drawing: `rows`.
- `other`: Anything that doesn't fit another kind. It behaves like a service. Its own drawing: `blank`.

## Presets

A preset is a ready-made part: a kind, a technology, a drawing, a card layout and starting limits
that fit it. Set `preset` to its id and give the part its own `name`. Anything else you set
on the part wins over the preset, so `{ "preset": "postgresql", "name": "Orders DB", "flow":
{ "capacity": 800 } }` is PostgreSQL with your own capacity. Use one whenever it matches what the
code uses.

### People and apps

- `customers`: Customers, a person. The people who use what you make.
- `admins`: Admins, a person. The people who run things behind the scenes.
- `support-team`: Support team, a person. The people who help customers.
- `on-call`: On call, a person. Whoever answers when something breaks.
- `web-app`: Web app, a client (React). A website people use in their browser.
- `iphone-app`: iPhone app, a client (iOS). An app on people's iPhones.
- `android-app`: Android app, a client (Android). An app on people's Android phones.
- `desktop-app`: Desktop app, a client. An app people install on their computer.
- `tills`: Tills, a client. The tills in a shop, taking payments.
- `sensors`: Sensors, a client. Devices that send readings on their own.
- `partners`: Partner integration, a client. Another company's system calling your API.

### The way in

- `cloudflare-dns`: Cloudflare DNS, a dns (Cloudflare). Turns your domain into the addresses traffic goes to.
- `route-53`: Route 53, a dns (Route 53). DNS that moves traffic away from a failed site.
- `cloudflare-cdn`: Cloudflare CDN, a cdn (Cloudflare). Serves your pages and files from close to people.
- `cloudfront`: CloudFront, a cdn (CloudFront). A CDN that keeps most traffic off your servers.
- `web-firewall`: Web firewall, a firewall (AWS WAF). Blocks attacks and bad requests before they reach you.
- `ddos-protection`: DDoS protection, a firewall (Cloudflare). Soaks up floods of traffic meant to take you down.
- `bot-protection`: Bot protection, a firewall. Lets people in and turns bots away.
- `vpn`: VPN, a firewall (Tailscale). A private way in for your own team.
- `api-gateway`: API gateway, a gateway (Kong). Checks every call to your API and routes it.
- `graphql-gateway`: GraphQL gateway, a gateway (GraphQL). One query that gathers answers from several services.
- `reverse-proxy`: Reverse proxy, a gateway (NGINX). One front door in front of your servers.
- `service-mesh`: Service mesh, a gateway (Istio). Carries and secures the calls between your services.
- `load-balancer`: Load balancer, a load-balancer (ALB). Shares traffic between healthy copies of a service.
- `haproxy`: HAProxy, a load-balancer (HAProxy). Hands requests to each server in turn.
- `token-bucket`: Token bucket limiter, a rate-limiter. Lets bursts through, then settles to a steady rate.
- `per-user-limit`: Per-user limit, a rate-limiter (Redis). Caps how often one person can call in a minute.
- `api-quota`: API quota, a rate-limiter. A daily allowance for each customer's calls.
- `auth0`: Auth0 sign-in, a sign-in (Auth0). Sign-in run for you, with passwords and social logins.
- `passkeys`: Passkey sign-in, a sign-in. Signs people in with their device, and no password.
- `keycloak`: Keycloak, a sign-in (Keycloak). Your own sign-in, handing out tokens to the other parts.

### Compute

- `rest-api`: REST API, a service (Node.js). An API answering requests on a set of routes.
- `web-server`: Web server, a service (Next.js). Builds and serves your web pages.
- `checkout-service`: Checkout service, a service (Go). Takes a basket and turns it into an order.
- `orders-service`: Orders service, a service. Tracks each order from placed to shipped.
- `kubernetes-service`: Kubernetes service, a service (Kubernetes). A service in pods that scale out as traffic grows.
- `container`: Container, a service (Docker). A service packed in a container.
- `background-worker`: Background worker, a worker (Sidekiq). Works through jobs from a queue.
- `celery-worker`: Celery worker, a worker (Celery). A pool of Python workers taking tasks.
- `video-encoder`: Video encoder, a worker. Turns each upload into the sizes people stream.
- `workflow-engine`: Workflow engine, a worker (Temporal). Runs long jobs step by step, and picks up after a failure.
- `image-resizer`: Image resizer, a function (Lambda). Makes every size of a picture when it's uploaded.
- `webhook-handler`: Webhook handler, a function (Cloudflare Workers). Takes in events other companies send you.
- `edge-function`: Edge function, a function (Cloudflare Workers). Small code that runs close to people.
- `nightly-export`: Nightly export, a scheduler (Cron). Starts an export every night.
- `reminders`: Reminders, a scheduler. Sends reminders when they're due.
- `data-pipeline`: Data pipeline, a scheduler (Airflow). Runs data jobs in order on a timetable.

### AI

- `claude`: Claude, a ai-model (Claude). A language model that answers, writes and reasons.
- `ai-agent`: AI agent, a ai-model. A model that uses tools to get a task done.
- `embeddings`: Embeddings model, a ai-model. Turns text into numbers that capture its meaning.
- `knowledge-base`: Knowledge base, a search. Finds the passages a model needs to answer.
- `vector-database`: Vector database, a search. Finds the closest matches by meaning.
- `recommendations`: Recommendations, a ai-model. Picks what to show each person next.
- `moderation`: Moderation, a ai-model. Checks posts and holds back the harmful ones.
- `fraud-model`: Fraud check, a ai-model. Scores each payment and holds the risky ones.
- `speech-to-text`: Speech to text, a ai-model. Turns voice into text as people speak.

### Messaging

- `sqs-queue`: SQS queue, a queue (SQS). Holds jobs until a worker is free.
- `rabbitmq`: RabbitMQ, a queue (RabbitMQ). Shares messages out between its consumers.
- `priority-queue`: Priority queue, a queue. Lets urgent work go first.
- `dead-letter-queue`: Dead-letter queue, a queue. Keeps messages that keep failing, to look at later.
- `kafka-topic`: Kafka topic, a topic (Kafka). A log of events, split into partitions.
- `event-bus`: Event bus, a topic (EventBridge). Carries events from the parts that publish to the parts that listen.
- `pub-sub-topic`: Pub/Sub topic, a topic (Pub/Sub). Copies each event to every subscriber.
- `outbox`: Outbox, a worker. Sends each saved change on as an event, so none is lost.

### Data

- `postgresql`: PostgreSQL, a database (PostgreSQL). A relational database for your records.
- `read-replica`: Read replica, a database (PostgreSQL). A copy of the database that takes the reads.
- `mysql`: MySQL, a database (MySQL). A relational database of tables and rows.
- `mongodb`: MongoDB, a database (MongoDB). A database of documents.
- `dynamodb`: DynamoDB, a database (DynamoDB). A key-value table that scales by itself.
- `graph-database`: Graph database, a database (Neo4j). Keeps records and how they relate.
- `time-series`: Time series database, a database. Keeps readings over time.
- `ledger`: Ledger, a database (PostgreSQL). Records every movement of money, always in balance.
- `redis-cache`: Redis cache, a cache (Redis). Keeps popular data in memory.
- `session-store`: Session store, a cache (Redis). Remembers who's signed in.
- `memcached`: Memcached, a cache (Memcached). A memory cache that drops the oldest keys first.
- `elasticsearch`: Elasticsearch, a search (Elasticsearch). Finds records by their words.
- `algolia`: Algolia, a search (Algolia). Search as you type, run for you.
- `s3-bucket`: S3 bucket, a storage (S3). Keeps files of any size.
- `media-storage`: Media storage, a storage (Cloud Storage). Keeps the photos people upload.
- `video-library`: Video library, a storage. Keeps videos ready to stream.
- `backups`: Backups, a storage (Backblaze). A copy of everything, taken every night.
- `snowflake`: Snowflake, a data-warehouse (Snowflake). Gathers data from everywhere for reports.
- `bigquery`: BigQuery, a data-warehouse (BigQuery). A warehouse you ask questions of in SQL.
- `clickhouse`: ClickHouse, a data-warehouse (ClickHouse). Fast analytics over lots of events.
- `etl-job`: ETL job, a worker. Copies data from your systems into the warehouse.

### Outside services

- `stripe`: Stripe payments, a service (Stripe). Takes card payments for you.
- `paypal`: PayPal, a service (PayPal). Lets people pay with PayPal.
- `shopify`: Shopify, a service (Shopify). A shop run for you, with its cart and checkout.
- `email-sending`: Email sending, a service (SendGrid). Sends your emails and tracks them.
- `text-messages`: Text messages, a service (Twilio). Sends text messages to people's phones.
- `push-notifications`: Push notifications, a service (Firebase). Sends notifications to people's phones.
- `delivery-tracking`: Delivery tracking, a service. A courier's service for sending and tracking parcels.

### Operations

- `monitoring`: Monitoring, a other (Datadog). Watches your systems' requests, errors and speed.
- `error-tracking`: Error tracking, a other (Sentry). Collects the errors your apps hit.
- `logs`: Logs, a other. Gathers what every part writes down.
- `dashboards`: Dashboards, a other (Grafana). Charts of how everything is doing.
- `feature-flags`: Feature flags, a service. Turns features on for some people before everyone.
- `build-pipeline`: Build pipeline, a other. Builds, tests and ships each change.
- `secrets-vault`: Secrets vault, a other. Keeps passwords and keys out of the code.

### Inside a service

- `http-routes`: HTTP routes, a endpoint (Express). The routes a service answers, such as POST /payments.
- `graphql-resolver`: GraphQL resolver, a endpoint (GraphQL). Answers one field or mutation of a GraphQL API.
- `grpc-method`: gRPC method, a endpoint (gRPC). One method other services call over gRPC.
- `webhook-route`: Webhook route, a endpoint. The route inside a service that takes in events another company sends.
- `module`: Module, a module. A part of the code with one job, such as billing or accounts.
- `domain-logic`: Domain logic, a module. The rules of the business, kept apart from how they're reached and stored.
- `data-access`: Data access, a module. The code that reads and writes the service's records.
- `source-file`: Source file, a file (TypeScript). One file of code, named by its path.
- `entry-file`: Entry file, a file (TypeScript). Where the service starts, wiring the other parts together.
- `test-suite`: Tests, a file (Vitest). The tests that check a part of the code still works.
- `interface`: Interface, a interface (TypeScript). A promise in code that other code keeps, such as a TypeScript interface.
- `api-spec`: API spec, a interface (OpenAPI). The written contract of an API, which clients and the service both follow.
- `protobuf-schema`: Protobuf schema, a interface (Protocol Buffers). The messages and methods of a gRPC service.
- `npm-package`: npm package, a library (npm). A package the code is built on, from npm.
- `payments-sdk`: Payments SDK, a library (Stripe). The library a service calls a payment provider with.
- `orm`: ORM, a library (Prisma). Turns rows in a database into objects in code.
- `table`: Table, a table. One table in a database, where a service keeps its records.
- `table-columns`: Table with columns, a table. A table drawn with its columns and their types.

## How it looks

How a part looks never changes what it is or how traffic moves through it, so choose looks for
the reader: what should they see first, and what can they skim?

### Card layouts

- `standard`: The name on top, then the drawing and one figure.
- `showcase`: The drawing fills the top of the card, with the name and figure below it.
- `wide`: A wide card: the name and figure on the left, the drawing on the right.
- `slim`: One slim line with the icon, the name and the figure, and no drawing.

Most parts are `standard`. Use `showcase` for the few parts a reader should see first, such
as the people and the main app. Use `wide` for a part with a lot to show, and `slim` for the
supporting cast, such as caches, topics, libraries, tables and outside services, so a busy map
stays calm.

### Sizes

`size` is `small`, `standard`, `large`, `extra-large`, each in its layout's own shape, in canvas units:

| Layout | small | standard | large | extra-large |
| --- | --- | --- | --- | --- |
| standard | 160 × 128 | 192 × 160 | 288 × 240 | 384 × 320 |
| showcase | 160 × 144 | 192 × 176 | 288 × 256 | 384 × 352 |
| wide | 256 × 112 | 320 × 144 | 448 × 208 | 576 × 256 |
| slim | 160 × 48 | 192 × 64 | 288 × 96 | 384 × 128 |

Leave most parts `standard`. Make the one to three parts the map is about `large`, and
minor ones `small`. Never make everything big: size is how a reader knows what matters.

### Drawings

Every part shows a drawing in its panel, which moves while the map plays. Left out, it's its
kind's own (listed under Parts). Set `drawing` to the one that says what this part does:
`hit-rate` for a cache, `card-payment` for payments, `token-bucket` for a rate limiter,
`dead-letters` for a dead-letter queue. Any part can show any drawing.

### People

- `crowd`: A few people, sending requests.
- `journey`: One person moving from browsing to paying.
- `online`: How many people are here, with a live count.
- `team`: A small team, each with a status dot.
- `support`: Someone with a headset, answering a chat.
- `admin`: Someone with a key, changing settings.
- `around-the-world`: People across time zones, with the awake ones lit.
- `persona`: A profile card with a name, a role and what they need.
- `audiences`: People split into groups: new, returning and paying.

### Apps and devices

- `browser`: A web page with a button being pressed.
- `phone`: A mobile app, with a list and a tap.
- `devices`: A laptop, a tablet and a phone, all sending requests.
- `desktop`: A desktop window with a sidebar, syncing.
- `watch`: A smartwatch with a ring filling up.
- `sensor`: A small device sending a reading on every beat.
- `tv`: A screen playing a stream, with its progress bar.
- `terminal`: A command typed, and its answer printed.
- `point-of-sale`: A till, with a card tapped against it.
- `api-client`: Code calling an API, and the answer coming back.
- `vehicle`: A vehicle on a route, sending where it is.

### Email and alerts

- `email`: Envelopes leaving an outbox, one at a time.
- `inbox`: An inbox, with new mail arriving at the top.
- `text-message`: A phone with text messages arriving.
- `push`: A notification sliding onto a lock screen.
- `chat-room`: Several people talking in one room.
- `webhook`: A POST sent to a web address, and the reply code.
- `video-call`: A grid of people on a call, with the speaker lit.
- `alerts`: A bell ringing, with a count of what's new.

### Network

- `records`: Names and the addresses they point to, looked up in turn.
- `lookup`: A name resolved step by step, from the root to the address.
- `expiry`: Records counting down until they're looked up again.
- `globe`: A globe with edge servers around it.
- `edges`: Edge servers around the world, close to people.
- `offload`: How much the edge serves, and how little reaches the origin.
- `lanes`: Lanes of requests merging through one gate.
- `paths`: Paths, and the service each one is routed to.
- `checks`: Each request checked for its key and quota, then routed.
- `shares`: One stream split three ways, with each share's level.
- `rotation`: Requests handed to each copy in turn.
- `targets`: The copies behind it and whether each is healthy.
- `packets`: Packets crossing between two machines, after a handshake.
- `anycast`: One address, answered by whichever site is nearest.
- `edge-cache`: Copies kept at the edge, with a hit served at once.
- `routes`: A table of routes, and where each one sends traffic.
- `reverse-proxy`: One door in front of several servers.
- `tunnel`: A private tunnel joining two networks.
- `mesh`: Services joined through side-cars, with traffic between them.
- `health-checks`: Each server checked in turn, and the failing one taken out.
- `failover`: Traffic moving from a failed site to its standby.
- `latency-map`: Round trips to each region, with the quickest lit.
- `live-connection`: A connection held open, with messages going both ways.
- `graphql`: A query asking for fields, and an answer shaped like it.
- `ports`: A machine's ports, with the open ones lit.

### Traffic and limits

- `gauge`: A needle that edges into the red past the limit.
- `token-bucket`: A bucket of tokens: each request takes one.
- `window`: Each second's traffic against the limit, with the excess cut.
- `leaky-bucket`: Requests pour in and drip out at a steady pace.
- `sliding-window`: A window sliding over the last minute of requests.
- `throttle`: Bunched-up requests spaced out to a steady pace.
- `quota`: A daily allowance being used up, and what's left of it.
- `bandwidth`: A pipe filling with traffic towards its limit.
- `circuit-breaker`: A switch that opens when calls fail, and closes once they recover.
- `retries`: A call failing, waiting longer each time, then going through.

### Security and sign-in

- `rules`: A wall of rules: allowed traffic passes, the rest bounces off.
- `shield`: A shield with what it let through and what it blocked.
- `log`: Allowed and blocked requests as they happen.
- `password`: A password being typed, then a tick.
- `token`: A signed token, issued in three parts.
- `code`: A six-digit code being filled in.
- `lock`: A padlock closing over what it keeps safe.
- `secrets`: Keys kept in a vault, handed out one at a time.
- `fingerprint`: A fingerprint being scanned, line by line.
- `passkey`: A device confirming who it is with a touch, and no password.
- `two-step`: A password, then a code from a phone.
- `permissions`: Roles, and what each one may do.
- `sessions`: Signed-in sessions, each running out in time.
- `certificate`: A certificate, who issued it and the days until it expires.
- `attack`: A flood of traffic, mostly stopped at the edge.
- `bot-check`: Visitors checked one by one, with the bots turned away.
- `audit-log`: Who did what and when, written down for later.
- `encryption`: Plain text going in, and scrambled text coming out.

### Compute

- `activity`: Recent traffic as a line, and how busy it is.
- `instances`: Copies of the service, each with its load.
- `latency`: How long answers take: typical, slow and slowest.
- `jobs`: Jobs in progress, each filling as it's worked on.
- `stages`: Jobs moving from taken, to working, to done.
- `pool`: Worker slots, busy or free.
- `warm`: Copies that light up as they're called.
- `calls`: Calls arriving over time, each a short burst.
- `scaling`: Copies rising and falling with demand.
- `containers`: Containers stacked on a machine, starting and stopping.
- `pods`: Pods spread over three machines, with one being replaced.
- `servers`: A rack of servers with their lights blinking.
- `cpu`: A processor's cores, and how busy each one is.
- `threads`: Requests handed to threads, with a few waiting.
- `endpoints`: An API's routes, with how often each is called.
- `source-code`: Lines of code, with the one running lit.
- `deploys`: A new version rolling out across the copies.
- `blue-green`: Two versions side by side, with traffic switching over.
- `scale-out`: Copies added as the load climbs past a line.
- `cold-start`: A function waking up, then answering quickly.
- `batch`: A big job split into chunks, worked on side by side.
- `pipeline`: Data passing through steps, one after another.
- `video-encoding`: One video turned into several sizes.
- `image-sizes`: One picture made into several sizes.
- `workflow`: Steps that branch, wait on each other, then join.

### Time

- `clock`: A clock, and the job it starts every hour.
- `timeline`: A day's runs on a timeline, with now moving along it.
- `week`: A week of runs on a calendar.
- `countdown`: A timer counting down to the next run.
- `cron`: A cron line, and when it next runs.
- `month`: A month, with runs on chosen days.
- `hourglass`: Sand running through, for something that takes time.
- `delayed-jobs`: Jobs parked until their time comes.

### AI

- `tokens`: An answer appearing a word at a time.
- `chat`: A prompt and the reply streaming back.
- `layers`: Layers of a network, with a signal passing through.
- `embeddings`: Words placed as points, with similar ones close together.
- `vector-search`: A question finding its nearest neighbours.
- `agent`: Think, use a tool, look at the result, and go round again.
- `retrieval`: A question, the passages found for it, then the answer.
- `classifier`: Items sorted into labelled bins, each with how sure it is.
- `training`: The error falling as a model learns.
- `image-generation`: A picture sharpening out of noise.
- `speech`: A voice turned into words as it speaks.
- `recommendations`: Items picked for someone, best match first.
- `moderation`: Posts checked as they arrive, with a few held back.
- `context-window`: Tokens filling a context window towards its limit.

### Messaging

- `line`: Work waiting in line, with new items arriving.
- `depth`: How long the line has been over time.
- `states`: What's waiting, being worked on and failed.
- `fan-out`: One event copied to every subscriber.
- `subscribers`: Each subscriber, and the events reaching it.
- `partitions`: The event log, split into partitions.
- `priority`: Urgent work jumping to the front of the line.
- `dead-letters`: Messages that kept failing, set aside to look at.
- `in-order`: Messages kept in exact order, handled one at a time.
- `consumer-group`: Messages shared out between the members of a group.
- `event-stream`: Events flowing past, each tagged with its type.
- `pub-sub`: Publishers on one side, subscribers on the other.
- `outbox`: Changes written down, then sent on as events.
- `acks`: Messages delivered and ticked off one by one.
- `back-pressure`: A fast sender slowed down by a full line.

### Data

- `faders`: Levels for reads, writes and connections.
- `table`: A table of records, with new rows being written.
- `replicas`: A primary copying its writes to two replicas.
- `hit-rate`: How much is served from memory.
- `keys`: Keys in memory, each expiring in time.
- `memory`: Memory used and free, with the oldest keys making room.
- `results`: A search and its best matches.
- `index`: Words, and the records each one is found in.
- `suggest`: Suggestions appearing as someone types.
- `key-value`: Keys and their values, each read in a blink.
- `documents`: Documents with fields nested inside them.
- `graph`: Records joined by how they relate.
- `time-series`: Readings landing on a timeline as they're taken.
- `shards`: Records spread over shards by their key.
- `schema`: Tables and the links between them.
- `sql`: A query, and the rows it brings back.
- `transactions`: Changes saved together, or not at all.
- `schema-change`: A table changing shape, a step at a time.
- `change-feed`: Each change copied out as it happens.
- `connections`: A pool of connections, busy and free.

### Files and media

- `bucket`: Files dropping into a bucket.
- `files`: Images, documents and archives, kept side by side.
- `usage`: How much space each kind of file takes.
- `images`: A grid of photos, with a new one uploading.
- `video`: A video playing, with its buffer filling ahead.
- `upload`: A file uploading in chunks.
- `cold-storage`: Files moving from hot to cold as they age.
- `folders`: Folders, and the files inside them.
- `file-versions`: One file, and its earlier versions behind it.
- `audio`: A sound wave playing.

### Analytics

- `bars`: Data flowing in, and a chart growing from it.
- `heatmap`: A grid of figures, darker where there's more.
- `trend`: A figure over time, with this week's point.
- `funnel`: Steps from visiting to buying, each one narrower.
- `dashboard`: A dashboard of tiles: a figure, a chart and a list.
- `donut`: A ring split into shares.
- `etl`: Data copied from several sources into tables.
- `cohorts`: Each week's sign-ups, and how many came back.
- `report`: A report with a headline figure and a chart.
- `places`: Activity by place, as dots on a map.
- `top-list`: The top items, ranked, each with a bar.
- `big-number`: One large figure, and how it's changed.

### Payments and shopping

- `card-payment`: A card tapped, and the payment approved.
- `checkout`: A basket, its total and a pay button.
- `receipt`: A receipt printing line by line.
- `invoice`: An invoice with its lines, a total and a paid stamp.
- `subscription`: A plan renewing each month.
- `cart`: Items dropping into a shopping cart.
- `stock`: Products on shelves, with how many are left.
- `orders`: Orders moving from placed, to packed, to shipped.
- `refunds`: Payments going out, and a few coming back.
- `fraud-check`: Each payment scored, with the risky ones held.
- `ledger`: Debits and credits that always balance.
- `delivery`: A parcel moving along its route to a door.
- `prices`: A price tag that follows demand.

### Operations

- `logs`: Log lines scrolling past, with a warning in amber.
- `metrics`: Charts of requests, errors and response times.
- `incident`: An alert going off, and the person on call taking it.
- `trace`: One request's time spent in each part, as bars.
- `uptime`: Each day's uptime as a bar, with one bad day.
- `errors`: Errors spiking, then settling down.
- `feature-flags`: Switches turning features on for some people.
- `experiment`: Two versions side by side, and which one is winning.
- `build`: Build, test and deploy steps, ticking off in turn.
- `branches`: Branches splitting off and merging back.
- `backups`: A copy taken every night, with the oldest let go.
- `settings`: Settings, with switches and values.

### Inside a service

- `route-list`: An endpoint's routes, each lit in turn as a request comes in.
- `module-graph`: A module's own parts, with calls running from its way in to its store.
- `source`: Numbered lines of code, with the running line lit.
- `contract`: An interface's methods, ticked off as code keeps each one.
- `package`: A package with its name and version, and an update waiting.
- `rows`: A table's columns, and new rows being written.
- `imports`: A file's imports, fanning out to what it uses.
- `call-stack`: A call stack growing as one function calls the next.
- `tests`: Tests running, each passing in turn.
- `columns`: Columns or fields, each with its type.
- `semver`: A version number going up, with the kind of change it is.
- `handler`: A request arriving at a handler, worked on and answered.

### General

- `blank`: An empty box, for anything.
- `cog`: A turning cog, for something that does work.
- `modules`: Blocks fitted together, for something made of parts.
- `sparkline`: A small line chart, drawing as it goes.
- `bar-chart`: Bars rising and falling.
- `ring`: A ring filling to a share.
- `status`: A list of checks, each passing or failing.
- `flowchart`: Boxes and arrows, with something moving through them.
- `stack`: Layers stacked one on another.
- `checklist`: Tasks being ticked off.
- `hub`: One centre joined to many.
- `filter`: Many go in, and few come out.
- `cycle`: Steps going round and round.
- `signal`: A pulse sent out in rings.
- `transform`: Shapes going in, and changed shapes coming out.

### Colours and edges

A part's, zone's or note's `style` sets:

- `stroke`: the edge's colour. `strokeStrength`, from 0 to 1, how strong it is.
- `fill`: the colour it's filled with. `fillStrength`, from 0 to 1, how strong. Keep fills
  light, from 0.2 to 0.5, so text stays readable.
- `pattern`: `solid`, `dashed`, `dotted`. `weight`: `thin`, `regular`, `bold`.

Colours are names, which each theme draws in its own shade so the map reads in light and dark:
`grey`, `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `teal`, `blue`, `indigo`, `violet`, `pink`. A brand colour can be `#rrggbb`, drawn as it is in both themes, so use those
sparingly.

Colour means something in Flozu: things are grey until they have something to say, and Flozu's
own orange marks what's selected and live. So:

- Give colour one meaning per map, and say what it is in a note: the main path, which team owns
  what, or what's new. Two to four colours at most.
- Leave most parts uncoloured. A coloured edge (`stroke`) is quieter than a fill.
- A zone with a dashed edge reads as a boundary you don't control, such as another company's or
  another team's.
- Avoid `orange` for your own meaning, so it never looks like Flozu's live colour.

## Lines

### What a line carries

- `request`: it asks and waits, such as an HTTP call or a database query.
- `message`: it sends and moves on, such as an event on a topic or a job on a queue. Links into
  and out of a queue or topic are messages already, so you can leave `kind` out.
- `uses`: a dependency with no traffic, such as code importing a library or implementing an
  interface. Links into a library or interface are `uses` already.

Each kind is drawn its own way, so a reader can tell a call from an event at a glance. A line goes
from `from` to `to`; set `direction: "both"` only when traffic really flows both ways, such
as a live connection. Give it a short `label` for what it carries ("Place order", "Order
placed"), and a `protocol` (HTTPS, gRPC, SQL, AMQP, WebSocket) when you know it.

### Where it meets a part

A part has four sides: `left`, `right`, `top`, `bottom`. Leave them out and Flozu picks
them as it lays the map out: a line leaves the right of `from` and arrives at the left of
`to`, so traffic reads left to right; a line back to an earlier part runs from left to right
along its own lane; and a line that would run behind a card meets a top or bottom instead. Most
lines need nothing more. Set `fromSide` and `toSide` only to say something with them:

- A dependency, such as code using a library or a service writing logs: `"toSide": "top"` reads
  as something the part leans on rather than the next step.

### How it runs

`lineRoute` on the outline sets how every line runs: `curved`, `square`, `straight`. Left out, they curve.
`square` turns at right angles, which reads cleanly on a map with many lines and zones, like an
architecture diagram; `curved` suits a map with fewer lines, for people; `straight` suits a
small one. A line's own `style.route` overrides it for that line.

### How it's drawn

A link's `style` sets:

- `stroke` and `strokeStrength`: its colour, by name as for parts, and how strong.
- `pattern`: `solid`, `dashed`, `dotted`. Left out, it's its kind's own.
- `weight`: `thin`, `regular`, `bold`. Make the main path `bold`, and lines nobody needs to follow
  `thin`.
- `effect`, what moves along it while the map plays: `traffic`, `pulse`, `flow`, `none`. Left out, it's its
  traffic, as dots that speed up as it gets busier. `pulse` suits heartbeats and health checks,
  `flow` a steady stream such as video or a data pipeline, and `none` a line with nothing on
  the move.
- `route`: as above. `hidden: true` leaves the line itself out, so only what moves along it
  shows. Use it rarely.

### Standby lines

`standby: true` makes a line carry nothing until a line beside it fails: one from the same part,
carrying the same kind of traffic, to the same kind of part. Use it for a failover to a replica
or a second region, so a failure drill shows the switch.

## Traffic and limits

Flozu works traffic out from the numbers on the map; it never runs or calls your systems. Traffic
starts at parts no line flows into, such as people or an app, and each part sends on traffic in
proportion to what reaches it. Past a part's limit, the excess is turned away; past its capacity,
work backs up. Scenarios then scale it all: a busy day, a spike, a failure. Rates are compared as
plain numbers, whatever their unit.

### Where traffic starts

On a `person` (or any part traffic starts at), `flow.people` says how many people use it at
once on a normal day: `busiest`, and optionally `typical` (the day's average) and
`quietest` (overnight). Its lines' rates are what those people send at the busiest moment.

### On each line

`rate` is how much a line carries per second at a normal day's busiest moment, and `unit` what
it counts, such as `req/s`, `msg/s`, `queries/s` or `jobs/s`. Real systems are uneven, so
the rates should be too: a page view makes several calls, a cache takes more reads than the
database behind it, most visitors never pay, and a nightly job is quiet all day.

### On each part (`flow`)

- `capacity`: the most it can process per second before work backs up. For a part that scales,
  what one copy can process.
- `limit`: the most it lets through per second; the rest is turned away. For rate limiters,
  gateways and anything with a quota.
- `buffer`: how much can wait before traffic overflows, for queues and topics.
- `scaling`: `{ "min": 2, "max": 20, "startup": 30 }`, the fewest and most copies it runs and
  the seconds a new copy takes to start.
- `latency`: seconds it takes to handle one request while it has room, such as `0.05`.
- `cost`: what one copy costs an hour, in dollars.

### Where the numbers are

Look in the code and its settings first: rate limits and quotas, autoscaling settings
(`minReplicas`, `maxReplicas`, desired counts, reserved concurrency), worker and thread pool
sizes, database connection pools, queue sizes and timeouts, instance sizes, load test results,
and SLOs in the docs.

Where they aren't there, estimate. Start from the people, work out what one person's action
sends down each line, and give capacity to the parts that can run out, so the map shows which
part gives first. Round the numbers, keep them believable next to each other, add
`"meta": { "Numbers": "Estimated" }` to parts whose numbers you made up, and tell the person
which ones they are.

## Notes, views, scenarios and stories

### Notes

A note is plain words on the canvas for people who weren't in the room: why the cache is there, a
known risk, what's about to change, or what the colours mean. One to four per map. Give it a
`zone` to sit with the parts it's about; left out, it sits under the map. `width` is from 160
to 640, and `style` colours it as for a part.

### Views

Every map has an "Everything" view. Add a view for each audience that needs its own:

- `audience`: `technical`, `non-technical`.
- `hide`: ids of parts, links, zones and notes it leaves out, such as caches, topics and
  libraries for people who don't build it.
- `collapse`: ids of zones it draws as one box.
- `wording`: other names and descriptions by id, in their words: "Ordering" for "Orders API".

A map that's shown beyond engineers should have a non-technical view.

### Scenarios

A scenario plays the map under load over time. Start from a ready-made one with `preset`:

- `normal-day`: Normal day. A day's rhythm up to today's busiest moment, to check the map copes with room to spare.
- `black-friday`: Black Friday. Doors open at midnight to 7 times today's peak, then a whole day at 4 times.
- `launch`: Product launch. Five times today's peak within 10 minutes of the announcement, with a long tail after.
- `tv-ad`: TV ad or push notification. Twenty times today's peak within 30 seconds, gone again in 5 minutes.
- `ticket-drop`: Ticket drop. Everyone arrives the minute tickets go on sale: fifty times today's peak.
- `outage`: Back after an outage. Nobody gets through for 5 minutes, then everyone comes back at once, with retries.
- `growth`: Steady growth. Traffic doubles over four weeks, with each day's rhythm on top.
- `quiet-night`: Quiet night. From 10pm to 6am, to see whether auto-scaling scales back in and what sits idle.
- `region-down`: Region down. The busiest region goes down for half an hour at the day's peak, to see what fails and what takes over.

Add `normal-day`, and the busy moment the business worries about, such as `black-friday` for a
shop, `launch` or `tv-ad` for a product, `ticket-drop` for sales that open at a set time. Add
`region-down` when the map has regions; Flozu aims it at the busiest one.

Anything you set beside `preset` wins over it, and without one, set at least `name` and
`duration`:

- `duration` in seconds (60 to four weeks), `start` (seconds after midnight), `rhythm`
  (`daily` follows a day's ups and downs, `flat` holds steady) and `level` (a multiple of a
  normal day's busiest moment).
- `events`, each at `at` seconds from the start:
  - `{ "kind": "spike", "at": 3600, "rise": 60, "hold": 900, "fall": 3600, "level": 5 }`: a
    sudden rush.
  - `{ "kind": "ramp", "at": 0, "over": 86400, "to": 2 }`: steady growth.
  - `{ "kind": "outage", "at": 600, "length": 300, "rush": 0.5, "fall": 600 }`: nobody gets in,
    then everyone comes back at once.
  - `{ "kind": "failure", "at": 1800, "length": 900, "target": { "components": ["orders-db"] },
    "mode": "down" }`: a part, line (`connections`, by link id) or `zone` goes `down`, or
    `degraded` with `keep` (0 to 1) of what it can take.
  - Spikes, ramps and outages reach every part traffic starts at, or only the ids in `entries`.
- `random`: `{ "spikes": 3, "level": [2, 4], "rise": [30, 120], "hold": [300, 900] }`, random
  spikes picked from `seed`. `noise`: wobble from 0 to 0.5. `headroom`: the busiest a part
  should run, from 0 to 1, such as 0.7.
- `components` and `connections`: multipliers by part id or link id, such as `{ "search": 3 }`.

### Stories

A story walks through the map like slides. Each step has a `title`, a sentence or two of
`text`, and `focus`: the ids of the parts, links, zones and notes it's about, which the camera
frames while the rest fades. A step can also show a moment of a scenario,
`"scenario": { "id": "black-friday", "at": 600 }` (seconds from its start), and show parts with
other limits on that step only, such as a fix: `"overrides": { "orders-db": { "flow": {
"capacity": 3000 } } }`.

Three to seven steps read best, up to 60. Follow the main journey from where traffic
starts, then end on what matters: the busy moment, the risk, or the fix.

## Projects, closer looks and mapping again

### Several repositories, one project

A product spread over several repositories reads best as a project: a folder holding a map of
each repository, and an overview map that ties them together.

1. Ask which repositories belong together, if the person hasn't said. Read each one where it is,
   on this computer.
2. Map each repository with `create_map`, all with the same `folder`: the project's name,
   such as "Shop". Keep the `mapId` each one gives back.
3. Draw the overview last: a part for each repository (a `service`, `client` or
   `worker` for what it runs as), the people who use them, the stores and outside services they
   share, and the links between them. Set each repository's part's `opens` to its map's
   `mapId`, so opening the part in Flozu goes into that map. Put it in the same folder.
4. Use the same names for the same things on every map, so people can follow them from map to map.

Without the MCP tools, write an outline for each repository and leave `opens` out: it needs
the ids of maps already in Flozu. Tell the person to link each part to its map with **Link a map**
in the part's **About** tab.

### A closer look at one part

When one part hides a system of its own, such as a service with many modules, map its insides as
a map of their own: its modules (`module`, `interface`, `library`), the stores it uses
and the services it calls. Then point the part at that map with `opens`. On a map that's
already there, that's a change: `component.update` with `"inside": { "mapId": "…" }`
through `change_map`.

### Mapping a repository again

Code changes, and its map should follow. Before you map a repository, call `list_maps` and look
for a map of it: by its name, and the `code` on its parts (`read_map`). If there is one,
never make a second map of it:

1. Read it with `read_map` and reuse its ids for every part, link and zone that's still
   there, so they change where they are. Keep the parts people added that still make sense, such
   as people and outside services.
2. Call `update_map` with the whole outline of the code as it is now. Flozu keeps where people
   moved things, the looks they chose, and their notes, views, scenarios and stories. Parts, links
   and zones the outline leaves out are taken away; new ones go beside what they link to.
3. It arrives as a proposal. Tell the person what changed, and that they can compare it with the
   map and adopt it in Versions. Nothing on the map changes until they do.

Every change you make to a map, with `update_map` or `change_map`, is a proposal like this.
Pass `direct: true` only when the person asked, in this chat, for the change to go straight
onto the map. Flozu then keeps a version of the map as it was first, so it can be undone.

## Check it

- Every id is unique, and everything named by id (`from`, `to`, `zone`, `parent`,
  `hide`, `focus`, scenarios) is in the outline. Give links an `id` when something names them.
- 8 to 40 parts, zones two or three levels deep, and every link something you saw in the code.
- Not everything looks the same: the parts that matter are bigger, the supporting ones slim,
  drawings fit what each part does, and colour has one meaning.
- Traffic starts somewhere (people with `flow.people`), lines carry uneven rates, and parts
  that can run out have a capacity. Estimates are marked.
- There's a story, a normal day and a busy scenario, and a non-technical view if people beyond
  engineers will see it.
- On a map made before, its ids still match, and it goes back with `update_map`.
- No secrets, keys, passwords, personal data or code. Names, paths and short descriptions only.

## The outline, field by field

- `outlineFormat`: always 2. (Format 1 outlines, with parts, links and zones
  only, still read.)
- `name`, `description`: the map's. `lineRoute`: `curved`, `square`, `straight`.
- `parts` (1 to 300): `id`, `name`, `kind` or `preset` or both, and
  optionally `description`, `technology`, `external`, `zone`, `code`, `meta` (short
  facts, such as `{ "Team": "Payments" }`), `layout` (`standard`, `showcase`, `wide`, `slim`), `size`
  (`small`, `standard`, `large`, `extra-large`), `drawing`, `style`, `flow` (`capacity`, `limit`,
  `buffer`, `scaling`, `people`, `latency`, `cost`) and `opens` (the id of
  a map already in Flozu that shows what's inside it).
- `links` (up to 1,000): `from`, `to`, and optionally `id`, `kind`
  (`request`, `message`, `uses`), `label`, `protocol`, `direction` (`forward` or
  `both`), `rate`, `unit`, `fromSide` and `toSide` (`left`, `right`, `top`,
  `bottom`), `style` (`stroke`, `strokeStrength`, `pattern`, `weight`, `effect`,
  `route`, `hidden`) and `standby`.
- `zones` (up to 100): `id`, `name`, and optionally `kind` (`zone`,
  `network`, `region`, `system`, `team`), `description`, `parent` and `style`.
- `notes` (up to 100): `text`, and optionally `id`, `zone`, `width` and
  `style`.
- `views` (up to 20): `name`, `audience`, and optionally `id`, `hide`,
  `collapse` and `wording`.
- `scenarios` (up to 20): `preset`, or `name` and `duration`, and
  optionally `id`, `description`, `start`, `rhythm`, `level`, `events`, `random`,
  `seed`, `noise`, `headroom`, `components` and `connections`.
- `stories` (up to 20): `name`, `steps` (1 to 60: `title`,
  and optionally `id`, `text`, `focus`, `scenario` and `overrides`), and optionally
  `id`.

Ids use letters, digits, `_` or `-`, and are shared by everything in the outline. The ids
become the map's own, so you can change the map later by the same names. Names are up to 120
characters, descriptions up to 2,000.

## A full example

```json
{
  "outlineFormat": 2,
  "name": "Shop backend",
  "description": "How an order travels from the shop's website to the warehouse.",
  "lineRoute": "square",
  "zones": [
    {
      "id": "aws",
      "kind": "region",
      "name": "AWS eu-west-1"
    },
    {
      "id": "core",
      "kind": "system",
      "name": "Orders",
      "parent": "aws"
    }
  ],
  "parts": [
    {
      "id": "shoppers",
      "kind": "person",
      "name": "Shoppers",
      "layout": "showcase",
      "drawing": "around-the-world",
      "flow": {
        "people": {
          "busiest": 12000,
          "typical": 4000,
          "quietest": 300
        }
      }
    },
    {
      "id": "web",
      "kind": "client",
      "name": "Shop website",
      "technology": "Next.js",
      "code": "apps/web",
      "drawing": "checkout"
    },
    {
      "id": "orders-api",
      "kind": "service",
      "name": "Orders API",
      "technology": "Go",
      "zone": "core",
      "code": "services/orders",
      "description": "Takes orders, checks the cart and charges the card.",
      "size": "large",
      "style": {
        "stroke": "blue"
      },
      "flow": {
        "capacity": 150,
        "scaling": {
          "min": 2,
          "max": 12
        },
        "latency": 0.08,
        "cost": 0.1
      }
    },
    {
      "id": "cart-cache",
      "preset": "redis-cache",
      "name": "Cart cache",
      "zone": "core",
      "layout": "slim"
    },
    {
      "id": "orders-db",
      "preset": "postgresql",
      "name": "Orders DB",
      "zone": "core",
      "drawing": "transactions"
    },
    {
      "id": "order-events",
      "kind": "topic",
      "name": "Order events",
      "technology": "SNS",
      "zone": "aws",
      "layout": "slim"
    },
    {
      "id": "packer",
      "kind": "worker",
      "name": "Packing worker",
      "technology": "Go",
      "zone": "aws",
      "code": "services/packer",
      "drawing": "delivery",
      "flow": {
        "capacity": 20,
        "buffer": 5000
      }
    },
    {
      "id": "stripe",
      "preset": "stripe",
      "name": "Stripe",
      "layout": "slim"
    }
  ],
  "links": [
    {
      "id": "visit",
      "from": "shoppers",
      "to": "web",
      "label": "Browse and buy",
      "rate": 400,
      "unit": "req/s"
    },
    {
      "id": "place",
      "from": "web",
      "to": "orders-api",
      "label": "Place order",
      "protocol": "HTTPS",
      "rate": 60,
      "unit": "req/s",
      "style": {
        "stroke": "blue",
        "weight": "bold"
      }
    },
    {
      "from": "orders-api",
      "to": "cart-cache",
      "label": "Read cart",
      "protocol": "RESP",
      "rate": 120
    },
    {
      "from": "orders-api",
      "to": "orders-db",
      "label": "Save order",
      "protocol": "SQL",
      "rate": 60,
      "style": {
        "stroke": "blue",
        "weight": "bold"
      }
    },
    {
      "from": "orders-api",
      "to": "stripe",
      "label": "Charge card",
      "protocol": "HTTPS",
      "rate": 12
    },
    {
      "from": "orders-api",
      "to": "order-events",
      "label": "Order placed",
      "rate": 12,
      "unit": "msg/s"
    },
    {
      "from": "order-events",
      "to": "packer",
      "label": "Pack it",
      "rate": 12,
      "unit": "msg/s"
    }
  ],
  "notes": [
    {
      "text": "Card details go straight to Stripe. The Orders API only keeps Stripe's payment id.",
      "zone": "core"
    }
  ],
  "views": [
    {
      "id": "business",
      "name": "Business overview",
      "audience": "non-technical",
      "hide": [
        "cart-cache",
        "order-events"
      ],
      "wording": {
        "orders-api": {
          "name": "Ordering",
          "description": "Where every order is taken and paid for."
        },
        "packer": {
          "name": "Warehouse"
        }
      }
    }
  ],
  "scenarios": [
    {
      "id": "normal",
      "preset": "normal-day"
    },
    {
      "id": "black-friday",
      "preset": "black-friday"
    }
  ],
  "stories": [
    {
      "id": "order-tour",
      "name": "How an order travels",
      "steps": [
        {
          "title": "Shoppers arrive",
          "text": "Up to 12,000 people shop at once on a normal evening.",
          "focus": [
            "shoppers",
            "web",
            "visit"
          ]
        },
        {
          "title": "The order is placed",
          "text": "The Orders API reads the cart, saves the order and charges the card.",
          "focus": [
            "orders-api",
            "cart-cache",
            "orders-db",
            "stripe"
          ]
        },
        {
          "title": "Packing starts",
          "text": "An event tells the warehouse to pack it, so the shopper never waits for that.",
          "focus": [
            "order-events",
            "packer"
          ]
        },
        {
          "title": "On Black Friday",
          "text": "Seven times the traffic at midnight. The API scales out; the database is the part to watch.",
          "focus": [
            "orders-api",
            "orders-db"
          ],
          "scenario": {
            "id": "black-friday",
            "at": 600
          }
        }
      ]
    }
  ]
}
```