# Flozu documentation

> Map how your systems connect, watch traffic move through them, and test what happens on your busiest day.

![The Flozu editor showing a shop's checkout: people, a web shop, an orders API, a database, payments and background jobs, with traffic moving along the lines.](https://docs.flozu.app/_astro/editor-light.zNB3jwva_wPVX1.webp)

## Where do you want to start?

- [I'm new here](https://docs.flozu.app/start/quick-start.md): Draw a small map, give it some traffic and test it on Black Friday, in five minutes.
- [Will our system cope?](https://docs.flozu.app/walkthroughs/black-friday.md): Play your busiest day on the map, find the part that falls behind first, and size the fix.
- [What if something breaks?](https://docs.flozu.app/walkthroughs/what-if-it-breaks.md): Take a database or a whole region down, see who notices, and prove the fix before you build it.
- [I need to explain it](https://docs.flozu.app/walkthroughs/explain-it.md): Walk a new starter, a client or your manager through the live map, one step at a time.
- [Map my code](https://docs.flozu.app/guides/map-your-code.md): Have Claude read a repository and draw the map for you.
- [Start from an example](https://docs.flozu.app/guides/templates.md): Open a real-looking system, from a static site to a delivery platform, and press play.

## What makes it different

A diagram shows boxes and arrows. A Flozu map also knows the numbers behind them: how much traffic each line carries, and how much each part can take. That’s enough to answer the questions a diagram can’t.

### Draw your system

Add parts from 28 kinds and 117 presets, connect them, and group them into zones. [Build a map](https://docs.flozu.app/guides/parts.md)

### Watch it live

Traffic moves along every line, and each part shows what it’s doing. Colour only shows up when something needs your attention. [Traffic and limits](https://docs.flozu.app/guides/traffic-and-limits.md)

### Test your busiest day

Run Black Friday, a launch or an outage over a day, and see which part runs short first and what fixes it. [Scenarios](https://docs.flozu.app/guides/scenarios.md)

### Explain it to anyone

Present the map read-only, walk people through it with a story, or send a link that holds the whole map. [Present and share](https://docs.flozu.app/guides/presenting-and-sharing.md)

---

# What is Flozu?

> Flozu is a canvas for mapping how a company's systems connect, and for showing how traffic moves through them.

At midnight on Black Friday the shop slowed to a crawl, and by morning nobody could say why. The architecture diagram on the wiki showed every box and arrow, but not which box ran out of room first. That’s the question Flozu answers, before the day comes.

Flozu is a canvas for mapping how systems connect. You draw your infrastructure (the parts, how they connect and what flows between them) and Flozu brings it to life: traffic moves along the lines, and each part shows when it’s busy, backing up or turning traffic away.

![A checkout system drawn in Flozu: shoppers, a web shop and an orders API in an AWS region, sending to a database, a payments service and a background jobs zone.](https://docs.flozu.app/_astro/map-light.bQE_NUvi_Z2jmy8q.webp)

## Who it’s for

Flozu is made for tech companies that want to explain their own systems:

- **To clients**, who should see your rates and limits but not change anything.
- **To new developers**, who need to know what talks to what before they read any code.
- **To people who aren’t technical**, who want to know why the site slowed down on Black Friday.
- **To yourself**, before a launch, to find the part that runs out of room first.

## What makes a map more than a diagram

A diagram shows boxes and arrows. A Flozu map also knows the numbers behind them: how much traffic each line carries, and how much each part can take. Say your orders API handles 400 orders a second and gets 40 on a normal day. On Black Friday it gets about 290: Flozu marks it tight, and says how much more room it needs.

![The checkout map on Black Friday at ten past midnight: traffic on every line, the Orders API 72% busy in amber, the email worker 438% overloaded in red, and the timeline along the bottom saying 2 parts need room.](https://docs.flozu.app/_astro/black-friday-map-light.Dh3wsS-m_1QtJLi.webp)

From those numbers it can:

- **Show the map live.** Dots travel along each line, closer together on busier ones, and each part’s panel moves with what it does.
- **Test a scenario.** Play Black Friday over a whole day and see which part is the first to run short, for how long, and what would fix it.
- **Pull the plug.** Take a part or a whole region down in a scenario, and see what fails, what takes over and how many people notice. See [failure drills](https://docs.flozu.app/guides/failure-drills.md).
- **Tell a story.** Walk people through the map one step at a time, each step framing the parts it’s about, with the load at that moment.
- **Zoom into a part.** Give a service a map of its own, its modules and what they call, and open it from the card, so a set of maps reads as one picture.

Flozu never runs your systems or reads from them. The motion comes from the numbers on the map, so it works the same on a laptop with no connection as it does in front of a client.

## How it’s put together

Everything you draw is one **map**: parts, the lines between them, zones around them and notes beside them. Maps are saved in your [account](https://docs.flozu.app/guides/accounts.md), where your [team](https://docs.flozu.app/guides/teams.md) can open them too, or in your browser as a guest, or as files in the Mac app. To move maps somewhere else, export them as a file, a whole project at a time if you like, or as a picture for a slide. To show it to someone, share a link that carries the map inside it.

- [Quick start](https://docs.flozu.app/start/quick-start.md): Make your first map in five minutes.
- [The map](https://docs.flozu.app/concepts/the-map.md): Parts, lines, zones and notes, and how they fit together.

---

# Quick start

> Make your first map, connect it, give it some traffic and test it on Black Friday, in about five minutes.

This page takes you from an empty map to one you’ve tested on Black Friday. If you’d rather look around first, open a [template](https://docs.flozu.app/guides/templates.md) instead.

## Make a map

1. Open Flozu. You land on **home**: one box with your latest maps and the ways to start one.

2. Select **New map**. A blank map opens in the editor, with the parts library on the left and the inspector on the right.

   > **Tip**
   >
   > On an empty map, **Open an example** draws a shop’s checkout for you to look around.

3. Give the map a name. With nothing selected, the inspector shows the map itself: type its name under **About**.

## Add parts

1. Press `P` with the pointer over the canvas. A **Person** appears where the pointer is. Every kind of part has a key like this, shown beside it in the library.

2. Drag **Client app** from the library onto the canvas, to the right of the person.

3. Press `S` to add a **Service**, then `D` to add a **Database** to its right.

4. Double-click a part’s name to rename it. Call the service “Orders API” and the database “Orders DB”.

## Connect them

1. Drag from the port on the right edge of the person to the client app. Near another part’s port, the line snaps to it inside a soft orange ring, so you don’t have to hit the port exactly.

2. Connect the client app to Orders API, and Orders API to Orders DB.

3. From Orders API, drag a line out and let go on empty canvas. Flozu asks what comes next and suggests parts that usually follow a service. Pick **Queue**, and it’s added already connected.

![Dropping a line on empty canvas opens a small search, here narrowed to Cache by typing.](https://docs.flozu.app/_astro/quick-add-light.CjYtG6cl_1JhTVg.webp)

_Let go of a line on empty canvas, or double-click it, to add a part._

## Give it traffic

A map comes alive once it knows its numbers.

1. Select the line from the client app to Orders API. In the inspector’s **Traffic** tab, set its rate to 200 requests a second.

2. Select Orders API. In its **Traffic** tab, set its capacity to 400 a second: what it can process.

3. Press play on the island at the foot of the canvas if the map is paused. Dots now move along each line, closer together where there’s more traffic.

Why those numbers? 200 a second into a part that can take 400 means it’s half busy on a normal day: room to spare. The rate is always the busiest moment of a normal day, so a scenario can scale it up from there. You don’t need every number to start. The rates where traffic comes in and the capacity of the part you’re worried about are enough.

## Test it on Black Friday

1. Open the mode menu on the island at the foot of the canvas and choose **Scenario**.

2. In the scenario panel, pick **Black Friday**. Flozu plays a whole day with a rush at midnight and four times today’s traffic after it.

3. Read **What happens**. Orders API is outlined in red: just after midnight, nearly 1,500 requests a second arrive, and it can take 400. Under **Fix it**, Flozu says to give it about 2,100 a second, five times what it has, or run 6 copies.

4. Select **Apply** to make that fix, and the red outline goes. One undo takes it back.

![Black Friday running on the checkout map: the scenario panel lists two parts that need more room, the email worker is outlined in red, and a timeline runs along the bottom.](https://docs.flozu.app/_astro/scenario-light.D50hHthp_2r0uL7.webp)

## Next steps

- [Will it survive Black Friday?](https://docs.flozu.app/walkthroughs/black-friday.md) does the same on a fuller shop, where the part that breaks first isn’t the one you’d guess.
- [Take the tour](https://docs.flozu.app/start/tour.md) to learn what each part of the editor does.
- [Sort your maps into projects](https://docs.flozu.app/guides/your-maps.md) as you make more.
- [Present the map](https://docs.flozu.app/guides/presenting-and-sharing.md) to someone, or send them a link.

---

# A tour of the editor

> What each panel, button and tab in the Flozu editor does.

![The editor: the canvas fills the window, with Flozu's mark at the top left and the parts library in the panel under it, Help and the theme switch at the top right above the inspector, and the island of actions at the foot.](https://docs.flozu.app/_astro/editor-light.zNB3jwva_wPVX1.webp)

The canvas fills the window, and everything else floats over it. Flozu’s mark and the workspace you’re in sit at the top left, with the panel under them. Help and the theme switch sit in a small bar at the top right, with your usage and a button to connect an AI assistant once you’re signed in. The inspector floats on the right; the button at its top right folds it into a small box in the corner, and that box brings it back. The island at the foot holds everything you do to the map, and ends with the canvas menu.

The panel on the left shows the map’s own menu: **Add parts** shows the parts library in its place, and **Scenarios**, **Stories** and **Versions and proposals** open theirs there too, each with a way back. **Back to Menu** at its top goes to Flozu’s menu, where the map is the first row, to go back in. Fold the panel and it shrinks into a slim rail with the same buttons. See [getting around](#getting-around) for the rest of the panel.

A [map inside a part](https://docs.flozu.app/guides/maps-inside-parts.md) shows a trail at the top centre of the window: the maps above it, each a way back out.

## Getting around

Flozu has no bar across the top. The page or the canvas runs to the edges, and a few things float over it.

- **The top left** shows Flozu’s mark and the workspace you’re in: **My maps** for the maps on this device, or, once you’ve [signed in](https://docs.flozu.app/guides/accounts.md#workspaces), your own workspace and each of your [teams](https://docs.flozu.app/guides/teams.md). Choose it to switch.
- **The top right** has a small bar with [Help](https://docs.flozu.app/help/getting-help.md) and the button that switches between the light and dark themes, and once you’re signed in, your [usage](https://docs.flozu.app/guides/usage.md) and a button to [connect an assistant](https://docs.flozu.app/guides/connect-an-assistant.md). While you have maps open, a page with how many comes first, and lists them, to [move between them](https://docs.flozu.app/guides/your-maps.md#open-maps) from anywhere.
- **The panel** down the left is one panel you move through. It’s only as tall as what it shows. Away from a map it shows the **menu**: **Home**, **Projects** and **Templates**, then **Open**, the maps you have open, and **Recent**, the maps you changed last. The top of every level keeps **Home**, **+** for a new map, a new project or an import, and the fold, however far in you’ve gone. Home and Templates open their pages; Projects shows your projects in the panel’s place, with **Back to Menu** at the top.
- **In a map** the panel shows that map’s own menu: **Add parts**, **Scenarios**, **Stories**, **Versions and proposals** and **Maps inside**, then **Present** and **Map settings**. Every level below works the same way: its name at the top, and one way back above it, named for the level above. **Scenarios** lists the map’s scenarios, then one scenario, then a part of it such as its Moments; **Stories** lists the stories, then one story’s steps. The map’s menu has **Back to Menu** at its top, and the menu has the map as its first row, to go back in. Going deeper slides in from the right, and going back from the left. The mode menu at the foot of the canvas opens the same things in the same place. `Esc` goes back one step too.
- **Fold the panel** with the button at its top right to give the page or the canvas the room. It shrinks into a slim rail of buttons under Flozu’s mark: the first brings the panel back, and the others go straight to a place, such as the parts, the scenarios or your projects. Flozu remembers your choice for maps and for the other pages separately.

On a phone, the rail runs along the bottom of the screen, and its buttons slide the panel over the page; pressing the same button again slides it away. On a phone or a window narrower than 1,100 pixels, the panel and the inspector take turns, so they never lie over each other or squeeze the map.

## The parts library

The library on the left has two shelves. **Parts** holds the plain kinds of part, each with the key that adds it. **Presets** holds parts ready to go, such as a Redis cache or Stripe payments. Drag one onto the canvas, or click it to add it in the middle of the screen. Press `/` to search both shelves at once.

The scenario, versions and stories panels open in the library’s place, and showing the parts again closes them.

## The canvas

The canvas is a grid you can pan and zoom. Drag on empty canvas or scroll to pan, pinch (or hold `Ctrl` or `⌘` while scrolling) to zoom, and drag across empty canvas with `Shift` held to select several things at once.

- Double-click empty canvas to search for a part and add it there.
- Drag from a part’s right port to draw a line.
- Hover a line and select its plus to put a part on it.
- Double-click a name to rename it in place.

## The island

The island floats at the foot of the canvas and holds what you do to the map:

| Control       | What it does                                                                         |
| ------------- | ------------------------------------------------------------------------------------ |
| Play or pause | Start or stop the traffic.                                                           |
| Mode menu     | Pick what you’re doing. It opens upward, and only one mode runs at a time.           |
| **Actions**   | Share, export, show or hide the panels, and the map’s settings.                      |
| Zoom level    | Opens the [canvas menu](#the-canvas-menu): undo and redo, zoom, fit and full screen. |

The mode menu offers:

| Mode         | What it does                                                                                                                       |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Edit**     | Build and change the map. This is where a map opens.                                                                               |
| **View**     | [Present the map](https://docs.flozu.app/guides/presenting-and-sharing.md), read-only.                                             |
| **Scenario** | [Try a scenario](https://docs.flozu.app/guides/scenarios.md), such as Black Friday, with its timeline along the bottom.            |
| **Story**    | Open the map’s [stories](https://docs.flozu.app/guides/stories.md), with a story’s steps along the bottom in the timeline’s place. |
| **Versions** | Look back through the map’s [versions and proposals](https://docs.flozu.app/guides/versions-and-proposals.md).                     |

The **Actions** menu offers:

| Action            | What it does                                                                                               |
| ----------------- | ---------------------------------------------------------------------------------------------------------- |
| **Share a link…** | [Share a link](https://docs.flozu.app/guides/presenting-and-sharing.md#share-a-link) that carries the map. |
| **Export…**       | [Export the map](https://docs.flozu.app/guides/import-export.md) as a picture, a PDF or a file.            |
| **Map settings…** | [Rename or delete the map](#map-settings).                                                                 |

![The island's Actions menu open above it: Share a link, Export and Map settings.](https://docs.flozu.app/_astro/actions-light.Cri_Eh53_ZD5vmU.webp)

Notices, such as “Saved as a copy”, float just above the island.

## Map settings

Choose **Map settings…** from the **Actions** menu to rename the map or delete it. A new name is one change you can undo. **Delete map…** asks first and offers to export a copy, then closes the map. Its versions and proposals go with it; maps that open from its parts stay. Who can see a map follows the workspace it’s in: move it into a [team](https://docs.flozu.app/guides/teams.md#share-a-map-with-the-team) to share it.

![The Map settings window: the map's name, and a section to delete the map.](https://docs.flozu.app/_astro/map-settings-light.BtFqXxua_ZaJNpS.webp)

## The canvas menu

The zoom level at the end of the island opens the canvas menu, which holds what’s about the canvas rather than the map:

| Control                           | What it does                                                          |
| --------------------------------- | --------------------------------------------------------------------- |
| Undo and redo                     | Take back a change, or put it back. `⌘Z` and `Shift``⌘Z` do the same. |
| Zoom out, the zoom level, zoom in | Step the zoom. Select the level to go back to 100%.                   |
| **Fit the map to the screen**     | Frame the whole map.                                                  |
| **Full screen**                   | Fill the screen, where the browser allows it.                         |
| **Scrolling**                     | **Moves the canvas** or **Zooms**.                                    |

The menu stays open while you use it, so you can step the zoom; press `Esc` or click elsewhere to close it.

![The canvas menu open above the island: undo and redo, the zoom with its level, Fit the map to the screen, Full screen, and Scrolling with Moves the canvas ticked.](https://docs.flozu.app/_astro/canvas-menu-light.CUFJQen3_8DWWE.webp)

Scrolling, such as two fingers on a trackpad, moves around the canvas. If you’d rather it zoomed, choose **Zooms** under **Scrolling**. Flozu remembers the choice in this browser.

The theme switch, at the top right of every screen, swaps between the light and dark themes.

## The inspector

The inspector edits whatever is selected. With nothing selected, it shows the map: its name and notes under **About**, and under **Guide**, how to read the map and the keys that build it.

Its tabs split each thing’s settings so the panel never becomes one long scroll:

| Selected | Tabs                                                                                                                                                                                                                                              |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A part   | **About** (at a glance, then name, kind, technology, who runs it, notes), **Look** (size, card, drawing, style), **Traffic** (how it copes, limits and auto-scaling), **Lines** (how many come in and go out, then each line and what it carries) |
| A line   | **About** (what it carries, direction, label, protocol), **Look** (style, effect, route and ends), **Traffic** (rate)                                                                                                                             |
| A zone   | **About** (name, kind, notes), **Look** (style), **Inside** (what it holds)                                                                                                                                                                       |
| A note   | **About** and **Look**                                                                                                                                                                                                                            |
| The map  | **About** (name, how its lines run), **Guide**                                                                                                                                                                                                    |

Flozu remembers the tab you picked for each kind of thing, so clicking from one part to the next stays on the same tab. The arrow keys move between tabs, and actions such as **Delete part** stay at the foot of every tab, below a line. A delete asks first: the button turns red, and pressing it again within three seconds deletes. Otherwise it goes back on its own.

A part’s **About** tab starts with it at a glance: what comes in each second, how busy it is and how many lines it has, on a normal day or at its busiest in the scenario running. Choose one to open the tab it comes from. Each group of fields sits in its own card.

![The inspector for a service called Orders API, on its About tab: at a glance, 40 a second in, 10% busy and 4 lines; then its name, kind, technology, who runs it and notes.](https://docs.flozu.app/_astro/inspector-about-light.B3kXzWvu_Z2t0r3W.webp)

Its **Lines** tab counts the lines in and out, with a bar coloured by what each carries, then lists them with their label and what they carry each second. Choose one to select it.

![The Lines tab for Orders API: 1 line in and 3 out, 104 a second out, a bar of three requests and one message, then each line with its label and rate.](https://docs.flozu.app/_astro/inspector-lines-light.D_9fEwCx_meQeO.webp)

## Small screens

On a narrow window the library and inspector start hidden, so the canvas keeps its room. The library hides below 1,200 pixels wide and the inspector below 760. **Add parts** in the map’s menu, or the box at the top right, brings either back. Below 1,100 pixels only one side panel stays out at a time: showing the inspector folds the panel on the left, and bringing the panel back folds the inspector. On a phone the rail lies along the bottom of the screen, its buttons slide the panel in over the map, and pinching zooms the canvas.

---

# Get Flozu

> Use Flozu in your browser at my.flozu.app, run it from its source on your own computer, or install the Mac app.

Flozu runs in any modern browser and as a Mac app. Both are the same app: what works in one works in the other.

## In your browser

Open [my.flozu.app](https://my.flozu.app/) in a current version of Chrome, Edge, Firefox or Safari. [Sign in](https://docs.flozu.app/guides/accounts.md) with Google or GitHub to keep your maps in your account and open them anywhere, or continue as a guest to keep them in this browser.

> **Note**
>
> Flozu is in a private beta, so signing in works for invited addresses only. Anyone can continue as a guest.

## From the source

To run Flozu on your own computer from its source, you need access to its repository, [Node.js](https://nodejs.org) 22.23.4 or later and pnpm 10. Run this way, nobody signs in, and your maps are saved in the browser you use.

- **macOS and Linux**

  ```sh
  corepack enable          # once, to get the pnpm version Flozu uses
  git clone https://github.com/flozu-app/flozu.git
  cd flozu
  pnpm install
  pnpm dev                 # opens Flozu at http://localhost:5173
  ```

- **Windows**

  ```powershell
  corepack enable
  git clone https://github.com/flozu-app/flozu.git
  cd flozu
  pnpm install
  pnpm dev
  ```

If your Node doesn’t include Corepack, `npm install -g pnpm` works too.

## The Mac app

The Mac app is Flozu in its own window, with a menu bar, and each map saved as a file you can see in Finder. See [the Mac app](https://docs.flozu.app/mac/overview.md) for what it adds and how to get it.

---

# Will it survive Black Friday?

> Play Black Friday on a shop's checkout, find the part that falls behind first, size the fix and prove it works, in about ten minutes.

Your shop copes on a normal Tuesday. On Black Friday, seven times as many people arrive at midnight, and four times as many stay all day. Something will run out of room first. This walkthrough finds out what, by how much, and what to change, before the day comes.

You’ll use the **Checkout system** template: shoppers, a web shop, an orders API, a database, card payments, and a worker that sends the confirmation email.

## 1. Open the checkout

1. Open **Templates** and find **Checkout system**. Select **Use template**. A copy opens in the editor, so nothing you change here touches the template.

2. Press play if the map is paused. Dots move along each line, closer together where there’s more traffic.

![The Checkout system map: Shoppers and the web shop on the left, then an AWS region holding the Orders API, the Orders DB and a background jobs zone with Order events and the Email worker, and Stripe payments above.](https://docs.flozu.app/_astro/map-light.bQE_NUvi_Z2jmy8q.webp)

The map already has its numbers. Select a few things to see them in the inspector’s **Traffic** tab:

| What                  | On a normal day     | It can take    | So it’s  |
| --------------------- | ------------------- | -------------- | -------- |
| Web shop → Orders API | 40 orders a second  |                |          |
| Orders API            | 40 a second         | 400 a second   | 10% busy |
| Orders DB             | 80 queries a second | 1,000 a second | 8% busy  |
| Email worker          | 12 emails a second  | 20 a second    | 60% busy |

Every part has room to spare. The Email worker has the least: 60% busy before anything unusual happens. Keep an eye on it.

## 2. Play Black Friday

1. Open **Scenarios** and pick **Black Friday**. A timeline appears along the bottom, and the map shows the busiest moment.

2. Read the card at the top of **What happens**: two parts need more room.

3. Look at the canvas. The Email worker is outlined in red, and its strip says it’s over.

![Black Friday running on the checkout map: the scenario panel lists two parts that need more room, the email worker is outlined in red, and a timeline runs along the bottom.](https://docs.flozu.app/_astro/scenario-light.D50hHthp_2r0uL7.webp)

Here’s what happened at ten past midnight, the busiest moment:

| Part         | Arrives            | It can take    | Busy | What Flozu says                              |
| ------------ | ------------------ | -------------- | ---- | -------------------------------------------- |
| Orders API   | about 290 a second | 400 a second   | 72%  | **Tight**: past the 70% it should stay under |
| Email worker | about 88 a second  | 20 a second    | 438% | **Over**: it can’t keep up                   |
| Orders DB    | about 580 a second | 1,000 a second | 58%  | Fine                                         |

The Email worker is tight from the first minute and over by the second. That’s the part that breaks first.

> **Note**
>
> Shoppers don’t notice the Email worker falling behind. The line into it is a dashed message line: the order is placed and the shopper moves on, and the email is sent afterwards. What they’d notice is their confirmation email arriving late, or not at all. If the Orders API ran over, they’d notice straight away, because they wait for its answer.

## 3. Watch it happen

Drag the playhead along the timeline, or press `Space` to play the day in about 30 seconds. The red line along the top of the timeline marks the stretch where a part is over. **Moments** in the panel lists when things change: the Email worker gets tight at 00:00, runs over at 00:02, and the busiest moment is 00:10.

![The timeline for Black Friday: a curve of traffic across the day from 00:00 to 24:00, marked red along the top where parts need room, with the playhead at 00:10.](https://docs.flozu.app/_astro/timeline-light.B5yrEedO_ZNuc2f.webp)

## 4. Fix it

Under **Fix it**, each part that needs room comes with the fix that would let it cope:

- **Email worker:** give it 126 a second, 6.3 times what it has, or run 7 copies.
- **Orders API:** give it 417 a second, 5% more than it has, or run 2 copies.

Flozu sizes each fix so the part stays under 70% busy at its worst moment, leaving room for a surprise.

![What happens for Black Friday: a card saying 2 of 3 parts need room with a coloured bar and the outcome, then Fix it with each part that needs more room and its fix.](https://docs.flozu.app/_astro/needs-more-room-light.tXuLJjeI_2dF7W7.webp)

1. Select **Apply** beside each fix. Each is one change you can undo. (**Try it** makes the fix in a proposal instead, so you can compare before you commit. The [next walkthrough](https://docs.flozu.app/walkthroughs/what-if-it-breaks.md) uses it.)

2. Watch the canvas: the red outline goes, and the card at the top of **What happens** says everything copes. At the busiest moment the Orders API is now 70% busy and the Email worker 69%.

Not sure 126 is right? Select the Email worker and choose **Try other capacities** in its **Traffic** tab. Tiles show how busy each round number would make it, on Black Friday and on a normal day, so you can see what a smaller fix would leave you with.

![Trying other capacities for Email worker during Black Friday: tiles from 20 to 200 a second filled from red to green, 150 picked, and a slider marking healthy from 126 a second.](https://docs.flozu.app/_astro/try-capacity-light._ndGs3U3_SuvPi.webp)

## 5. Keep it

1. Choose **Save with the map** in the scenario panel. Black Friday now travels with the map, in files and share links, and you can come back to it after the next change.

2. To show someone, choose **Share a link…** from the **Actions** menu. Whoever opens it can play Black Friday too.

![The scenario panel after both fixes are applied: 0 of 3 parts need room, 69% at the busiest, and all 3 checked parts cope on Black Friday, with Save with the map at the top.](https://docs.flozu.app/_astro/black-friday-fixed-light.CnoOx8xn_ZREtCj.webp)

## What you learned

- **Rates live on lines and limits on parts.** That’s all a scenario needs to work out who runs short. See [traffic and limits](https://docs.flozu.app/guides/traffic-and-limits.md).
- **The first part to break isn’t always the obvious one.** The Orders API looked like the bottleneck, but the Email worker had the least room to start with.
- **Message lines hide problems from shoppers,** which is good for them and easy to miss for you.

## Next

- [What if something breaks?](https://docs.flozu.app/walkthroughs/what-if-it-breaks.md) takes a part down on the same map.
- [Scenarios](https://docs.flozu.app/guides/scenarios.md) covers making your own, from a TV ad to steady growth.

---

# What if something breaks?

> Take a shop's database down, then its whole cloud region, see who notices, and try the fix in a proposal before you change anything.

Every system has a part it can’t do without. Most teams find out which one during an outage. This walkthrough finds it on purpose: you’ll pull the plug on a database, then on a whole cloud region, see how many people notice, and test the fix without touching the map.

You’ll use the **Checkout system** template, as in [Will it survive Black Friday?](https://docs.flozu.app/walkthroughs/black-friday.md). Open it from **Templates** with **Use template**, or carry on with the copy you made there.

> **Note**
>
> Flozu never touches your real systems. A drill is worked out from the lines and parts on the map, by fixed rules, so it plays the same way every time.

## 1. Take the database down

You break things inside a scenario, so start one first.

1. Open **Scenarios** and pick **Normal day**. Drag the playhead to about 20:00, the busiest part of the day.

2. Right-click **Orders DB** on the canvas and choose **Take down here**. It goes down at the playhead, for ten minutes.

![Right-clicking Orders DB on the canvas opens a menu with Take down here.](https://docs.flozu.app/_astro/take-down-light.DlzO3A8y_ZDxO17.webp)

## 2. See who notices

The Orders DB fades behind a dashed red outline. The line into it turns red, and its dots fade out before they arrive. Shoppers and the web shop show **33% fail** on their strips.

![The checkout map with Orders DB down: its card faded behind a dashed red outline marked Down, the SQL line into it red, Shoppers and the web shop showing 33% fail, and the panel saying up to 33% of Shoppers' traffic fails for 10 minutes.](https://docs.flozu.app/_astro/orders-db-down-light.qCEqZ1eO_1xFWCP.webp)

Why a third? Shoppers make 120 requests a second. 40 of those place an order, and every order is saved in the Orders DB. The other 80 are people browsing, which the web shop handles on its own, so they carry on as if nothing happened.

The panel’s summary says it in one sentence: up to 33% of Shoppers’ traffic fails, for 10 minutes. Open **Blast radius** to see what the failure touched and how much failed in all: about 24,000 requests.

> **Tip**
>
> A failure travels back along request lines, because the caller is waiting for an answer. Along a message line, only a send that fails on the spot counts, such as to a topic that’s down. Work that gets stuck further on never reaches the shopper: take the Email worker down for ten minutes, and Order events holds the emails until it’s back, without failing a single order.

## 3. Try the fix in a proposal

**Fix it** now starts with how to survive this. Nothing takes over when the Orders DB goes down, so it’s a **single point of failure**, and the fix is a change to the map’s shape: a standby copy of the database beside it.

1. Select **Try it** beside the fix. Flozu starts a [proposal](https://docs.flozu.app/guides/versions-and-proposals.md): a copy of the map with the standby database added, opened at the same moment of the same scenario.

2. Look at the top left. It says **Copes now**: with the standby, nobody notices the database going down.

3. The map itself hasn’t changed. Choose **Adopt** at the end of the island to make the proposal the map, or leave it for now.

## 4. Take a whole region down

A single database is one thing. What if everything in AWS eu-west-1 goes dark?

1. Go back to the map, open **Scenarios** and pick **Region down**. It takes the map’s busiest region down for half an hour at the day’s peak.

2. Everything in the region is dashed in red and marked **Down**. The summary says: when AWS eu-west-1 goes down, up to 33% of Shoppers’ traffic fails, for 30 minutes. That’s about 72,000 requests.

![Region down on the checkout map: the AWS eu-west-1 region and everything in it are dashed in red and marked Down, Shoppers and the web shop show 33% fail, the panel says up to 33% of Shoppers' traffic fails for 30 minutes, and the timeline marks the half hour it's down.](https://docs.flozu.app/_astro/failure-drill-light.Begv5NG0_eIzt8.webp)

The fix this time is a **second zone**: a copy of the region, with a copy of everything in it, standing by. Select **Try it** again, and the proposal says **Copes now**.

![A proposal with a standby copy of AWS eu-west-1 below the region that's down: the copy carries the traffic, the panel says nobody notices, and the top left says Copes now beside the proposal's name.](https://docs.flozu.app/_astro/proposal-verdict-light.Cly_0Ch9_VntVv.webp)

## 5. Find the weak spots you didn’t think of

You picked the database because it seemed risky. Flozu can check every part instead.

1. In any scenario, open **Weak spots** under **What happens** and select **Find weak spots**.

2. Flozu takes each part and zone down in turn, for an hour at the busiest moment, and lists them by how much fails.

![Weak spots on the checkout map: losing the web shop fails all of Shoppers' traffic, and AWS eu-west-1, Orders API and Orders DB each fail up to 33% of it, each with Drill this.](https://docs.flozu.app/_astro/weak-spots-light.GK3l50o8_ZmEqUR.webp)

The worst one isn’t in the cloud at all. Losing the **web shop** fails every request, because everything goes through it. The region, the Orders API and the Orders DB come next at a third each, then Payments and Order events at a tenth. **Drill this** adds that failure to the scenario so you can watch it play.

## What you learned

- **Who notices depends on the lines.** Requests carry a failure back to the people waiting; messages only carry back a send that fails on the spot.
- **A single point of failure needs a change of shape,** not more capacity: a standby copy, a second zone, or a queue in front.
- **Proposals let you prove a fix first.** The map only changes when you adopt.

## Next

- [Make the case for a fix](https://docs.flozu.app/walkthroughs/make-the-case.md) turns this proposal into something to show your team.
- [Failure drills](https://docs.flozu.app/guides/failure-drills.md) covers degraded parts, cut lines and every kind of fix.

---

# Explain your system to someone new

> Turn a scenario into a story that walks a new starter, a client or your manager through the map one step at a time, then present it or send it as a link.

A new developer joins on Monday. They need to know what talks to what, and why the email worker is the part everyone worries about, before they read any code. A diagram on a wiki won’t tell them that. A story will: it walks them through the live map one step at a time, like slides, with each step framing the parts it’s about and the load at that moment.

This walkthrough makes a story from the Black Friday scenario on the **Checkout system** map, rewrites it for a newcomer, and presents it.

## 1. Start from a saved scenario

A story can stop at moments in a scenario, so the map needs one saved. If you did [Will it survive Black Friday?](https://docs.flozu.app/walkthroughs/black-friday.md), it has one. Otherwise:

1. Open **Scenarios**, pick **Black Friday**, and choose **Save with the map**.

## 2. Draft the story

1. Open **Stories**. Because the map has a saved scenario, it offers to draft a story from it. Choose **From Black Friday**.

2. Flozu writes six steps: the whole map at the start, one for each moment worth stopping at (the Email worker getting tight, then running over, the busiest moment and the quietest), and a last step called **With more room** that shows the fixes the scenario suggests.

![The stories panel listing a Black Friday story's six steps, from the whole map at 00:00 to With more room, and the first step's card below the map with its title and words as fields, and buttons for its moment, framing and More.](https://docs.flozu.app/_astro/stories-light.BnTqS7jP_24hwb.webp)

It’s all one step to undo, and a draft to change. The **With more room** step shows the fixes on that step only: the map itself keeps its numbers.

## 3. Write it for your audience

The draft’s words say what happens. A newcomer also needs to know why it matters. Pick a step, and type straight into its card below the map: the card is what people see when you present.

For the step where the Email worker gets tight, the draft says what the numbers do. You might write instead:

> **The email worker is the first to struggle.** After every order, we send a confirmation email in the background. On a normal day this worker is already 60% busy, so a rush at midnight pushes it over within two minutes. Shoppers don’t wait for it, so they don’t notice. Their emails just arrive late.

1. Add a step of your own before the rush. Pick the first step, select **Orders API** and **Orders DB** on the canvas, then choose **Add a step**. It goes after the step you’re on, framing what’s selected.

2. Give it a title such as “Where an order goes”, and a sentence or two: “Every order goes through the Orders API, which charges the card with Stripe, then saves the order in PostgreSQL.”

3. Move steps up and down, or delete them, from their menus.

![A story step being edited: the camera framed on Orders API and Orders DB, everything else faded, and the step's card below the map reading Where an order goes, step 2 of 7.](https://docs.flozu.app/_astro/story-step-light.zgd8Agkb_Z1pVrTB.webp)

> **Tip**
>
> Good steps say one thing each. Frame one to three parts, give the step a moment when the load matters, and write the words for the person listening, not for you.

## 4. Present it

1. Choose **View** from the mode menu at the foot of the canvas. The map is now read-only, so nothing moves by accident.

2. Choose **Story**. The steps take the timeline’s place along the foot, and the camera glides to the first one.

3. Move through it with **Next** and **Back**, the arrow keys, or a presentation clicker (they send `Page Up` and `Page Down`). `Esc` leaves the story.

![A story playing: the camera framed on the email worker, outlined in yellow with its strip reading 84% Busy, with the story's steps along the foot reading Step 2 of 6, Email worker gets tight, Black Friday at 00:00.](https://docs.flozu.app/_astro/story-player-light.DuLoij-i_Z1MpUvP.webp)

Every step is the live map, not a picture, so anyone can stop and ask “what’s that?”, and you can select it and show them.

## 5. Send it

Choose **Share a link…** from the **Actions** menu. The link carries the map with its stories and saved scenarios, so whoever opens it can play the story at their own pace and save a copy. They don’t need an account.

![The Share a link popover: the link, copied, with a note that it holds the map as it is now.](https://docs.flozu.app/_astro/share-light.BNzWBMZs_Z2ki1JK.webp)

A link holds the map as it is when you make it. Change the story later, and make a new link.

## What you learned

- **A story from a scenario** gives you a first draft in one click, ordered by what happens.
- **The card is the slide.** What you type on a step is exactly what your audience reads.
- **A share link carries stories,** so the walkthrough works without you in the room.

## Next

- [Make the case for a fix](https://docs.flozu.app/walkthroughs/make-the-case.md) adds a step that compares the map before and after a change.
- [Stories](https://docs.flozu.app/guides/stories.md) covers every part of a step, and showing parts differently on one step.
- [Presenting and share links](https://docs.flozu.app/guides/presenting-and-sharing.md) covers what a link holds and what it leaves out.

---

# Make the case for a fix

> Turn a fix into a proposal, prove it with the same failure played before and after, put a price on it, and tell it as a story your team can say yes to.

You know the checkout goes down with its cloud region, and you know a standby region fixes it. Your manager wants to know three things: does it really fix it, what does it cost, and can you show them in five minutes? This walkthrough answers all three on the **Checkout system** map.

It picks up from [What if something breaks?](https://docs.flozu.app/walkthroughs/what-if-it-breaks.md), but works on its own.

## 1. Give the parts a price

A fix that doubles your servers isn’t free, so put the running costs on the map first. Costs on the map before you try the fix are carried into the proposal, so both sides are priced the same way.

1. Select **Orders API**, open its **Traffic** tab, and set **Costs** to 0.40, in dollars an hour.

2. Do the same for **Orders DB** at 1.20 and **Email worker** at 0.10.

Use your real bill if you have it. Rough numbers are fine: what matters is the difference between two designs.

## 2. Try the fix in a proposal

1. Open **Scenarios** and pick **Region down**. Up to 33% of Shoppers’ traffic fails for 30 minutes.

2. Under **Fix it**, beside the second zone, select **Try it**. Flozu opens a [proposal](https://docs.flozu.app/guides/versions-and-proposals.md): a copy of the map with a standby copy of AWS eu-west-1 and everything in it. The top left says **Copes now**.

![Fix it for Region down: nothing takes over when AWS eu-west-1 goes down, so 33% of Shoppers' traffic fails, and the fix, a second zone beside it with a copy of everything in it on standby, has a Try it button.](https://docs.flozu.app/_astro/try-fix-light.CgAqbTWN_9vwLP.webp)

Nothing on the map has changed yet. The proposal is where you work until you’re sure.

## 3. Prove it, side by side

1. Select **Copes now** at the top left. The Compare screen opens with the map as it was on one side and the proposal on the other, and Region down playing on both.

2. One timeline drives both maps. Drag it to 19:45 and watch the first map’s region go down and the second carry on.

3. Read the panel. It says what the change did, in one sentence:

   > Before, up to 33% of Shoppers’ traffic fails for 30 minutes. After, nobody notices, for about $1,241 a month more.

![Comparing a proposal with where it began, with Region down playing on both: the new standby region carries the traffic while AWS eu-west-1 is down, and the panel says before, up to 33% of Shoppers' traffic fails for 30 minutes, and after, nobody notices.](https://docs.flozu.app/_astro/replay-light.BshI_bk0_28NuiA.webp)

That’s the whole case: the risk, the fix, and its price. The price is the copy of everything in the region, so it doubles what the region costs: $1.70 an hour becomes $3.40.

> **Tip**
>
> Too dear? Go back to the proposal and try something smaller, such as a standby copy of the Orders DB alone. Compare again, and the panel says whether it still copes and what it saves.

## 4. Tell it as a story

1. On the Compare screen, with Region down playing, choose **Tell it as a story** under how each map copes.

2. Flozu writes a four-step story on the map: Region down from the start, the moment it goes wrong, the fix (comparing the proposal with the map at that moment), and the moment things are well again.

3. Change the words for your audience. For a manager, the third step might say: “A standby copy of the region takes over, and nobody notices. It costs about $1,241 a month.”

![The Compare screen on step 3 of 4 of the new story, The fix: Add a standby copy of AWS eu-west-1, with the region down above its standby copy, and the panel saying that before, up to 33% of Shoppers' traffic fails for 30 minutes, and after, nobody notices.](https://docs.flozu.app/_astro/fix-story-light.C7heP7D5_Z5XHDg.webp)

## 5. Show it

Present the map (**View** in the mode menu, then **Story**) and step through it. The third step opens the comparison, with the same scenario playing on both maps.

> **Caution**
>
> A share link holds the map without its history, so it doesn’t carry the proposal: the third step says its comparison isn’t in that copy. To let someone play the whole story on their own, put the map in a [team](https://docs.flozu.app/guides/teams.md) they’re in, or [export it with its history](https://docs.flozu.app/guides/import-export.md) and send them the file.

## 6. Adopt it

When the answer is yes, open the proposal and choose **Adopt**. Flozu saves the map as a version first, then makes the proposal the map. The story still opens its comparison, because the adopted proposal remembers where it began.

## What you learned

- **A proposal is a safe place to try a change.** The map only changes when you adopt.
- **The replay is the proof.** One scenario, two maps, one sentence that says what changed.
- **Costs turn a fix into a decision.** Rough prices are enough to compare two designs.

## Next

- [Versions and proposals](https://docs.flozu.app/guides/versions-and-proposals.md) covers comparing any two versions.
- [Response times and cost](https://docs.flozu.app/guides/response-times-and-cost.md) covers what the estimates count.

---

# Your maps, projects and folders

> Make, find and sort your maps into projects and folders, keep several open at once, and know when and how they save.

Your first map is easy to find. By your twentieth, you’ll want them sorted: the payments team’s maps in one place, each service’s map inside its system’s. Flozu sorts maps into **projects**, and projects into **folders**, and keeps the ones you’re working on open side by side.

## Try it

1. On home, select **All maps and projects** under the box. The Maps page opens.

2. Select **+** at the top of the panel on the left, choose **New project** and call it “Payments”. Its page opens.

3. Select **New map**. The map is made inside the project, and opens in the editor.

4. Go back to the Maps page with **All maps** and drag another map onto **Payments**. It moves in.

![The Maps page on the Payments project: the way back to All maps, then a Services folder and two maps, with a search, New map and a menu for more.](https://docs.flozu.app/_astro/project-light.BzZkDNHr_Z1tHqS9.webp)

## Home

Flozu opens on home: one box in the middle of the canvas, there to type into.

![Home: What are we mapping? over one box, with the map to continue first, four recent maps under it, then New map, Templates and Import.](https://docs.flozu.app/_astro/home-light.Ck2unptZ_Z1PVwDk.webp)

- **The first row** carries on with the map you last edited. **Recent** lists the four before it.
- **Type** to find a map by name. Use `↑` and `↓` to pick one and `Enter` to open it; `Esc` clears what you typed.
- **New map** opens a blank map in the editor. **Templates** starts from an example system instead; see [templates](https://docs.flozu.app/guides/templates.md). **Import** brings in a map or project file; see [import and export](https://docs.flozu.app/guides/import-export.md). You can also drop files anywhere on home.
- **With no recent maps,** such as when you first sign in, home also offers three [showcase maps](https://docs.flozu.app/guides/templates.md#the-showcase): whole systems with scenarios, stories and a history to explore.
- **In more than one workspace,** such as your own and a team’s, they show as tabs over the box.
- **All maps and projects**, under the box, opens the Maps page.

## The Maps page

The Maps page shows every map and project in one panel, one level at a time. Select a project or folder to see what’s in it, and the way back at its top to go up again. **Projects**, in the panel on the left, moves through the same levels.

- **All maps** lists your projects, then every map you’ve made, with a small drawing of it, its name, where it’s kept, what it holds and when you last edited it, most recent first.
- **Search maps** narrows the list by name. On a project, it looks through everything inside it.
- **New map** makes a map where you are. The **⋯** beside it makes a project or folder, imports, exports, and renames, moves or deletes the project or folder on show.

### A map’s menu

Each map has a **⋯** menu:

| Item          | What it does                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Rename**    | Changes the map’s name.                                                                                                        |
| **Duplicate** | Makes a copy beside it, such as “Checkout system copy”, with its open proposals, so its stories still compare them.            |
| **Move to…**  | Puts the map in a project or folder, or in a [team](https://docs.flozu.app/guides/teams.md#share-a-map-with-the-team).         |
| **Export…**   | Saves the map as a file, with or without its history. See [import and export](https://docs.flozu.app/guides/import-export.md). |
| **Delete**    | Deletes the map and its versions. Flozu asks first, and offers to export a copy.                                               |

With a map open, **Map settings…** in the **Actions** menu renames or deletes it too.

## Projects and folders

A project is simply a folder at the top. A map doesn’t have to be in one.

- **New project**, with the **+** beside **Projects** on the Maps page or at the top of the **Maps** panel, makes a project and opens it.
- **New folder**, in the **⋯** menu of a project or folder, makes a folder inside it.
- **New map** and **Import** on a project put the map straight in that project.

A project on the Maps page works like a space in a wiki: its folders, its maps, and a search that looks through everything inside it.

### How the maps fit

When a project’s maps open into each other through [maps inside parts](https://docs.flozu.app/guides/maps-inside-parts.md), the Maps page shows **How the maps fit**: each top map, the parts in it that open maps, and the maps they open, a few levels down. Select any map to open it.

### Move maps and folders

- Choose **Move to…** from a map’s or folder’s menu, and pick where it goes.
- Or drag a map on the Maps page, or its row in the **Projects** panel, onto a project or folder, or onto the way back at the top of a level to move it up one.
- Drop a folder on the **Projects** heading on the Maps page to turn it into a project.

Moving or renaming a folder takes everything in it along, and once you’re signed in a project or folder can [move into a team](https://docs.flozu.app/guides/teams.md#share-a-map-with-the-team) the same way. Deleting one asks first and deletes everything inside it. In the Mac app it goes to the Trash.

## The Projects panel

**Projects**, in the menu down the left, or **Maps inside** on a map’s own menu, shows one level at a time, so it stays short however many maps you have.

![The Projects panel on the Pantry delivery platform map's level: the way back to its project, then the maps inside it, its scenarios, its stories and its open proposals, each with a count.](https://docs.flozu.app/_astro/maps-panel-light.BEfR2uNA_1KtI05.webp)

- **The top** lists your projects, each saying how much it holds, then the maps that aren’t in a project.
- **Select a name** to open that project on the Maps page, or that map. **Select the arrow** at the end of its row to show what’s in it, in the panel’s place.
- **A project or folder** lists its folders, then its maps. A map that a part opens into is listed one level down, under the map that opens it.
- **A map** lists the [maps inside its parts](https://docs.flozu.app/guides/maps-inside-parts.md), its [saved scenarios](https://docs.flozu.app/guides/scenarios.md#save-a-scenario), its [stories](https://docs.flozu.app/guides/stories.md) and its open [proposals](https://docs.flozu.app/guides/versions-and-proposals.md), each with a count. Pick a scenario to open the map with it running, a story to present it, or a proposal to open it.
- **The way back**, at the top of a level, or `Esc`, goes up one level. The panel stays where you left it until you go back.

**Find a map, scenario or story** searches every level at once, and says where each thing it finds is.

## Recent maps

**Recent**, in the menu down the left, lists the five maps you changed last that aren’t open already, newest first. Select one to open it.

## Open maps

The maps you open are listed under **Open** in the menu down the left, in place of tabs, so you can jump between the checkout and the payment service it calls without going back home. The page with a number, at the top right, lists them too, from wherever you are.

![The menu down the left with three maps listed under Open and the map on show highlighted, then the maps changed last under Recent.](https://docs.flozu.app/_astro/open-maps-light.iYy431XI_Z1Y4VUg.webp)

- Opening a map adds it beside the one you’re on.
- Select the page at the top right to see the same list over whatever’s on show, and pick a map to go to it.
- Close a map with its **×**, or with a middle click. The one beside it takes its place, or Home when it was the last. **Close all** closes every one.
- Drag them in the menu to put them in a different order.
- They come back when you open Flozu again.

Each open map keeps its undo history while Flozu is open, as long as nothing else has changed the map since. In the Mac app, `⌘W` closes the map on show and `⌃Tab` and `⌃⇧Tab` move between your open maps.

## Saving

There’s no save button. Every change saves itself a moment later, and straight away when you switch to another map or close the window.

- **If a save fails,** such as when you lose your connection, a notice says your latest change isn’t saved yet, and Flozu keeps trying until it is, then says so. Closing the tab while a change is still waiting asks first.
- **If someone else saves the map while you’re editing it,** in another tab, on another device or in your team, Flozu never saves over their work. The map shows their copy, and your changes are kept as a proposal called “Your changes from” and the time, to [compare and adopt](https://docs.flozu.app/guides/versions-and-proposals.md).
- **If something breaks,** Flozu shows a page that lets you download the map you had open before you reload, so your latest changes are never lost.

See [where maps live](https://docs.flozu.app/concepts/where-maps-live.md) for how and where they’re kept.

## Good to know

- **Folders nest up to six levels deep.** A folder’s name can be up to 80 characters. It can’t contain `/`, `\` or `:`, can’t start with a dot, and has to be different from the other folders beside it, whatever the capitals.
- **Moving a map never changes the map itself.** Where a map is kept belongs to Flozu’s storage, not to the map file, so an exported map doesn’t say which folder it came from. To take the folders along, export the whole project or folder as a [bundle](https://docs.flozu.app/guides/import-export.md#a-file-to-open-again).
- **Every map and project has its own address,** such as `#/maps/<id>` or `#/projects/Payments/Services`, so the browser’s back button works and you can bookmark one.
- **Opening a map starts a fresh undo history,** unless it’s still in your open maps.
- **Presenting, proposals, comparing and shared maps** fill the whole window, without the panel.

---

# Parts

> Add parts to a map, name them, say what they're built with, and move, select and delete them.

A part is anything you’d point at on a whiteboard when you explain your system: the people who use it, an app, a gateway, a service, a queue, a database, or, inside a service, an endpoint or a module. Its kind tells Flozu how it behaves, such as whether it can run out of room or hold work in a queue.

## Try it

Draw the start of a shop’s checkout:

1. On an empty map, with the pointer over the canvas, press `P` for a person. Double-click its name and call it “Shoppers”.

2. Press `S` to the right of it for a service, and call it “Orders API”. Then press `D` to the right again for a database, “Orders DB”.

3. Drag from the right edge of each part to the next to connect them.

![Three parts on an empty canvas, Shoppers, Orders API and Orders DB, joined left to right by two lines.](https://docs.flozu.app/_astro/first-parts-light.CHF90DTt_Z2pGQw.webp)

## Kinds of part

Flozu has 28 kinds of part, grouped as the library groups them:

| Family           | Kinds                                                             |
| ---------------- | ----------------------------------------------------------------- |
| People and apps  | Person, Client app                                                |
| The way in       | DNS, CDN, Firewall, Gateway, Sign-in, Load balancer, Rate limiter |
| Compute          | Service, Worker, Function, Scheduler, AI model                    |
| Messaging        | Queue, Topic                                                      |
| Data             | Database, Cache, Search, Storage, Data warehouse                  |
| Inside a service | Endpoint, Module, Code file, Interface, Library, Table            |
| Anything else    | Custom part                                                       |

[Part kinds](https://docs.flozu.app/reference/part-kinds.md) lists each one with its key, if it has one, and what it’s for. Most kinds for inside a service have no key; add them from the library or by searching.

## Add a part

There are four ways, so use whichever is closest to hand:

- **Press its key** with the pointer over the canvas: `S` for a service, `D` for a database, `Q` for a queue. The part appears under the pointer.
- **Drag it from the library** (**Add parts** on the map’s menu down the left) onto the canvas, or click it to add it mid-screen.
- **Double-click empty canvas** and search for it.
- **Drop a line on empty canvas.** Flozu suggests the parts that usually come next (a database or a queue after a service) and adds the one you pick already connected.

A new part settles into place with a soft orange ring, and a new line glows orange for a moment, so you can see where they landed. The selected part has an orange edge and a soft glow.

The library’s **Presets** shelf has 117 parts ready to go, such as Cloudflare DNS or a Redis cache. See [start from a preset](https://docs.flozu.app/guides/looks.md#start-from-a-preset).

## Describe it

Select a part, and its **About** tab in the inspector holds what it is:

- **Name.** Or double-click the name on the card to rename it in place.
- **Kind.** Change it any time. A kind decides how a part behaves, such as which limits it can have, but not how it has to look.
- **Technology.** What it’s built with or bought from, such as PostgreSQL or Stripe. Pick from the suggestions or type anything. When Flozu knows the technology, its logo becomes the part’s mark.
- **Run by.** **Us**, or **Someone else** for a part another company runs, such as a payment provider. A part someone else runs has a dashed outline.
- **Notes.** Anything a reader should know about it.

The caption above a card says its kind and technology, such as “Database · PostgreSQL”.

## How a card reads

Every part is a card. Its header shows its mark and name, and its panel shows a small live drawing of what it does, with one figure underneath, such as a database’s queries a second or a queue’s size. Its ports sit halfway down: in on the left, out on the right, so a map reads left to right.

Change how a part looks, from its card to its drawing and size, in its **Look** tab. See [make it look right](https://docs.flozu.app/guides/looks.md).

## Select, move and delete

- **Select** a part by clicking it. Hold `⌘` (or `Ctrl`) to add to the selection, or drag across empty canvas with `Shift` held to select an area.
- **Move** what’s selected by dragging it, or a grid step at a time with the arrow keys.
- **Delete** what’s selected with `Delete` or `Backspace`. A part takes its lines with it.
- **Let go** of the selection with `Esc`.

With several things selected, the inspector can put them in a zone, style them all at once, or delete them together.

> **Tip**
>
> Every one of these is a single step to undo. Press `⌘Z` (or `Ctrl+Z`) to take it back, however far you dragged.

---

# Lines

> Connect parts with requests, messages and uses lines, from any side, run them curved, square or straight, and pick what moves along them.

A line says one part talks to another. What matters most is whether the sender waits for an answer. A phone call waits: if nobody picks up, you know straight away. A letter doesn’t: you post it and get on with your day. Flozu’s lines work the same way, and that decides who notices when something [breaks](https://docs.flozu.app/guides/failure-drills.md).

There are three kinds:

| Kind    | Looks like               | What it is                                                                                                                       |
| ------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| Request | A solid pale blue line   | Something that asks and waits for an answer, like an HTTP call or a database query.                                              |
| Message | A dashed lime line       | Something sent and left, like an event or a job.                                                                                 |
| Uses    | A quiet dotted grey line | One part depends on another, like code importing a library or keeping an interface. It carries no traffic, so scenarios skip it. |

## Draw a line

Drag from a port on a part’s edge to another part. Every part has a port on each side: left and right always show, and top and bottom show when your pointer is on the part. As you get close to a port, the line snaps to it inside a soft orange ring, so you never have to hit the small target. Letting go on a card connects to it too, and a line from the top or bottom then arrives at the side facing it. Letting go on the part you started from cancels.

Flozu picks the kind for you: a line into a library or an interface starts as uses, a line into or out of a queue or a topic starts as a message, and so does a line out of a scheduler, since it starts a job and doesn’t wait for it. Every other line starts as a request. A uses line has no direction, protocol or **Traffic** tab. You can change it in the line’s **About** tab.

### Keep going

Let go of a line on empty canvas and Flozu asks what comes next. It suggests the parts that usually follow, best first, and adds the one you pick already connected. It’s the quickest way to draw a path from one end of a system to the other.

![A small search over the canvas, titled Add a part, narrowed to Cache.](https://docs.flozu.app/_astro/quick-add-light.CjYtG6cl_1JhTVg.webp)

## Put a part on a line

Hover a line and select the plus in its middle. Pick a part, and the line splits in two around it. Both halves keep the line’s settings. If there’s no room, everything from the line’s end rightwards moves along to make some, all in one step to undo.

## Line settings

Select a line to edit it in the inspector.

- **About:** what it carries (request or message), its direction (forward, or both ways), a label such as “Charge card”, and a protocol such as HTTPS, gRPC or SQL.
- **Look:** its colour, pattern and weight (see [styling](https://docs.flozu.app/guides/looks.md#colours-and-styles)), what moves along it, how it runs, and which side of each part it leaves and arrives at.
- **Traffic:** its rate, the traffic it carries each second at the busiest moment of a normal day, and whether it’s always in use or a standby. See [traffic and limits](https://docs.flozu.app/guides/traffic-and-limits.md).

The selected line and its traffic turn orange.

## Which sides a line joins

A line leaves from the right of a part and arrives at the left until you say otherwise. Draw it from another port, or move it in the **Look** tab’s **Ends** section: **Leaves** and **Arrives** each pick a side with an arrow. A line from the bottom of a part into the top of the part below runs straight down, instead of bending round.

## Curved, square or straight

A line runs one of three ways:

| Route    | Looks like                                                              |
| -------- | ----------------------------------------------------------------------- |
| Curved   | A smooth curve, the usual.                                              |
| Square   | Flat and upright runs with small rounded turns, like a circuit diagram. |
| Straight | A straight line from one port to the other.                             |

Set the way for every line on the map in the map’s **About** tab, under **Lines**: select an empty part of the canvas to see it. To run one line its own way, pick its **Route** in its **Look** tab. Picking the map’s way again puts it back in step with the map.

![The checkout map with every line running square, in flat and upright runs with rounded turns.](https://docs.flozu.app/_astro/square-lines-light.DowMTJ4H_QdKWn.webp)

## Standby lines

A standby line carries nothing until a line beside it fails, like a failover to a replica or a second region. Set **Use** to **As a standby** in the line’s **Traffic** tab. It’s drawn faint and dashed while it rests, and says **Standby** in a scenario.

It stands by for the lines beside it: from the same part, of the same kind, to the same kind of part. When one of those is cut, or the part it goes to is down, the standby takes its traffic over and draws thicker. Without its own rate, it carries what the lines it stands by for would have. See [failure drills](https://docs.flozu.app/guides/failure-drills.md).

## Traffic on the line

While the map plays, dots travel along each line at a steady speed, closer together on busier lines. Messages travel as short capsules, and a two-way line carries traffic both ways. The spacing follows a log scale, so 10 a second and 10,000 a second both read clearly.

## What moves along a line

The line’s **Look** tab picks its **Effect**:

| Effect  | What it shows                                                                    |
| ------- | -------------------------------------------------------------------------------- |
| Traffic | Dots and capsules, as above. The usual.                                          |
| Pulse   | A soft glowing streak that runs the length of the line, quicker on busier lines. |
| Flow    | Dashes that stream along the line, both ways on a two-way line.                  |
| None    | Nothing moves.                                                                   |

To show only the effect, pick **No line** (the crossed-out eye) under **Pattern**. The line itself then draws faintly only while you hover or select it, or while the map is paused, so you can still find it. Every effect stops when you pause the map.

![A line's Look tab with Pulse and Square picked, beside the line glowing on the canvas.](https://docs.flozu.app/_astro/line-effects-light.DJpzF9bc_zqyqy.webp)

---

# Make it look right

> Start from a preset, size the big pieces of your system big, pick each card's layout and drawing, and use colour to mark out regions, teams or the path that matters.

A map is looked at before it’s read. If every card is the same size and colour, people have to read every name to find what matters. Make the important parts big, the supporting ones small, and give colour one meaning, and they’ll see the shape of your system before they read a word.

How a part looks never changes what it is or how traffic moves through it. Look and behaviour are separate, so style freely.

## Try it

On the **Checkout system** template, make the order path stand out:

1. Select **Orders API**, open its **Look** tab, and pick **Large** under size. It’s the part the map is about, so it should look it.

2. Select **Payments** and pick the **Slim** card. Stripe runs it, so it needs less room.

3. Select the lines from **Web shop** to **Orders API** and from **Orders API** to **Orders DB**, holding `⌘`. In **Style**, set the colour to blue and the weight to bold.

![The checkout map styled: a large Orders API, a slim Payments card, and the order path from the web shop through the Orders API to the Orders DB in bold blue.](https://docs.flozu.app/_astro/looks-styled-light.BY0BNWb5_ZWeFKw.webp)

## Start from a preset

The library’s **Presets** shelf holds 117 parts ready to go, such as Cloudflare DNS, a web firewall, a token bucket limiter, a Redis cache, a Kafka topic, Claude or Stripe payments.

![The parts library on its Presets shelf, grouped into people and apps, the way in and more, each preset with a logo or icon.](https://docs.flozu.app/_astro/library-presets-light.B4iSAi-v_1Ib4r8.webp)

A preset fills in a part’s kind, name, drawing, card, technology and whether someone else runs it, with sensible starting limits: a rate limiter’s limit, a queue’s buffer, a service’s capacity and how it auto-scales. Everything it fills in is only where the part starts. Change any of it afterwards, as with any part.

A search in the library looks through the plain parts and the presets at once. [Presets](https://docs.flozu.app/reference/presets.md) lists them all.

### Logos

When Flozu knows a part’s technology, its mark is that technology’s logo, in one colour. Otherwise it’s the kind’s icon. Logos come from [Simple Icons](https://simpleicons.org); the brands belong to their owners. Some brands, such as AWS and OpenAI, don’t allow their logo there, so those parts keep the kind’s icon.

## Size

A bigger share of your system can look bigger. Select a part and drag one of its corners. It snaps to the grid, from 160 by 48 up to 640 by 512. Its left and right edges are its ports, so only the corners resize it.

Or pick a size in the **Look** tab: small, standard, large or extra large, each in the shape of the part’s card. A standard card is 192 by 160, large is 288 by 240 and extra large 384 by 320.

The drawing grows to fill the card and keeps its shape. The name and figure grow a little with it, so a part twice the size reads as bigger without shouting.

## Card layouts

Each part picks its card in the **Look** tab. A map can mix them freely.

| Card     | What it shows                                                             |
| -------- | ------------------------------------------------------------------------- |
| 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.     |

Each layout has a shape of its own, so picking one also gives the part that layout’s size: a standard card is 192 by 160, showcase 192 by 176, wide 320 by 144 and slim 192 by 64. A large part stays large, and its ports stay at the same height so its lines don’t bend.

You don’t have to pick a layout to change how a card reads. Resizing is enough:

- A card shorter than 112 shows as a **slim** line, since there’s no room for a drawing.
- A standard or showcase card at least twice as wide as it is tall shows as a **wide** one.

## Drawings

Each part’s panel shows a small live drawing of what it does. Every kind has its own, but any part can show any of the 237 drawings in the library: a service can show a card payment, a queue its dead letters, a worker a video being encoded.

![The Look tab for Orders API: its size, four card layouts with Standard picked, the Activity drawing it shows, and a button to browse all drawings.](https://docs.flozu.app/_astro/inspector-look-light.CgFV5Zhd_Z2ebD4S.webp)

Under **Drawing** in the **Look** tab, the part’s drawing shows as one tile. **Browse all** opens the gallery beside the inspector. It opens on the drawings suggested for the part; search it, or pick a category from the filter beside the search. Picking a drawing applies it straight away, and the gallery stays open so you can try another.

![The drawings gallery open beside the inspector: a search with a filter beside it set to Suggested, and a grid of animated drawings.](https://docs.flozu.app/_astro/drawings-light.C_04ouZV_21Acsm.webp)

Changing a part’s kind keeps a drawing you picked; a part showing its kind’s own drawing switches to the new kind’s. [Drawings](https://docs.flozu.app/reference/drawings.md) lists every drawing with what it shows.

## Colours and styles

Give any part, line, zone or note colours of its own, so a map can mark out its areas: the EU region in blue, a team’s systems in violet, the risky path in red.

![The checkout map with its AWS region filled in blue and its background jobs zone in violet.](https://docs.flozu.app/_astro/styled-zones-light.D47X4juY_X7PnG.webp)

Select it and open its **Look** tab. The **Style** section has:

| Setting                   | What it sets                                                                                                                  |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Border** (or **Line**)  | The colour of its edge, or of the line. Its button shows the colour; press it for the palette and a picker.                   |
| **Pattern**               | Solid, dashed or dotted. A line can have no line at all, so only what moves along it shows.                                   |
| **Weight**                | Thin, regular or bold.                                                                                                        |
| **Strength**              | How strong the colour is.                                                                                                     |
| **Fill** and its strength | The colour it’s filled with. Lines have no fill.                                                                              |
| **Effect** and **Route**  | Lines only: what moves along it and how it runs. See [lines](https://docs.flozu.app/guides/lines.md#what-moves-along-a-line). |

A strength slider previews on the canvas as you drag it, and saves once when you let go. **Reset** goes back to the usual look. Select several things, and a change applies to all of them at once, as one step to undo.

### How colours work

Colours are names from one palette (grey, red, orange, amber, yellow, lime, green, teal, blue, indigo, violet and pink), not exact values. Each theme draws them in its own shade, so a map reads well in both dark and light.

### A colour of your own

Press a colour’s button: the palette sits at the top, and a picker under it takes any colour. Drag in the square for how strong and how bright, slide the rainbow for the hue, or type a hex code such as `#3a7bd5` and press Enter. The canvas shows the colour as you drag, and it saves once when you let go. A colour of your own is drawn the same in both themes.

![The colours open from a line's colour button: the palette in two rows, then a blue square with a ring in it, a rainbow slider and the hex code #3972BF.](https://docs.flozu.app/_astro/colour-picker-light.C9pYJpS4_Z10Hxq6.webp)

## Good to know

- **Give colour one meaning per map,** such as the main path, or one team’s parts. A map where everything is coloured reads as if nothing is.
- **A fill is always a tint,** so words on it stay easy to read.
- **Anything you leave alone keeps the item’s usual look,** such as dashed for a message or dotted for a team.
- **Selection and scenario outlines** still show over a style.
- **A coloured zone’s or line’s colour** also shows in the map’s small drawing, at home and on the Maps page.

---

# Zones and notes

> Draw frames around parts that belong together, such as a cloud region or a team, and leave notes for whoever reads the map.

A zone answers two questions a box-and-arrow diagram leaves open: where does this run, and who looks after it? Draw a region around the parts in AWS eu-west-1, and a [failure drill](https://docs.flozu.app/guides/failure-drills.md) can take the whole region down. Draw a team around the parts the payments team owns, and everyone knows who to ask. A note answers the third question: why does it work this way?

## Zones

A zone is a frame around parts that belong together: a cloud region, a network, a system, a team or any other boundary. Each kind of zone draws its edge its own way, with its icon and name in the top-left corner.

| Zone    | For                                         | Edge   |
| ------- | ------------------------------------------- | ------ |
| Region  | A cloud region or a data centre.            | Solid  |
| Network | A private network or a subnet.              | Dashed |
| System  | A product or a system, for the big picture. | Solid  |
| Team    | The people who look after these parts.      | Dotted |
| Zone    | Any other boundary.                         | Dashed |

![A blue AWS region zone holding the orders API and database, with a violet background jobs zone inside it.](https://docs.flozu.app/_astro/styled-zones-light.D47X4juY_X7PnG.webp)

### Add a zone

- Select some parts and press `Z`. The zone is drawn around them, with room for its label.
- Or press `Z` with nothing selected, or drag **Zone** from the library, to add an empty one.
- Or select several things and choose to put them in a zone from the inspector.

### What’s inside a zone

What you see is what the map holds. A part belongs to the smallest zone around its middle, and a zone to the smallest zone that holds all of it, so zones nest. Whatever you move, resize or add joins the zone it lands in, in the same step to undo.

- **Move a zone** by dragging its label or edge. Everything inside comes with it.
- **Reshape it** by dragging its corners and edges when it’s selected. What’s inside stays put.
- **Delete a zone** and what was inside stays, in the zone around it if there is one.

Only a zone’s label and edge catch the pointer, so you can still pan, select and add parts inside it. Its **Inside** tab lists what it holds.

## Notes

A note is plain words on the canvas, such as why something works the way it does.

- Press `N` to write one where the pointer is, or drag **Note** from the library.
- Click away, press `Esc` or `⌘Enter` to finish. A note left blank isn’t added.
- Double-click a note to edit it.
- Its height follows its words. Drag its right edge to set how wide it runs.

---

# Maps inside parts

> Give a part a map of its own, such as a payment service's modules and what they call, and go in and out of it like zooming into the card.

A part on a big map often hides a whole system of its own. Payments on a shop’s map is a service with its own endpoints, modules and databases, and a module there might hide a map of its code. Any part can open into a map that shows what’s inside it, so a set of maps reads as one picture you can zoom through: the whole platform for a manager, one service for its team, the code for a new starter.

## Try it

1. Open **Templates** from home, and use the **Pantry delivery platform** showcase.

2. Find the **Checkout** part. Pages are stacked behind its card, and a badge at its lower right names the map inside. Click the badge.

3. The camera flies into the card, and Checkout’s own map opens: its endpoints, modules and databases. The trail at the top centre reads **Pantry delivery platform › Checkout**.

4. Press `⌘↑`, or select **Pantry delivery platform** in the trail, to come back out.

Now run **Black Friday** on Pantry and go into Checkout again. The scenario comes with you, so you can see which module inside struggles when the whole platform is busy.

![Pantry's Checkout map open inside its part, with the trail Pantry delivery platform › Checkout at the top left, Slot holds overloaded at 114%, and Black Friday, from Pantry delivery platform, along the timeline.](https://docs.flozu.app/_astro/inside-scenario-light.UmY9aMEi_Z29kKVl.webp)

The map inside is an ordinary map. You can open, present, share and export it on its own, and several parts can open the same one, such as one sign-in service used by every team.

## Go in and out

To go in, do any of these:

- Click the badge.
- Select the part and press `⌘↓` (`Ctrl+↓` on Windows and Linux).
- Select **Open inside** in the **Map inside** section.

The camera flies into the card, and the map inside grows into place and joins your open maps beside this one. Going back out, the map above settles back where you left it. With reduced motion, it simply opens.

![The Payments map open, with Checkout system › Payments as a trail above it and Orders API drawn faded on the left, calling in.](https://docs.flozu.app/_astro/map-inside-light.7aJ1C1t1_eheyQ.webp)

The maps above show as a trail before the map’s name at the canvas’s top left, such as **Checkout system › Payments**. Select one, or press `⌘↑`, to go back out, with the part you came from selected. A map that several parts open goes back out the way you came in.

Presenting works the same way, so you can walk an audience from the big picture into one service and back.

## How the card shows it

![The Payments card with pages stacked behind it and a badge at its lower right reading Payments 4.](https://docs.flozu.app/_astro/inside-badge-light.De8jQuVw_8XYXC.webp)

A part that opens into a map has pages stacked behind its card and a badge at its lower right, with the map’s name and how many parts it holds. Unless you picked a drawing for the part, its panel shows a small drawing of the map inside.

If the map isn’t here, such as one that was deleted or didn’t come with the file or link, the badge says **Map not here**. **Make its map** or **Link a map** gives the part a new one.

## Give a part a map

Select the part and open its **About** tab. The **Map inside** section offers two ways:

- **Make its map** saves a new map in the same folder, named after the part and holding one part like it, links the part to it, and opens it. It’s one step to undo.
- **Link a map** picks one of your saved maps, for a service you’ve already mapped.

Once a part has a map, the section shows a small preview of it with **Open inside**, **Unlink** and **Link another map**. **Unlink** only drops the link: the map stays where it is.

## Scenarios carry through

While a scenario runs, it plays inside the maps your parts open into too, on the same timeline. Each way into the map inside gets as much busier as the lines that reach it on the map above, so Black Friday on the shop is Black Friday inside the payment service.

- **The badge says how the inside copes.** It reads **Tight** in amber, or **2 over** in red when parts inside can’t keep up, at the moment the playhead is on.
- **Going in takes the scenario with you.** Open the part’s map while a scenario runs and the same scenario plays there, at the same moment. The timeline names where it came from, such as **Black Friday, from Checkout system**. Opening the scenario panel there gives that map a scenario of its own instead.

## Where it sits stays in view

The part’s neighbours on the map above are drawn faded at the edges of the map inside: what calls in on the left, and what it calls on the right, with their lines. They aren’t part of this map, so they can’t be selected or moved, and clicking one takes you to it.

Each of those lines joins one part inside. Flozu works it out: a line in joins the map’s only way in, a part nothing flows into, and a line out leaves from its only way out. To choose for yourself, select the line on the map above and set **Lands on** or **Leaves from** in its **About** tab.

## Parts for inside a service

The library’s **Inside a service** family has parts for what a service is made of: endpoints, modules, code files, interfaces, libraries and tables. A dotted **uses** line says one depends on another, such as a module using a library, and carries no traffic. See [lines](https://docs.flozu.app/guides/lines.md). The **Inside a payment service** template shows one put together.

## In the Projects panel

On a map’s own menu, **Maps inside** shows them in the panel. In the **Projects** panel, select the arrow beside a map to see the maps its parts open into, under **Maps inside**, with a layers mark. In their folder they’re listed there, under the map that opens them, rather than beside it; a map kept in another folder is listed in that folder too. Moving or renaming either map never breaks the link, because a part names its map by id, not by name or place.

A project’s page shows **How the maps fit**: each map that opens others, with the parts that open them and the maps inside, as links.

> **Tip**
>
> Exporting a map **with its history**, or a project, takes the maps inside its parts along, even ones kept in another folder, so the links still work wherever it’s imported. See [import and export](https://docs.flozu.app/guides/import-export.md).

---

# Templates

> Start from an example system, from a static site to a whole delivery platform, and try a scenario on it.

The quickest way to learn Flozu, and often the quickest way to map your own system, is to start from one that already works. The template library holds example systems with their numbers filled in, so you can press play and try a scenario straight away. Open it from **Templates** in the menu down the left, or **Templates** in the box on home.

![The template library, one panel: a search and the levels, then the showcase maps Pantry, Quill and Encore as rows, each with a drawing, what it is and buttons to preview or use it.](https://docs.flozu.app/_astro/templates-light.pmxnJm-m_Z1UbWvw.webp)

## What’s in it

Templates come in four levels:

| Level    | Templates                                                                                    |
| -------- | -------------------------------------------------------------------------------------------- |
| Showcase | Pantry delivery platform, Quill AI writing app, Encore ticket drop                           |
| Starter  | Static website, Web app with a database, Checkout system                                     |
| Growing  | Photo uploads with a queue, AI assistant, Event analytics pipeline, Inside a payment service |
| At scale | Video streaming, Ride-hailing dispatch, Social timeline, Shop in two regions                 |

Each row shows a drawing of the template, what it is and how many parts it has. **Search templates** finds them by name, what they’re about or what they show, such as auto-scaling, multi-region, caching or queues, and a level narrows the list. The **ⓘ** beside a level says what it holds.

Some at-scale templates are loosely based on a well-known company’s public engineering writing, and their row says whose. They’re all simplified, and their numbers are made up so scenarios have something to show.

## The showcase

The three showcase maps are whole systems to open first, each using everything Flozu does:

- **Pantry delivery platform:** groceries to the door, with shoppers, couriers and store pickers online at once, and five teams’ systems in 42 parts.
- **Quill AI writing app:** an editor that drafts and checks with Claude, whose story is about limits.
- **Encore ticket drop:** a ticket seller’s 10am on-sale, with a waiting room in front of booking, and a Region down drill whose story shows the standby region that fixes it.

Each has preset looks and drawings, zones and coloured lines, notes, auto-scaling, saved scenarios, stories to play, a second view for people who aren’t engineers, and a history of versions and proposals to compare.

Their key services also open into [maps of their own](https://docs.flozu.app/guides/maps-inside-parts.md), down to the code: Pantry’s checkout, dispatch and help chat, Quill’s writing service and Encore’s booking. Pantry’s checkout goes one level further, into the files that hold a delivery slot. Run Black Friday on Pantry and open Checkout to see it play inside.

Using a showcase saves it in a project of its own, named after it, with the maps inside its parts beside it and linked. Until you have maps of your own, they’re also home’s **Examples**: opening one there saves a copy with its history the first time and opens that same copy after, so your changes stay.

## Which one to start from

| If you’re mapping                                      | Start from                                                    |
| ------------------------------------------------------ | ------------------------------------------------------------- |
| A website or a small app                               | Static website, or Web app with a database                    |
| A shop, or anything that takes payments                | Checkout system                                               |
| Work done in the background, such as uploads or emails | Photo uploads with a queue                                    |
| An app that calls an AI model                          | AI assistant, or Quill AI writing app to see limits in action |
| Data pipelines and analytics                           | Event analytics pipeline                                      |
| One service’s insides, down to its modules             | Inside a payment service                                      |
| Something big, across regions and teams                | Shop in two regions, or Pantry delivery platform              |

## Preview a template

**Preview** opens the template read-only, as it would be presented, with scenarios you can try. It suggests one to start with, such as “Try Black Friday: the email worker falls behind first.”

## Use a template

**Use template** saves a copy as one of your own maps and opens it in the editor. Change it as much as you like: the template itself never changes.

---

# Map your code with Claude

> Have Claude read a codebase on your computer and write an outline of it, then import the outline and Flozu draws the map.

Claude can read a codebase on your computer and map it for you: the services, workers, databases and outside services it uses, what calls what, and where each part runs. Claude writes a short **outline**, and Flozu lays it out as a map when you import it.

Your code stays on your computer. Claude reads it where it is, and the outline holds only names, folders and short descriptions. You don’t need an account or a connection to GitHub.

![A map drawn from an outline: shoppers and the shop website on the left, then an AWS region zone holding an Orders system zone with a large Orders API, a cart cache and the Orders DB, then an Order events topic and a packing worker, and Stripe on the right. The order path runs straight and blue from the shoppers to the Orders API, the lines to Stripe and the order events run along a gap under the Orders DB, and every line shows its traffic.](https://docs.flozu.app/_astro/outline-map-light.Ddae9mOQ_2jYYfH.webp)

## Map a repository

1. Open [Claude Code](https://claude.com/claude-code), or another coding assistant, in the repository you want to map.

2. Give it the guide: [map-your-code.md](https://docs.flozu.app/map-your-code.md). Paste the guide’s link into your request, or save the file in the repository as `.claude/skills/map-to-flozu/SKILL.md`, so Claude Code uses it whenever you ask for a map.

3. Ask for the map, and say what you want to see. For example:

   ```text
   Follow the map-your-code guide to map this repository for Flozu.
   Show the services, what they talk to, and where they run.
   Save it as architecture.flozu-outline.json.
   ```

4. Open Flozu’s home, or the project you want the map in on the Maps page, and choose **Import**, or drop the file on the page. The map comes in drawn, ready to open.

Flozu places everything itself: traffic reads from left to right, each zone is a box around what’s in it, and lines run straight along gaps between the cards rather than behind them. Move things around as you like after that, and change anything Claude chose.

## What Claude puts on the map

The guide tells Claude how to turn code into parts, lines and zones:

- **Parts** are what runs and what it uses: services, workers, functions, scheduled jobs, apps, databases, queues, caches, storage, and outside services such as Stripe, marked as run by another company. For a single app, its modules are the parts. For a database, its tables are.
- **Lines** go from what calls, sends or depends to what it reaches. Each is a request, a message or a dependency, with a label and a protocol when the code says.
- **Zones** group parts by system, cloud region, network or team.

Claude can set everything you can in the editor, and the guide tells it how to make the map read well:

- **How it looks:** the parts the map is about are bigger, supporting parts such as caches and outside services are [slim](https://docs.flozu.app/guides/looks.md#card-layouts), each part shows a [drawing](https://docs.flozu.app/guides/looks.md#drawings) that says what it does, and [colour](https://docs.flozu.app/guides/looks.md#colours-and-styles) has one meaning, such as the main path.
- **Lines** carry their own [style](https://docs.flozu.app/guides/lines.md): the main path bold, and square or curved routes across the map.
- **Traffic:** how many people use it, a rate on each line and limits on the parts that can run out, from the code and its settings where they’re there. Claude marks the numbers it estimated and tells you which they are. See [traffic and limits](https://docs.flozu.app/guides/traffic-and-limits.md).
- **Its story:** a [story](https://docs.flozu.app/guides/stories.md) along the main journey, [scenarios](https://docs.flozu.app/guides/scenarios.md) for a normal day and a busy one, a [view](https://docs.flozu.app/concepts/views.md) in plain words for people who don’t build it, and a note or two.

Claude also notes where each part lives in the code, which you can see under **Code** in the part’s details. It aims for 8 to 40 parts a map. For a large system, ask for one map of the whole first, then a map of each big service, and link them with [maps inside parts](https://docs.flozu.app/guides/maps-inside-parts.md).

## When an outline can’t be drawn

If something in the file doesn’t fit, such as a line to a part that isn’t in it, Flozu says what’s wrong and where, and imports nothing from that file. Paste the message back to Claude and ask it to fix the outline.

> **Caution**
>
> The outline should hold names, folders and descriptions only. The guide tells Claude to leave out secrets, keys and personal data, but look over the file before you share it.

To write or change an outline yourself, see [Outlines](https://docs.flozu.app/reference/file-format.md#outlines) in the file format.

## Straight into your account

With a Flozu account, you don’t need the file. [Connect your assistant](https://docs.flozu.app/guides/connect-an-assistant.md) to Flozu, then sign in to Flozu and allow it when it asks. The page that asks shows what the assistant will be able to do, and that your repository’s code never leaves your computer. After that, it can see your workspaces and maps, draw new maps of your code in any project, and suggest changes. Every change it makes to a map, including mapping it again, comes in as a proposal for you to adopt. If you ask it to change a map itself, Flozu keeps a version of the map first, so you can always go back. Your code still stays on your computer: only the maps come to Flozu.

> **Note**
>
> Accounts are invite-only while Flozu is in beta. Without one, map your code into a file and import it, as above.

### Several repositories in one project

When a product lives in several repositories, ask Claude to map each one into the same [project](https://docs.flozu.app/guides/your-maps.md), then draw an overview: a part for each repository, the people who use them and what they share, with each part opening that repository’s own map. Open a part on the overview and you’re in its map.

### Mapping a repository again

Code changes, so ask Claude to map a repository again whenever it has. Claude looks for the map it made before and keeps its parts’ names, so what’s still there changes where it is. Everything you did to the map stays: where you moved things, the colours and drawings you chose, and your notes, views, scenarios and stories. New parts go beside what they link to, and parts the code no longer has are taken away.

It never changes your map by itself. The new map arrives as a [proposal](https://docs.flozu.app/guides/versions-and-proposals.md): compare it with your map, then adopt it or let it go.

### Finding what breaks

Claude can also test a map. Ask it what happens on your map in a [scenario](https://docs.flozu.app/guides/scenarios.md), one you saved or a ready-made one such as Black Friday or Region down, and it plays the scenario as the scenario panel does: what fails where traffic starts, which parts run short of room, the moments worth knowing and what to change. Ask it to fix what it finds and it suggests the fix as a proposal, then plays the scenario on the proposal and on your map to say whether the fix works. Playing a scenario saves nothing.

---

# Connect an assistant

> Add Flozu to Claude Code, Claude, Cursor, VS Code, Codex, Windsurf, Gemini CLI, ChatGPT or another AI assistant, so it can map your code into your account and work with your maps.

Flozu has an MCP server, so AI assistants can work in your account. Connect one and it can map a repository straight into a project, read your maps, run scenarios on them and suggest changes. Every change it makes to a map that’s already there comes in as a proposal for you to adopt in [Versions](https://docs.flozu.app/guides/versions-and-proposals.md).

Your code stays on your computer. The assistant reads it there and sends Flozu only the map it draws: the parts, how they connect and what they’re called.

Flozu’s MCP address is:

```text
https://my.flozu.app/api/mcp
```

Whichever assistant you use, it ends the same way: your browser opens Flozu, you sign in if you haven’t, check it’s your account, and choose **Allow**. There’s no key to copy. When you’re signed in, the robot button at the top right of Flozu has the quickest way: pick Claude Code, Cursor, VS Code, Codex or Gemini CLI, and it shows three steps with the command ready to copy, or a button that adds Flozu in one go.

> **Note**
>
> Accounts are invite-only while Flozu is in beta. Without one, an assistant can still [map your code into a file](https://docs.flozu.app/guides/map-your-code.md) that you import.

## Assistants that read your code

These run on your computer, beside your code, so they can map a repository.

### Claude Code

- **Terminal**

  1. Add Flozu. `--scope user` makes it work in every project.

     ```shell
     claude mcp add --transport http --scope user flozu https://my.flozu.app/api/mcp
     ```

  2. In Claude Code, run `/mcp`, choose **flozu**, then **Authenticate**.

  3. Your browser opens Flozu. Check it's your account, and choose **Allow**.

- **Shared with your team**

  1. Put this in `.mcp.json` at the top of the repository and commit it. Everyone who opens the repository in Claude Code gets Flozu.

     ```json
     {
       "mcpServers": {
         "flozu": {
           "type": "http",
           "url": "https://my.flozu.app/api/mcp"
         }
       }
     }
     ```

  2. Each person runs `/mcp`, chooses **flozu**, then **Authenticate**, and signs in to Flozu as themselves.

Claude Code's VS Code and JetBrains extensions use the same servers, so adding it once covers them too.

### Cursor

- **One click**

  1. Add Flozu to Cursor. Cursor opens and asks you to confirm. [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=flozu\&config=eyJ1cmwiOiJodHRwczovL215LmZsb3p1LmFwcC9hcGkvbWNwIn0%3D)

  2. In **Cursor Settings → Tools & MCP**, choose **Connect** beside Flozu.

  3. Your browser opens Flozu. Check it's your account, and choose **Allow**.

- **Settings file**

  1. Add Flozu to `~/.cursor/mcp.json` for every project, or to `.cursor/mcp.json` in one repository.

     ```json
     {
       "mcpServers": {
         "flozu": {
           "url": "https://my.flozu.app/api/mcp"
         }
       }
     }
     ```

  2. In **Cursor Settings → Tools & MCP**, choose **Connect** beside Flozu.

  3. Your browser opens Flozu. Check it's your account, and choose **Allow**.

Ask in Cursor's chat, in Agent mode.

### VS Code

With GitHub Copilot’s chat, in Agent mode.

- **One click**

  1. Add Flozu to VS Code. VS Code opens and shows Flozu: choose **Install**. [Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22flozu%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmy.flozu.app%2Fapi%2Fmcp%22%7D)

  2. VS Code asks to let Flozu sign in. Choose **Allow**.

  3. Your browser opens Flozu. Check it's your account, and choose **Allow**.

- **Terminal**

  1. Add Flozu.

     ```shell
     code --add-mcp '{"name":"flozu","type":"http","url":"https://my.flozu.app/api/mcp"}'
     ```

  2. VS Code asks to let Flozu sign in. Choose **Allow**.

  3. Your browser opens Flozu. Check it's your account, and choose **Allow**.

- **Settings file**

  1. Add Flozu to `.vscode/mcp.json` in the repository, then choose **Start** above it.

     ```json
     {
       "servers": {
         "flozu": {
           "type": "http",
           "url": "https://my.flozu.app/api/mcp"
         }
       }
     }
     ```

  2. VS Code asks to let Flozu sign in. Choose **Allow**.

  3. Your browser opens Flozu. Check it's your account, and choose **Allow**.

Ask in Copilot Chat, in Agent mode.

### Codex

OpenAI’s coding assistant.

- **Terminal**

  1. Add Flozu.

     ```shell
     codex mcp add flozu --url https://my.flozu.app/api/mcp
     ```

  2. Sign in to it.

     ```shell
     codex mcp login flozu
     ```

  3. Your browser opens Flozu. Check it's your account, and choose **Allow**.

- **Settings file**

  1. Add Flozu to `~/.codex/config.toml`.

     ```toml
     [mcp_servers.flozu]
     url = "https://my.flozu.app/api/mcp"
     ```

  2. Sign in to it.

     ```shell
     codex mcp login flozu
     ```

  3. Your browser opens Flozu. Check it's your account, and choose **Allow**.

The Codex CLI, its IDE extension and the Codex app share these settings, so adding it once covers all three.

### Windsurf

1. Add Flozu to `~/.codeium/windsurf/mcp_config.json`. In Cascade, **MCPs → Manage MCPs → View raw config** opens it.

   ```json
   {
     "mcpServers": {
       "flozu": {
         "serverUrl": "https://my.flozu.app/api/mcp"
       }
     }
   }
   ```

2. Save it, then choose **Refresh** in Cascade's list of MCPs.

3. Your browser opens Flozu. Check it's your account, and choose **Allow**.

### Gemini CLI

- **Terminal**

  1. Add Flozu.

     ```shell
     gemini mcp add --transport http --scope user flozu https://my.flozu.app/api/mcp
     ```

  2. In Gemini, sign in to it.

     ```text
     /mcp auth flozu
     ```

  3. Your browser opens Flozu. Check it's your account, and choose **Allow**.

- **Settings file**

  1. Add Flozu to `~/.gemini/settings.json`.

     ```json
     {
       "mcpServers": {
         "flozu": {
           "httpUrl": "https://my.flozu.app/api/mcp"
         }
       }
     }
     ```

  2. In Gemini, sign in to it.

     ```text
     /mcp auth flozu
     ```

  3. Your browser opens Flozu. Check it's your account, and choose **Allow**.

Gemini Code Assist's agent mode, in VS Code and JetBrains, reads the same settings file.

## Chat apps

Chat apps can read your maps, run scenarios and suggest changes, but they can’t read the code on your computer. To map a repository, use one of the assistants above.

### Claude

In the Claude desktop app, on claude.ai and on your phone. A connector added in one is in all of them. This is Claude the chat app: Claude Code has its own steps, [above](#claude-code).

- **Free, Pro and Max**

  1. Open **Settings → Connectors** and choose **Add custom connector**.

  2. Name it **Flozu**, paste the address, and choose **Add**.

     ```text
     https://my.flozu.app/api/mcp
     ```

  3. Choose **Connect** beside Flozu.

  4. Your browser opens Flozu. Check it's your account, and choose **Allow**.

  5. In a chat, open **+ → Connectors** and check Flozu is on.

- **Team and Enterprise**

  1. An owner adds Flozu once, for everyone: **Organization settings → Connectors → Add custom connector**, with the address.

     ```text
     https://my.flozu.app/api/mcp
     ```

  2. Each person opens **Settings → Connectors** and chooses **Connect** beside Flozu.

  3. Your browser opens Flozu. Check it's your account, and choose **Allow**.

Add it once, on the web or in the desktop app, and it's in both and on your phone. Claude in a chat can't read the code on your computer: to map a repository, use Claude Code.

### ChatGPT

1. Open **Settings → Apps & Connectors → Advanced settings** and turn on **Developer mode**.

2. Back in **Apps & Connectors**, choose **Create**. Name it **Flozu**, paste the address, and set **Authentication** to **OAuth**.

   ```text
   https://my.flozu.app/api/mcp
   ```

3. Tick **I trust this application**, then choose **Create**.

4. Your browser opens Flozu. Check it's your account, and choose **Allow**.

5. In a chat, choose **+ → More → Developer mode** and turn Flozu on.

Developer mode is on Plus, Pro, Business, Enterprise and Edu. On Business and Enterprise, an admin may need to allow it first. ChatGPT can't read the code on your computer: to map a repository, use Codex.

## Another assistant

Any assistant that takes MCP servers can connect.

- **Remote servers**

  1. If it takes remote MCP servers that sign in (Streamable HTTP and OAuth), give it the address. It registers itself, so there's no key to copy.

     ```text
     https://my.flozu.app/api/mcp
     ```

  2. Your browser opens Flozu. Check it's your account, and choose **Allow**.

- **Local servers only**

  1. If it only runs MCP servers on your computer, add Flozu through `mcp-remote`, which needs Node.js.

     ```json
     {
       "mcpServers": {
         "flozu": {
           "command": "npx",
           "args": [
             "-y",
             "mcp-remote",
             "https://my.flozu.app/api/mcp"
           ]
         }
       }
     }
     ```

  2. Your browser opens Flozu. Check it's your account, and choose **Allow**.

## What to ask

Once it’s connected, ask in your own words. For example:

- **“Map this repo into my Flozu account”**\
  Reads the code where it is and draws a new map, in the project you name.
- **“Map this repo again and suggest the changes”**\
  Maps it again onto its map as a proposal, keeping what you moved and wrote.
- **“Map each repo in this folder into my Payments project, then draw an overview”**\
  One map a repository, and an overview whose parts open each one.
- **“Run Black Friday on my Checkout map and tell me what breaks first”**\
  Plays a ready-made scenario and says what runs short, and what to change.
- **“Suggest a fix for what breaks, and check it copes”**\
  Saves the fix as a proposal and plays the scenario on it.
- **“Add a story along the checkout path”**\
  Suggests a story, step by step, for you to adopt in Versions.

For a whole repository, the assistant follows Flozu’s guide to mapping code, the same one as in [Map your code with Claude](https://docs.flozu.app/guides/map-your-code.md), so the map comes out laid out and readable. Mapping a repository again keeps what you moved, coloured and wrote.

## Disconnecting

Remove Flozu in the assistant, the way you added it: for example, `claude mcp remove flozu` in Claude Code, or in Claude’s **Settings → Connectors**. To connect it again, add it again and allow it.

---

# Traffic and limits

> Give lines their rates and parts their capacity, limit and buffer, let parts auto-scale, and see how each part copes.

A map comes alive once it knows two numbers: how much each line carries, and how much each part can take. **Traffic lives on lines,** as a rate. **Limits live on parts,** because a limit belongs to the part that enforces it. From those two, Flozu works out how busy every part is, on a normal day and on your busiest.

## Try it

On the **Checkout system** template (open it from **Templates** with **Use template**):

1. Select the line from **Web shop** to **Orders API**. Its **Traffic** tab says it carries 40 requests a second: the orders placed at the busiest moment of a normal day.

2. Select **Orders API**. Its **Traffic** tab says it can take 400 a second, and that it’s 10% busy: underused.

3. Go back to the line and set its rate to 300. Select the Orders API again: it’s now 75% busy, past the 70% it should stay under, so it reads **Busy**.

4. Undo with `⌘Z` to put the rate back.

That’s the whole idea. Everything else on this page is about which numbers a part can have, and how Flozu shows them.

## Rates on lines

A line’s **rate** is how much it carries each second at the busiest moment of a normal day, such as 150 requests a second. Set it in the line’s **Traffic** tab. The rate sets how busy the line looks while the map plays, and it’s where every [scenario](https://docs.flozu.app/guides/scenarios.md) starts from: Black Friday is that rate, multiplied.

## Limits on parts

Select a part and open its **Traffic** tab. Each kind offers the limits that make sense for it:

| Limit        | What it is                                                     | For example                                            | Offered on                                                  |
| ------------ | -------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
| **Capacity** | The most it can handle each second. More than this backs up.   | An API that handles 400 requests a second              | Most parts, such as services, workers, databases and caches |
| **Limit**    | The most it lets through each second. The rest is turned away. | A rate limiter that lets 100 requests a second through | Rate limiters, firewalls, gateways, sign-in and AI models   |
| **Holds**    | How much can wait in line before it overflows.                 | A Kafka topic that holds 10,000 messages               | Queues and topics                                           |

The difference between a capacity and a limit is what happens to the extra. Past its capacity, a part falls behind and work waits. Past its limit, a part says no, and the parts after it never see the extra.

People, client apps and schedulers have no limits. They set the pace with the lines they send. For a part where traffic starts, such as people or an app, the Traffic tab asks instead how many use it at once on a normal day. See [people online](https://docs.flozu.app/guides/scenarios.md#people-online).

![The Traffic tab for App servers: on a normal day it is 66% busy across 3 copies, with 300 a second coming in. Below, 150 a second per copy, auto-scaling between 2 and 20 copies, a new copy starting in 90 seconds, the typical 50 ms a request, and no cost set.](https://docs.flozu.app/_astro/inspector-traffic-light.CuYaKJLH_Z1NuBcj.webp)

Below its limits, **Takes** says how long the part takes to handle one request, and **Costs** what it costs to run for an hour. Scenarios use them to [estimate response times and cost](https://docs.flozu.app/guides/response-times-and-cost.md).

> **Tip**
>
> You don’t need every number for a map to be useful. Start with the rates where traffic comes in and the capacity of the parts you’re worried about. A part with no capacity is shown as “not checked” in scenarios, rather than guessed at.

## How a part copes

Once a part has a limit and traffic reaches it, its **Traffic** tab opens on how it copes: how busy it is, how many copies it runs, how much comes in, and its health, from underused to overloaded. With no scenario running, that’s a normal day. While a [scenario](https://docs.flozu.app/guides/scenarios.md) runs, it’s the part’s busiest moment in that scenario, and the tab says when that is.

### Find the capacity a part needs

Choose **Try other capacities**. Tiles offer round numbers around today’s, each filled to how busy it would make the part, and a slider marks where the part turns healthy. Two tiles compare the moment above with a second one: a normal day while a scenario runs, or five times a normal day when none does. Nothing changes until you choose **Apply**, which you can undo in one step.

![Trying other capacities for Email worker during Black Friday: it is 438% busy at 00:10 with 20 a second. Tiles from 20 to 200 a second are filled from red to green, 150 is picked, the slider marks healthy from 126 a second, and the two tiles show Black Friday at 58%, healthy, and a normal day at 8%, underused.](https://docs.flozu.app/_astro/try-capacity-light._ndGs3U3_SuvPi.webp)

## How it shows on the map

While the map plays:

- **Flowing.** Dots move along each line at a pace set by its rate.
- **Backing up.** When more arrives at a part than its capacity, its buffer fills.
- **Overflowing.** When the buffer is full, or there is none, the extra spills over and the part says so.
- **Turned away.** Past a part’s limit, as at a rate limiter, the extra is turned away and never reaches the parts after it.

Colour only shows up when it means something: grey until there’s something to say, amber when a part is tight, red when it’s over. While a scenario runs, each part with a limit also gets a [health strip](https://docs.flozu.app/guides/scenarios.md#on-the-canvas) along the foot of its card.

## Auto-scaling

A part that auto-scales runs more copies of itself as traffic grows and fewer as it falls, as a cloud service or a container platform would.

Say 300 requests a second arrive at your app servers, and one copy handles 150. Two copies would be flat out, at 100%. Flozu keeps each copy under 70% busy, so it runs three, each 66% busy. On Black Friday it might run twenty.

### Turn it on

Select a part that has a capacity, open its **Traffic** tab and set **Scales** to **Auto**:

- **Per copy:** the capacity now counts for one copy, such as 150 requests a second.
- **Copies:** the fewest and the most it runs, as whole numbers from 1 to 1,000.
- **Starts in:** how long a new copy takes before it takes traffic. It starts at the kind’s usual time: a couple of seconds for a function, 90 for a service, 10 minutes for a database or search. Type a length such as “45 s” or “3 min”.

### How it scales

In a scenario, a part that auto-scales runs the fewest copies, between its fewest and its most, that keep each copy under the [spare room](https://docs.flozu.app/guides/scenarios.md#advanced) you aim for, 70% busy by default. That’s what an auto-scaler aiming at that target would do. Copies change what a part can handle, never the traffic it sends on.

New copies take time to start. A spike that arrives faster than a new copy starts runs the part over until its copies are up. Running past its spare room while copies start isn’t flagged, since that’s how auto-scaling works, but running over its capacity is.

### See the copies on the map

While a scenario runs, a part that auto-scales adds its copies to its health strip: “3/10”, or on a wider card “3 of 10 copies, 2 starting”. The widest cards show a pip for each copy it may run, up to 12, filled while it runs and pulsing while it starts. The copies past its first also stack up behind its card, sliding out as they start.

![App servers on Black Friday, on a wide card: 274% overloaded, with a pip for each of the 12 copies it may run, 5 filled and 7 hollow as they start, and its copies stacked behind the card.](https://docs.flozu.app/_astro/scaling-copies-light.DDllWGYJ_Z1OcBEM.webp)

### What scenarios suggest

Scenarios check auto-scaling both ways, and each suggestion has an **Apply**:

- **Keep more running** (keep warm) when it ran over while new copies were starting.
- **Let it scale in** when it keeps more copies running than its quietest moment needs.
- **Raise its most copies** when it ran out of copies, with how many it needs.

See [scenarios](https://docs.flozu.app/guides/scenarios.md#fix-what-it-finds).

---

# Scenarios

> Ask "what if?" of a map, such as Black Friday or a product launch, play it over time, see which part runs short first, and apply the fix.

Your orders API copes fine today. Will it on Black Friday, when seven times as many people show up at midnight? A scenario plays that day on your map and shows you the answer before your customers find it: which parts run short or fail, when, for how long, and what would fix them.

A scenario can be a busy day, a TV ad that sends everyone at once, a launch, steady growth, or something breaking. Flozu has 9 ready-made ones, and you can make your own.

## Try it

On the **Checkout system** template:

1. Open **Scenarios** in the map’s menu and pick **Black Friday**. A timeline appears along the bottom, and the map shows the busiest moment, ten past midnight.

2. Read the card at the top of **What happens**: 2 of 3 parts need room, the busiest at 438%.

3. On the canvas, the Email worker is outlined in red. About 88 emails a second reach it, and it can send 20.

4. Under **Fix it**, Flozu says to give it 126 a second, or run 7 copies. Select **Apply**, and the red outline goes.

![Black Friday on the checkout map: the scenario panel on the left says two parts need more room, the email worker is outlined in red on the canvas, and the timeline along the bottom shades the hours it's short.](https://docs.flozu.app/_astro/scenario-light.D50hHthp_2r0uL7.webp)

[Will it survive Black Friday?](https://docs.flozu.app/walkthroughs/black-friday.md) walks through the same thing with every number explained.

> **Note**
>
> Flozu never runs or calls your systems. A scenario is worked out from the rates and limits on the map, so it’s only as good as those numbers. See [how traffic is worked out](https://docs.flozu.app/concepts/how-traffic-is-worked-out.md).

## Pick a scenario

**Scenarios** lists the map’s own saved scenarios under **On this map**, then the ready-made ones, such as Normal day, Black Friday, Product launch, Back after an outage and Region down. See [ready-made scenarios](https://docs.flozu.app/reference/scenario-presets.md) for what each one does. **Scenario** at the top of the panel switches to another without going back to the list. Choosing **Scenario** in the mode menu at the foot of the canvas goes straight in.

To end a scenario, choose another mode or close the panel.

## Read what happens

The **What happens** tab opens on the outcome: how many parts need room and the busiest one’s share in big numbers, a bar with a segment for each part coloured by how it copes, and a sentence, such as “2 parts need more room on Black Friday”. Under it, **Fix it** lists the first three fixes.

![What happens for Black Friday: a card saying 2 of 3 parts need room with a coloured bar and the outcome, then Fix it with each part that needs more room and its fix, then a row each for Moments, Time and cost, Weak spots, The odds and What copes.](https://docs.flozu.app/_astro/needs-more-room-light.tXuLJjeI_2dF7W7.webp)

Below that, each row has a headline, such as “4, trouble from 00:00” for **Moments**. Select a row to go in to it, and the way back at the top to come out. What you find in a row stays there while you look at something else.

| Row                                 | What it tells you                                                                                                                                                                                                                                    |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Every fix**                       | Every fix, when there are more than three.                                                                                                                                                                                                           |
| **Moments**                         | The busiest and quietest moments, and when each part first gets tight, runs over, turns traffic away or fills its buffer. Select one to move the timeline there.                                                                                     |
| **Needs more room**                 | Each part that’s ever short, worst first, at its own worst moment, with the fix sized for that moment, such as “Give it 126/s of capacity, 6.3 times today’s, or run 7 copies”. The **i** beside it says for how long and from when.                 |
| **Time and cost**                   | Keep more copies running, let a part scale in, or make a part smaller when even its busiest moment uses under 30% of it. And [estimates](https://docs.flozu.app/guides/response-times-and-cost.md) of how long requests take and what the map costs. |
| **Blast radius** and **Survive it** | For a scenario where something fails: what each failure touched, and what would carry on next time. See [failure drills](https://docs.flozu.app/guides/failure-drills.md).                                                                           |
| **Weak spots**                      | **Find weak spots** takes each part and zone down in turn at the busiest moment, and lists the ones that hurt most.                                                                                                                                  |
| **The odds**                        | For a scenario with random spikes: how often each part runs short over many runs. See [the odds](#the-odds).                                                                                                                                         |
| **What copes**                      | The parts with room to spare, and the ones with no capacity set.                                                                                                                                                                                     |

Select a part in the panel to select it on the canvas and move the timeline to its worst moment.

## Fix what it finds

Each fix has two buttons:

- **Apply** makes the fix on the map as one change, so one undo takes it back.
- **Try it** makes it in a [proposal](https://docs.flozu.app/guides/versions-and-proposals.md) instead: a copy of the map you can compare with the original, with the same scenario playing on both. The map itself doesn’t change until you adopt it.

With more than one fix, **Try every fix in a proposal** makes them all in one, called “Cope with Black Friday”. A fix that changes the map’s shape, such as a standby copy, always starts as a proposal.

![A proposal called Cope with Black Friday on the checkout map, marked Copes now at the top: the scenario panel says all 3 checked parts cope on Black Friday, and the timeline sits at the day's busiest moment.](https://docs.flozu.app/_astro/black-friday-fix-light.U180IgwX_1G4hTv.webp)

The scenario plays on the map as it stands, so changing a capacity in the inspector shows on the canvas straight away.

## On the canvas

While a scenario runs, the canvas shows the moment at the timeline’s playhead:

- Each line’s dots move at its rate then, and its label says the rate.
- Each card’s figure counts the traffic then.
- A part with a capacity or a limit has a **health strip** along the bottom of its card: how busy it is, as a share of what it can take, and a meter with a tick at the spare room to keep. Hover the strip to read it all in words.
- Busy, critical and over parts are outlined in their colour, and an over part breathes. The lines into it turn red and slow down, as the work backs up.

| Health        | When                                                                                                                    | Colour |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- | ------ |
| **Underused** | Under 30% busy, or under the spare room if that’s less.                                                                 | Blue   |
| **Healthy**   | Between underused and the spare room.                                                                                   | Green  |
| **Busy**      | Past the spare room, 70% busy by default.                                                                               | Yellow |
| **Critical**  | Past 90%, or past the spare room if that’s higher.                                                                      | Orange |
| **Over**      | Past its capacity: **Overloaded**, **Queueing** when work backs up, or **Turning away** when its limit refuses traffic. | Red    |
| **Down**      | A failure took it down, so nothing gets through. Its card fades behind a dashed outline.                                | Red    |

A part that fails some of its traffic, because something after it is down, adds the share that fails to its strip, such as “33% fail”.

## The timeline

The timeline along the bottom draws how many people are online (or the multiple of today) across the scenario. An amber line along its top marks where a part is tight, a red one where it’s over, and diamonds mark the moments worth stopping at. The header says the time, the scenario, how busy it is then as a multiple of today’s busiest, and whether everything copes.

![The timeline for Black Friday: a curve of traffic across the day from 00:00 to 24:00, marked red along the top where parts need room, with the playhead at 00:10.](https://docs.flozu.app/_astro/timeline-light.B5yrEedO_ZNuc2f.webp)

It opens at the scenario’s worst moment. To move through it:

- **Drag** along it, or click anywhere on it.
- Use the **arrow keys** for small steps, `Shift` with the arrows for bigger ones, and `Home` and `End` for the start and the end. `Space` plays and pauses.
- **Skip** to the previous or next moment with the buttons on the right.
- **Play** it through in about 30 seconds. The canvas follows the playhead.

In a [failure drill](https://docs.flozu.app/guides/failure-drills.md), each failure has a bar along the foot of the graph, red for down and dashed amber for degraded, the stretch where traffic fails is shaded red, and the header says what’s wrong, such as “4 parts down, 33% failing”.

### Moments

The moments marked on the timeline are the ones **Moments** lists, and a [story](https://docs.flozu.app/guides/stories.md) step can stop at any of them:

| Moment                          | When                                                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------------------------------- |
| The busiest moment              | Traffic at its highest.                                                                                 |
| The quietest moment             | Traffic at its lowest.                                                                                  |
| _Part_ gets tight               | That part first runs past its spare room.                                                               |
| _Part_ runs over                | That part first runs past its capacity.                                                                 |
| _Part_ turns traffic away       | That part first turns traffic away at its limit.                                                        |
| _Part_’s buffer fills           | That queue or topic first fills up.                                                                     |
| _Part_ goes down                | A failure takes it down, or a zone or several parts. A line _is cut_, and a degraded one _is degraded_. |
| _Part_ moves traffic over       | Traffic moves off what failed, onto a standby or the lines beside it.                                   |
| _Part_’s requests start failing | Some of what starts there first fails.                                                                  |
| _Part_ is back                  | The failure ends.                                                                                       |
| Everything copes again          | Everything is clear again.                                                                              |

## Make your own

The **Set up** tab shapes the scenario. Changing a saved or ready-made scenario turns it into a draft, shown as such in the picker.

Say you’re running a TV ad at 8pm and expect three times the usual traffic for twenty minutes. Start from **Normal day**, and under **Events** add a **Spike** at 20:00 to a level of 3, holding for 20 minutes. Play it, and **What happens** says whether you’re ready.

### People online

For each part where traffic starts, how many people use it at once on a normal day: at the busiest moment, at a typical one and at the quietest. Leave it out and a scenario counts in multiples of today. You can also set this in the part’s **Traffic** tab.

### Timeframe

How long the scenario runs, from 10 minutes to 4 weeks; the time of day it starts; whether it follows a day’s rhythm (quietest at about 4am, busiest at about 8pm) or stays steady; and how busy it runs, as a multiple of today’s busiest moment.

### Events

What happens to people over the timeframe. Each event has when it starts, its shape, and whether it reaches everyone or just one part where traffic starts, such as a push notification that only reaches the app.

| Event      | What it does                                                       | For example                                          |
| ---------- | ------------------------------------------------------------------ | ---------------------------------------------------- |
| **Spike**  | Rises to a level, holds, then falls back.                          | A TV ad, a newsletter, a ticket drop                 |
| **Growth** | Grows to a level over a length of time, and stays there.           | A launch that keeps growing for a week               |
| **Outage** | Nobody gets through for a while, then everyone comes back at once. | Your provider’s outage, then the rush when it’s back |

Levels are multiples of a normal day’s busiest moment, so a map of 200 people and a map of 2 million both get a sensible Black Friday. Type lengths as “90 s”, “10 min” or “2 days”.

### Failures

Take a part, a line or a whole zone down for a while, or leave it degraded with only part of what it can take. You can also right-click it on the canvas and choose **Take down here**. See [failure drills](https://docs.flozu.app/guides/failure-drills.md).

### Random spikes

Up to how many random spikes to add, and the range of their peak, rise and hold. **Wobble** adds small moment-to-moment changes. A scenario always plays the same way until you choose **Roll again**, so you can show the same run to someone later.

### Advanced

The **spare room** to keep, 30% by default (so a part aims to run at most 70% busy), and a plain steady multiple of today’s busiest for an hour.

## Save a scenario

A draft belongs to this window only. **Save with the map** keeps it with the map, so it travels in files and share links, shows under the map in the **Maps** panel, and [stories](https://docs.flozu.app/guides/stories.md) can use it. Changes to a saved scenario save as you make them, each one step to undo. **Delete** removes it from the map and keeps showing it as a draft.

## The odds

One run of a scenario with random spikes can be lucky. The odds play it many times, each with different spikes, and say how often each part runs short.

1. Open **The odds**, under **What happens**, for a scenario with random spikes or wobble.

2. Pick how many runs, from 20 to 200, and select **Try**. **Stop** ends them early.

![The odds section after 50 runs: everything copes in 0 of 50 runs, with Show the worst run, and the email worker short in 50 of 50 runs with a fix sized to cope in 95% of them.](https://docs.flozu.app/_astro/odds-light.ChUrOgMa_Z1p86SO.webp)

The result says:

- **How many runs everything copes in,** such as 41 of 50.
- **How often each part runs short,** over its capacity or turning traffic away.
- **The fix that copes in 95% of runs,** for each part that runs short, with its **Apply**. It’s sized from the run at the 95% mark when the runs are put in order of what that part needs.
- **Show the worst run,** which sets the scenario to that run, so you can watch it on the timeline.

A scenario with no random spikes and no wobble plays the same every time, so it has no odds to try.

## In presenting

Presenting offers scenarios too, so a client can watch Black Friday play out. It leaves out the fixes, saving and people fields. See [presenting](https://docs.flozu.app/guides/presenting-and-sharing.md).

---

# Failure drills

> Pull the plug on a part, a line or a whole zone in a scenario, see what fails and what takes over, find the parts your map can least afford to lose, and try the fixes in a proposal.

What if the database goes down at the evening peak? What if a whole cloud region goes dark for half an hour? A failure drill takes it down in a [scenario](https://docs.flozu.app/guides/scenarios.md), plays it through, and shows what fails, what takes over, how many people notice, and what to change so they don’t next time.

> **Note**
>
> Flozu never breaks your real systems. A drill is worked out from the lines and kinds on the map, by [fixed rules](https://docs.flozu.app/concepts/how-traffic-is-worked-out.md#when-something-fails), so it plays the same way every time.

## Try it

On the **Checkout system** template:

1. Open **Scenarios** and pick **Region down**. It takes the map’s busiest region down for half an hour at the day’s peak.

2. Everything in AWS eu-west-1 is dashed in red and marked **Down**. Shoppers and the web shop show **33% fail**: every order needs the region, and orders are a third of what shoppers do.

3. Under **Fix it**, select **Try it** beside the second zone. A proposal opens with a standby copy of the region, and the top left says **Copes now**.

![Region down on the checkout map: the AWS eu-west-1 region and everything in it are dashed in red and marked Down, Shoppers and the web shop show 33% fail, the panel says up to 33% of Shoppers' traffic fails for 30 minutes, and the timeline marks the half hour it's down.](https://docs.flozu.app/_astro/failure-drill-light.Begv5NG0_eIzt8.webp)

[What if something breaks?](https://docs.flozu.app/walkthroughs/what-if-it-breaks.md) walks through a database and a region going down, with every number explained.

A map with no regions loses its busiest zone instead, or its busiest part.

## Break something of your choosing

While any scenario runs:

- **Right-click** a part, a zone or a line on the canvas and choose **Take down here**, or **Cut here** for a line. It goes down at the playhead, for 10 minutes.
- Or open **Set up** in the scenario panel and add it under **Failures**, to choose how long and how badly.

![Right-clicking Orders DB on the canvas opens a menu with Take down here.](https://docs.flozu.app/_astro/take-down-light.DlzO3A8y_ZDxO17.webp)

A drill changes the scenario’s draft, never the map. Save it with the map to keep it, the same as any scenario.

### Set up a failure

Under **Set up**, **Failures** lists each failure in the scenario. **Take down** adds one. What’s selected on the canvas comes first in its menu, so you can select several things and take them down together.

![The Failures section under Set up: failure 1 breaks AWS eu-west-1, down, starting 45 minutes in and lasting 30 minutes, with Take down below to add another.](https://docs.flozu.app/_astro/failure-setup-light.C7h2oN8C_ZlW42J.webp)

| Field      | What it sets                                                                                                                               |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Breaks** | The part, line or zone that fails. A zone takes everything in it down, including the zones inside it.                                      |
| **How**    | **Down**, so nothing gets through, or **Degraded**, so it keeps only part of what it can take, like a database with one of its disks gone. |
| **Keeps**  | For a degraded failure, how much it keeps, from 10% to 90%. A part that auto-scales keeps that share of its copies.                        |
| **Starts** | How far into the scenario it fails, such as “45 min”.                                                                                      |
| **Lasts**  | How long it stays down, from a minute to a day, or until the end.                                                                          |

## Read what happens

The panel’s summary says what fails at its worst, such as “When AWS eu-west-1 goes down, up to 33% of Shoppers’ traffic fails, for 30 minutes”, or that nobody notices.

- **Blast radius,** a row under the summary, lists each failure: how much of the traffic fails where it starts, for how long, about how much in all, and every part it touched, down, failing, short of room or filling up. Select one to see it on the canvas.
- **Fix it** starts with what to change to survive it, with why it matters behind the **i**.

![Blast radius for Region down: AWS eu-west-1 goes down at 19:45, up to 33% of Shoppers' traffic fails for 30 minutes, about 71,785 in all, and Email worker, Order events, Orders API and Orders DB are listed as Down.](https://docs.flozu.app/_astro/blast-radius-light.B_3DVv22_ZG7J52.webp)

On the canvas, at the playhead:

- **A part that’s down** fades behind a dashed red outline, its live panel stops, and its health strip says **Down**.
- **A zone that’s down** is dashed in red with **Down** after its name, or **Degraded** in amber.
- **A line into something that’s down** turns red, and its dots fade out before they arrive. A line that’s cut is dotted, and its label says **Cut**.
- **A line taking traffic over,** such as a standby, draws thicker.
- **The parts that send the traffic** show the share that fails on their strip, such as “33% fail”.

The [timeline](https://docs.flozu.app/guides/scenarios.md#the-timeline) marks each failure on a row under its graph and shades in red where traffic fails.

## Fix it

Some failures need more room: a part that ran short taking traffic over, or a queue that filled while the part after it was down. Flozu sizes those fixes, and **Apply** makes them.

Others need a change of shape. A part or zone that nothing takes over from is a **single point of failure**, and more capacity won’t help. Flozu offers one of these:

| Fix                | What it adds                                                                                                                                                  | When                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **Standby copy**   | A copy of the part beside it, with its lines in as [standbys](https://docs.flozu.app/guides/lines.md#standby-lines). It carries nothing until the part fails. | Most parts                                             |
| **Second copy**    | A copy beside it, sharing the traffic half each.                                                                                                              | When a load balancer or DNS sends the part its traffic |
| **Second zone**    | A copy of the zone beside it, with a copy of everything in it, on standby or sharing.                                                                         | A zone that goes down                                  |
| **Queue in front** | A queue the requests go through instead, so work waits there while it’s down.                                                                                 | A worker or a function that takes requests             |

A fix to the map’s shape always starts as a proposal: **Try it** opens one named for the fix, with the fix made and the same scenario at the same moment. With two or more fixes, **Try every fix in a proposal** makes them all in one, called “Survive Region down”. Inside a proposal, every fix has **Apply** instead, and **Make every fix** makes them all as one step to undo.

![Fix it for Region down: nothing takes over when AWS eu-west-1 goes down, so 33% of Shoppers' traffic fails, and the fix, a second zone beside it with a copy of everything in it on standby, has a Try it button.](https://docs.flozu.app/_astro/try-fix-light.CgAqbTWN_9vwLP.webp)

## See the fix hold

While a scenario runs on a proposal, the top left says what the proposal does to how the map copes: **Copes now**, **Copes better**, **No better**, **Copes worse** or **Copes, as before**. Hover over it for the whole story, such as “Before, up to 33% of Shoppers’ traffic fails for 30 minutes. After, nobody notices.”

![A proposal with a standby copy of AWS eu-west-1 below the region that's down: the copy carries the traffic, the panel says nobody notices, and the top left says Copes now beside the proposal's name.](https://docs.flozu.app/_astro/proposal-verdict-light.Cly_0Ch9_VntVv.webp)

Select it to compare the proposal with where it began, with the drill playing on both and one timeline driving both maps. See [replay a scenario](https://docs.flozu.app/guides/versions-and-proposals.md#replay-a-scenario). To walk others through the drill, the fix and the replay, [make a story](https://docs.flozu.app/guides/stories.md#show-a-fix-and-its-replay), as in [make the case for a fix](https://docs.flozu.app/walkthroughs/make-the-case.md).

## Find weak spots

Not sure what to drill? Open **Weak spots**, under **What happens** in any scenario, and select **Find weak spots**. Flozu takes each part and each zone down in turn for an hour at the scenario’s busiest moment, and lists them by how much fails where traffic starts, worst first. **Drill this** adds that failure to the scenario.

![Weak spots on the checkout map: losing the web shop fails all of Shoppers' traffic, and AWS eu-west-1, Orders API and Orders DB each fail up to 33% of it, each with Drill this.](https://docs.flozu.app/_astro/weak-spots-light.GK3l50o8_ZmEqUR.webp)

On the checkout, the worst one isn’t in the cloud: losing the web shop fails everything, because every shopper goes through it.

## Good to know

- **Taking something down from the keyboard:** move the focus to it with `Tab` and press the menu key or `Shift` + `F10`.
- **Coming back is cold.** When a failure ends, a part that auto-scales waits for its copies to start, and its strip says **Starting** until one has.
- **Some parts need no standby.** A load balancer or DNS spreads traffic over its other lines when one fails. A cache that’s down sends its reads on to the database behind it. A queue holds work for a part that’s down until its buffer is full.
- **Weak spots leave some parts out:** the parts where traffic starts, the people sending it, and parts that only other parts use.
- **Fixes land beside what they copy,** with their lines, and grow the zones around them to fit.
- **A standby line** needs a line beside it from the same part, of the same kind, to the same kind of part. Set it with **Use** in the line’s **Traffic** tab. See [standby lines](https://docs.flozu.app/guides/lines.md#standby-lines).

---

# Response times and cost

> See roughly how long requests take where traffic starts, how much of it fails, and what the map costs to run, while a scenario plays, and what a fix does to each.

A fix that stops an outage is easy to want. The question that follows is always “what will it cost, and will it slow anything down?” While a [scenario](https://docs.flozu.app/guides/scenarios.md) plays, Flozu estimates three things to answer it: how long requests take where traffic starts, how much of that traffic fails, and what the map costs to run.

On the **Checkout system** map on Black Friday, shoppers’ requests take about 39 ms, and 95% are done within about 78 ms. Give its parts running costs, as [Make the case for a fix](https://docs.flozu.app/walkthroughs/make-the-case.md) does, try a standby region for Region down, and the comparison says: “After, nobody notices, for about $1,241 a month more.” That’s a decision you can take to your team.

These are estimates, worked out from the map by [fixed rules](https://docs.flozu.app/concepts/how-traffic-is-worked-out.md#estimates), so they’re a guide for comparing one design with another rather than a measurement.

![The Estimates section on Black Friday: Shoppers' requests take about 39 ms, and 95% are done within about 78 ms, with none of their traffic failing, and running costs of about $1.18 an hour, $861 a month at that rate and $28.32 for the whole scenario.](https://docs.flozu.app/_astro/estimates-light.DanP7pIY_SrCuU.webp)

## What the estimates say

**Estimates**, under **Time and cost** in **What happens**, lists each part where traffic starts, such as your shoppers, with:

- **How long requests take,** typically, and the time 95% of them are done within. It adds the slowest moment when that’s well past the rest, or when some requests time out.
- **How much of its traffic fails,** across the scenario and at its worst. That’s everything a failure breaks, what a limit or a full buffer turns away, and what waits so long it times out.

Then **Running costs**, once a part has a cost: what the map costs an hour on average, a month at that rate, and for the whole scenario, and an hour at its dearest moment. Select it to see the parts that cost something, at that moment.

Hover over a part’s health strip on the canvas to see roughly how long it takes at the playhead, such as “about 140 ms each”.

## Give a part its time and cost

Select a part and open its **Traffic** tab:

| Field | What it sets                                                                                                                                      |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Takes | How long it takes to handle one request while it has room, in milliseconds. Left empty, it takes a typical time for its kind, shown in the field. |
| Costs | What it costs to run for an hour, in dollars. For a part that auto-scales, what one copy costs, and a scenario adds up the copies it runs.        |

A queue or topic only holds work, so it has a cost but no time. People and apps where traffic starts have neither.

> **Tip**
>
> You don’t need a cost on every part. Give one to the parts whose cost changes with your design, such as the ones that auto-scale, and compare the totals.

### Typical times

A part with no time of its own takes the typical time for its kind:

| Part           | Takes  | A new copy starts in |
| -------------- | ------ | -------------------- |
| DNS            | 20 ms  | None                 |
| CDN            | 20 ms  | None                 |
| Firewall       | 2 ms   | 60 s                 |
| Gateway        | 5 ms   | 60 s                 |
| Sign-in        | 100 ms | 2 min                |
| Load balancer  | 1 ms   | 60 s                 |
| Rate limiter   | 1 ms   | 30 s                 |
| Service        | 50 ms  | 90 s                 |
| Worker         | 500 ms | 90 s                 |
| Function       | 100 ms | 2 s                  |
| Scheduler      | None   | 60 s                 |
| AI model       | 2 s    | 5 min                |
| Queue          | 5 ms   | 2 min                |
| Topic          | 5 ms   | 2 min                |
| Database       | 10 ms  | 10 min               |
| Cache          | 1 ms   | 5 min                |
| Search         | 50 ms  | 10 min               |
| Storage        | 50 ms  | 60 s                 |
| Data warehouse | 2 s    | 2 min                |
| Endpoint       | 50 ms  | 90 s                 |
| Module         | 10 ms  | 90 s                 |
| Code file      | 5 ms   | 90 s                 |
| Table          | 5 ms   | 10 min               |
| Custom part    | 50 ms  | 2 min                |

## See what a fix costs

Fixes come with what they cost, where the parts have one:

- **Time and cost** advice says what keeping more copies warm costs a month, or what letting a part scale in saves.
- On the [Compare screen](https://docs.flozu.app/guides/versions-and-proposals.md#replay-a-scenario), the verdict adds the change in cost, such as “After, nobody notices, for about $310 a month more”. Below it, **Requests take, typically** shows where requests got faster or slower, where none of them fail on either map, and **Running costs** what each map costs a month at that rate.

---

# Presenting and share links

> Show a map read-only to clients and colleagues, and send a link that carries the whole map, which nobody needs an account to open.

Your client wants to see how their traffic flows through your platform, and what happens on their busiest day. You want them to look, play scenarios and ask questions, without dragging a database across the screen by accident. Present the map, or send a link that opens it presented.

## Try it

On the **Checkout system** template, choose **View** from the mode menu at the foot of the canvas. Select **Orders DB**: the details panel shows what it is, what it’s built with and how much traffic it takes, with nothing to edit. Then choose **Scenario** and pick **Black Friday** to play it, just as your client would.

## Present a map

Choose **View** from the mode menu on the island at the foot of the canvas to present the map.

![The checkout map presented: View chosen in the mode menu on the island at the foot, Orders DB selected, and a details panel showing its kind, technology, traffic in and capacity.](https://docs.flozu.app/_astro/present-light.C4E4FlJR_Z1FmWtI.webp)

A presented map still pans, zooms, plays and selects. Nothing drags, connects, deletes, renames or adds, and the keys that edit do nothing. There’s no parts library and no undo.

The **details** panel takes the inspector’s place, with the same layout but values in place of fields. A part shows its kind, what it’s built with, its traffic in and out, its capacity, limit and buffer, and its lines with their rates. With nothing selected it says how to read the map.

From the mode menu on the island at the foot of the canvas you can:

- Choose **Scenario** to try one, such as Black Friday. See [scenarios](https://docs.flozu.app/guides/scenarios.md).
- Choose **Story** to play one, when the map has one. See [stories](https://docs.flozu.app/guides/stories.md).
- Choose **Edit** to go back to the editor.

Beside the mode menu you can **pick a view**, when the map has more than one (see [views](https://docs.flozu.app/concepts/views.md)). A view only hides things, so scenarios and drills still play on the whole map. The **Actions** menu shares a link and shows or hides the details. A template or a shared map has **Use this template** or **Save a copy** at the end of the island.

Presenting never saves anything. Its address is the map’s own with `/view` on the end.

## Share a link

Choose **Share a link…** from the **Actions** menu on the island. Flozu makes a link that carries the map itself and copies it. Anyone who opens it sees the map presented, read-only, and can save their own copy.

![The Share a link popover: the link, copied, with a note that it holds the map as it is now.](https://docs.flozu.app/_astro/share-light.BNzWBMZs_Z2ki1JK.webp)

What you should know about a link:

- **It needs no server.** The map is packed into the link itself, after `#/shared/`. That part of a link never leaves the browser, so the map isn’t sent to whoever hosts Flozu.
- **It’s a snapshot.** It holds the map as it was when you made it. Make a new link after you change something.
- **It holds only what its view shows.** When you share from a view that hides parts, the link leaves them out entirely. A drill on a zone the view hides still takes down the parts that were in it.
- **It carries stories and saved scenarios,** so whoever opens it can play them too.
- **Very large maps make long links.** Links over 8,000 characters work in a browser but some apps cut them short, and Flozu says so. Export the map as a file instead.

> **Caution**
>
> A link made on my.flozu.app works for anyone. While you run Flozu from its source on your own computer, its links open Flozu on that computer only, and the share popover says so.

## Open a shared link

A shared map opens presented, checked and updated like any file. **Save a copy** keeps it as one of your own maps, beside (never over) a map you already have, and opens it in the editor. A link that’s been cut short, or isn’t a map, goes to home and says so.

---

# Stories

> Walk people through a map one step at a time, like slides, with each step framing the parts it's about and the load at that moment.

A story walks people through a map one step at a time, like slides, to explain how it behaves: where the load lands first, what happens next, and how a fix helps. Every step is the live map, not a picture of it, so when someone asks “what’s that?”, you can select it and show them.

The quickest way to see one is to play one. Open the **Encore ticket drop** example from **Templates**, choose **View**, then **Story**, and step through “If eu-west-1 goes down” with the arrow keys. To make your own, see [Explain your system to someone new](https://docs.flozu.app/walkthroughs/explain-it.md), or read on.

A map can hold several stories, such as one for a client and one for a new developer, and they travel with it in files, copies and share links.

## A step

A step has:

- **A title** and a few words on what’s happening.
- **A focus:** the parts, lines, zones and notes it’s about. While the step is on screen, the camera glides to frame them and everything else fades back. A step with no focus shows the whole map.
- **A moment,** optionally: a time in one of the map’s saved scenarios, such as “Black Friday at 20:00”. The map shows the load at that moment.
- **Parts shown differently,** optionally: other limits for this step only, such as a fix (“with three copies, it copes”), without changing the map. A part’s time and cost stay its own, so they follow the map as it changes.
- **A comparison,** optionally: one of the map’s proposals against where it began, with the step’s moment playing on both. See [show a fix and its replay](#show-a-fix-and-its-replay).

## Make a story

![The stories panel listing a Black Friday story's six steps, from the whole map at 00:00 to With more room, and the first step's card below the map with its title and words as fields, and buttons for its moment, framing and More.](https://docs.flozu.app/_astro/stories-light.BnTqS7jP_24hwb.webp)

Select **Stories** on the map’s menu in the panel on the left. It lists the map’s stories; pick one to go in to its steps, or **New story** to start one. A map with no stories yet goes straight to how to start one. Choosing **Story** in the mode menu at the foot of the canvas goes straight in too, and **Back to Stories** at the top of the panel goes back to the list.

1. **New story** starts one, with a first step about whatever is selected.
2. **Add a step** adds one after the step you’re on, about what’s selected.
3. Pick a step to see it on the canvas as it will play. You edit it on its card, below the map: the same card people see when you present, so what you type is what they read. Type its title and words in place. The **i** beside **Steps** says so too.
4. **Use selection** sets its focus from what’s selected on the canvas. **Whole map** clears it.
5. The scenario and moment buttons pick a saved scenario and a time in it.
6. The comparison button picks a proposal to compare, once the map has one.
7. **More** opens **Shown on this step only**, which picks parts to show with other limits, starting from their own. Changing a part’s copies there keeps how fast they start.

Move steps up and down, or delete them, from their menus. Every change is one step to undo. **Play** presents the map from the first step.

### A story from a scenario

Once a map has a [saved scenario](https://docs.flozu.app/guides/scenarios.md#save-a-scenario), the stories panel offers to draft a story from it: **From Black Friday**, say. It makes a first step at the start, a step at each moment worth stopping at, in time order, each framing the part it’s about, and, when parts run short, a last step called “With more room” that shows them with the fixes the scenario suggests. It’s all one step to undo, and a good place to start editing.

## Play a story

![A story playing: the camera framed on the email worker, outlined in yellow with its strip reading 84% Busy, with the story's steps along the foot reading Step 2 of 6, Email worker gets tight, Black Friday at 00:00.](https://docs.flozu.app/_astro/story-player-light.DuLoij-i_Z1MpUvP.webp)

Present a map that has stories, open the mode menu and choose **Story**. The story’s steps take the timeline’s place along the foot of the canvas, with a picker there when there are several stories. It shows which step it is, its title and words, and any part shown differently, with **Back**, **Next** and a dot for each step. A scenario’s timeline never shows at the same time.

- The arrow keys move between steps, and so do `Page Up` and `Page Down`, which is what presentation clickers send.
- `Esc` or the close button leaves the story for the plain map.

Shared links and templates play stories the same way. With reduced motion turned on, the camera jumps instead of gliding.

> **Tip**
>
> Stories don’t hold load of their own: how busy the map is comes from scenarios. A story that never names a moment plays over whichever scenario is being tried.

## Show a fix and its replay

A step can show one of the map’s [proposals](https://docs.flozu.app/guides/versions-and-proposals.md#propose-a-change) against where it began, with the step’s moment playing on both: the fix, and the proof that it works. Pick the proposal with the comparison button on the step’s card.

![A story on the Compare screen: Encore's standby region in eu-central-1 ringed in green as new, the panel saying before, up to 40% of Fans' traffic fails for 30 minutes, and after, nobody notices, for about $1,197 a month more, and the story's step along the foot reading Step 3 of 4, The fix: a standby region.](https://docs.flozu.app/_astro/story-compare-light.Cj1ED_2__8wXuL.webp)

When you present the map, that step opens the [comparison](https://docs.flozu.app/guides/versions-and-proposals.md#compare), with the story along the foot in the timeline’s place. **Next** and **Back** carry on through the story, back to the map for a step without a comparison. **Back to the map**, `Esc` or the close button leave the story. While you edit, the step stays on the map, and the story says what it compares, with a link to open it.

- Proposals are kept beside the map, not in it, so a shared link has none: there the step shows on the map and says its comparison isn’t in this copy. A template’s step says to use the template, since your copy comes with its history.
- Adopting the proposal keeps where it began, so the step still opens its comparison.

### A story from a fix

A story can be told around a fix in one click. Compare a proposal with where it began, play one of the map’s saved scenarios on both, and choose **Tell it as a story** under how each copes. The map opens with a new story in the stories panel:

1. the scenario from its start,
2. the moment it goes wrong, framing what breaks,
3. the fix, comparing the proposal with where it began at that moment,
4. the moment things are well again, or the scenario’s end.

It’s one step to undo, and the words are a draft to change.

The Encore example plays one from start to end: open it from Templates and play the story “If eu-west-1 goes down”.

---

# Versions and proposals

> Save versions of a map to look back on, propose changes in a copy, compare any two side by side with a scenario playing on both, and adopt a proposal.

Before a big change, you want two things: a way back if it goes wrong, and a way to try it without touching the map everyone else is looking at. **Versions** are the way back: the map as it was at a moment you chose. **Proposals** are the safe place to try: a copy of the map you change freely, compare with the original, and adopt only when you’re sure.

## Try it

On the **Checkout system** template:

1. Choose **Versions** from the mode menu, then **Save version**. Call it “Before search”.
2. Choose **Propose a change**, and call it “Add a search service”. The proposal opens.
3. Add a service called “Search” and connect the Web shop to it.
4. From the **Actions** menu, choose **Compare with where it began**. The new part is ringed in green and tagged **New**, and the panel lists the change.

Nothing has changed on the map itself. **Adopt** makes it so; deleting the proposal leaves the map as it was.

## Where they live

A map keeps its history beside it. Choose **Versions** from the mode menu on the island to open its versions, in the panel where the parts library was.

![The versions panel: Save version and Propose a change buttons, then a timeline with Now, Launch (one part removed) and Version 1.](https://docs.flozu.app/_astro/versions-light.DJ2UdzUF_1AHCRm.webp)

## Save a version

**Save version** keeps the map as it is now, with a name (“Version 3” to start with) and a note if you like. The history lists versions newest first, each with when it was saved and how much changed since the one before, such as `+2 −1 ~3`: added, removed and changed. **Now**, at the top, says whether the map has changed since the newest version.

## Restore a version

Choose **Restore** from a version’s menu to put the map back to how that version holds it, saved scenarios and stories included. It’s one step, so one undo puts it back. Before anything replaces the map, Flozu saves the map as it is as a version first (“Before restoring Launch”), so a restore never loses anything.

## Propose a change

**Propose a change** starts a proposal: a copy of the map, named for the change, such as “Add a search service”. It opens in the editor like any map, and its edits save into the proposal, never into the map. The top left says which proposal is open, with the way back to the map. **Compare with where it began**, **Rename proposal…** and **Delete proposal…** are in the island’s **Actions** menu, and **Adopt** is at the end of the island. Deleting asks first, then goes back to the map.

A scenario can start a proposal too: **Try it**, beside a fix, starts one with the fix made. While a scenario runs on a proposal, the top left also says what the proposal does to how the map copes with it, such as **Copes now**. Select it to compare. See [failure drills](https://docs.flozu.app/guides/failure-drills.md#fix-it).

Claude’s changes come in as proposals too, noted “Suggested by Claude.”, including a map of your code drawn again after the code changed. See [mapping a repository again](https://docs.flozu.app/guides/map-your-code.md#mapping-a-repository-again).

### Adopt a proposal

**Adopt** makes the map what the proposal holds:

1. Flozu saves the map as a version first (“Before adopting Add a search service”).
2. The map becomes what the proposal holds.
3. The proposal becomes a version under its own name, marked as an adopted proposal. It keeps where it began, so its menu offers **Compare with where it began**, and a [story step that compares it](https://docs.flozu.app/guides/stories.md#show-a-fix-and-its-replay) still works.

If the map changed since the proposal began, adopting says so, whether you adopt from the history or from inside the proposal. Those changes are kept in that first version, not merged.

## Compare

![Comparing a proposal with where it began: a new Search part ringed in green, the removed Payments part faded and ringed in red, and a panel listing the three changes.](https://docs.flozu.app/_astro/compare-light.Cd-1c6e7_Z1jRxNO.webp)

Choose **Compare with now** or **Compare with the one before** from a version’s menu (or **Compare with where it began** for a proposal, adopted ones included) to see two of a map’s versions on one canvas. Either side can be the map now, a version, a proposal or where a proposal began. Compare is read-only, so it’s safe for showing a proposal to others, and a story’s step can open one as it plays: see [show a fix and its replay](https://docs.flozu.app/guides/stories.md#show-a-fix-and-its-replay).

- **Changes,** the default, draws both at once: a new part ringed in green and tagged “New”, a removed one faded and ringed in red, a changed one in amber, and a moved or resized one with a quiet dashed ring. Lines and zones take the same colours.
- **Before** and **After** show one map each, with its changes marked. Switching keeps the camera still, so your eye can follow what moves.

The panel beside it lists every change, by parts, lines, zones, notes, views, stories and saved scenarios, field by field (“Capacity: 500/s → 2k/s”). Pick one to select it on the canvas. Changes to the map itself come first: its name, its description and how its lines run.

- **A story** says how each step changed: “New step: The fix”, “The peak: words and moment changed” or “Calm: moved to step 3”.
- **A saved scenario** names its settings as the scenario panel does, such as “How busy: 1× → 6×”, and says when its failures changed apart from its other events. Pick one to play it on both maps.

### Replay a scenario

Pick a **Scenario** in the panel to play the same one on both maps. It starts as the scenario the map was running, at the same moment. When the two hold a saved scenario differently, say a proposal moved a drill, both play it as **To** holds it, and **As in** lets you play **From**’s copy on both instead. One timeline drives both: drag it or play it, and **Before** and **After** each show their own map’s health. **Changes** shows the second map’s, with anything it removed as the first had it.

![Comparing a proposal with where it began, with Region down playing on both: the new standby region carries the traffic while AWS eu-west-1 is down, the panel says before, up to 33% of Shoppers' traffic fails for 30 minutes, and after, nobody notices, and lists Shoppers going from 33% failing to none.](https://docs.flozu.app/_astro/replay-light.BshI_bk0_28NuiA.webp)

The panel says first what the change did, such as “Before, up to 33% of Shoppers’ traffic fails for 30 minutes. After, nobody notices.”, then what was in trouble on either map, before → after: how much of the traffic where it starts fails at its worst, and how long each part runs short of room. Both maps play exactly the same scenario, so a failure of something only one of them has is left out of both, and the panel says so.

When the change makes requests faster or slower, or a part has a cost, it also lists [the estimates](https://docs.flozu.app/guides/response-times-and-cost.md): how long requests take, typically, and what each map costs a month. Times only count the requests that get through, so they’re left out where some of the traffic fails on either map. The first sentence then ends with the change in cost, such as “After, nobody notices, for about $310 a month more.”

For a scenario with random spikes or wobble, **Try 50 runs on both** plays the same runs on each and says how often each copes, such as “Copes in 62% → 97% of runs.” A run copes when nothing fails where traffic starts and every part has room, so a part that’s down doesn’t count against it if nobody notices.

Comparing a proposal with where it began while a saved scenario plays, **Tell it as a story** drafts a story around the fix: see [a story from a fix](https://docs.flozu.app/guides/stories.md#a-story-from-a-fix).

## Where history is kept

Versions and proposals are kept beside the map, not inside its file. A map file or a share link is always the map as it is now, with no history. To take the history along, export the map **with its history**. See [import and export](https://docs.flozu.app/guides/import-export.md). Deleting a map deletes its history too. See [where maps live](https://docs.flozu.app/concepts/where-maps-live.md).

---

# Import and export

> Save a map as a picture, a PDF or a file, move whole projects between computers as one bundle, and bring anything Flozu made back in.

Everything in Flozu can leave as a file and come back: one map, a project, or every map you have. The most common reason is a slide deck: choose **Export…** in the **Actions** menu, pick **PNG image**, tick **See-through background**, and the whole map drops onto any slide, sharp at twice its size. Files also back your maps up, move them to another computer, and hand them to someone else who uses Flozu.

## Export

**Export** opens the same dialog wherever you find it:

- **Export…** in the editor’s **Actions** menu, on the island, for the map that’s open.
- A map’s menu on the Maps page.
- A project’s or folder’s menu, on its page and in the **Maps** panel.
- **Export…** in the **⋯** menu on the Maps page: on All maps for every map, and on a project for that project.
- **File › Export…** (`⌘E`) in the [Mac app](https://docs.flozu.app/mac/overview.md), for what’s on show, and **File › Export all maps…** (`⌥⌘E`).

![The export dialog for Checkout system: PNG image chosen, with SVG drawing, PDF, Map file and Map with its history below, a Theme menu and a See-through background box.](https://docs.flozu.app/_astro/export-light.BGVY_5Ic_Z28poYp.webp)

Pick what you want, then **Export**. The dialog offers what fits what you’re exporting.

### A picture of the map

| Choice          | What you get                                                                    |
| --------------- | ------------------------------------------------------------------------------- |
| **PNG image**   | A picture of the whole map at twice its size, for slides and chats.             |
| **SVG drawing** | Real shapes and text that stay sharp at any size, for design tools and the web. |
| **PDF**         | One page of the same shapes and text, for printing and documents.               |

A picture shows the whole map, not just what fits on screen, as it looks now: its styles, zones, notes, line labels and the load of any scenario you’re trying. Motion is stilled, so each part shows its resting frame, and nothing is selected.

- **Theme** draws it dark or light, whichever you’re using now unless you change it.
- **See-through background** leaves the background out of a PNG or SVG, so it sits on any slide.

Pictures need the map on screen, so they’re offered in the editor. From a map’s card, the dialog says to open the map first.

> **Note**
>
> A PDF’s text is in Helvetica, which every PDF reader has, so letters outside Western alphabets don’t show in a PDF yet. Use a PNG or SVG for those.

### A file to open again

| Choice                                     | File                 | What it holds                                                                                                             |
| ------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Map file**                               | `.flozu.json`        | The map as it is now, with its stories and saved scenarios.                                                               |
| **Map with its history**                   | `.flozu-bundle.json` | The map, its versions and proposals, and any [maps inside its parts](https://docs.flozu.app/guides/maps-inside-parts.md). |
| **The project with everything in it**      | `.flozu-bundle.json` | Every map in the project, in its folders, empty folders too.                                                              |
| **The folder with everything in it**       | `.flozu-bundle.json` | The same, for one folder.                                                                                                 |
| **Every map, in its projects and folders** | `.flozu-bundle.json` | Your whole library.                                                                                                       |

A file of several maps is a **bundle**. For a project, a folder or every map, tick **Include versions and proposals** to take their history too. Before you export, the dialog says what the file will hold, such as “It holds 12 maps, 3 folders and 20 versions”.

A bundle also carries any map a part in it opens into that’s kept somewhere else, so its links still lead somewhere when it’s imported.

> **Tip**
>
> In the browser, deleting a folder offers **Export its maps first**, so nothing is lost by accident. In the Mac app, a deleted folder goes to the Trash.

## Import

Bring in any file Flozu exports, three ways:

- **Import** on home, or **Import…** in the **⋯** menu on the Maps page.
- Drop files anywhere on a page of maps.
- **File › Import…** (`⌘O`) in the Mac app.

Maps come into the project or folder on show. Flozu works out what each file is from what’s in it, not its name: a map, a bundle, or a single version, which joins its map when you have it. Maps made by an older version of Flozu are updated as they come in. An outline Claude wrote from your code comes in drawn as a new map: see [map your code with Claude](https://docs.flozu.app/guides/map-your-code.md).

### An import never overwrites anything

- **A map you already have** comes in as a copy beside it, with its own versions. Links to it from other maps in the same bundle follow the copy.
- **A bundle’s top folders** come in under a free name, so a project imported beside itself becomes “Payments 2”.
- **A map a part opens into** isn’t copied again if you already have it.
- **Something that can’t be read,** such as one damaged map, is left out and named, and the rest still comes in.

A bundle that would nest folders more than six deep is refused before anything is made. If a file won’t import at all, see [troubleshooting](https://docs.flozu.app/help/troubleshooting.md#a-file-wont-import).

## Other ways to share

- **A share link** carries a map inside the link, for someone to look at without importing anything. See [share a link](https://docs.flozu.app/guides/presenting-and-sharing.md#share-a-link).
- **In the Mac app** each map is already a file in Documents › Flozu, so anything that syncs that folder moves your maps too. See [files and folders](https://docs.flozu.app/mac/files-and-folders.md).

The files themselves are described in [file format](https://docs.flozu.app/reference/file-format.md).

---

# Your account

> Sign in to keep your maps online and open them anywhere, continue as a guest to keep them in this browser, and download or delete everything Flozu keeps about you.

As a guest, your maps live in one browser on one computer. Sign in, and they follow you: start a map on your laptop, open it on the office desktop, and share it with your team.

![Flozu's sign-in page: Continue with Google or GitHub, Microsoft marked as coming soon, and Continue as guest below, beside a live map of a delivery platform.](https://docs.flozu.app/_astro/sign-in-light.D4zJzBth_Z2gCwTY.webp)

On the web, Flozu opens on its sign-in page. Sign in to keep your maps in your account, where they open on any computer and can be shared with a [team](https://docs.flozu.app/guides/teams.md). Or choose **Continue as guest** to keep them in this browser, as files are kept on a computer.

> **Note**
>
> Flozu is in a private beta. Signing in works for the addresses that have been invited. Anyone can continue as a guest.

## Sign in

Under **Continue with**, choose **Google** or **GitHub**, and sign in there. The first time, Flozu makes your account with the name, email address and picture they share. Microsoft is shown as coming soon.

Continuing agrees to the terms of use, and says you’ve read the privacy notice. Both are linked from the sign-in page, and from **Help** in the app.

## Your first sign-in

The first time you sign in, Flozu asks three quick questions before your maps: where you heard about it, what you do, and what you’d like to use it for. Pick a tile to answer. The first two move on as soon as you pick; the last takes as many as you like, then **Finish**. **Skip**, at the top right, goes straight to your maps, and you won’t be asked again either way. Your answers are kept with your account, and you can see them in [Download my data](#your-account-menu).

Then, and each time you sign in after that, Flozu’s mark settles into its corner as your maps open. Click anywhere or press any key to skip it.

## Continue as a guest

**Continue as guest** opens home with nobody signed in. Your maps are saved in this browser only, so use the same browser each time, or [export them](https://docs.flozu.app/guides/import-export.md) to move them. Flozu remembers the choice in this browser, and signing in later is always there: **Sign in**, last at the top right.

A shared map’s link and the legal pages open for anyone, signed in or not, and the Mac app never asks you to sign in, since its maps are files on your Mac.

## Workspaces

Every map is kept in one workspace. The switcher at the top left lists the ones you can use:

| Workspace           | Who sees it                                                                              | Where you’ll see it                   |
| ------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------- |
| Your own            | Only you                                                                                 | Signed in. It opens first.            |
| Each team you’re in | Everyone in the team, each by their [role](https://docs.flozu.app/guides/teams.md#roles) | Signed in                             |
| This browser        | Whoever uses this browser                                                                | As a guest, or signed out             |
| This Mac            | Whoever uses this Mac                                                                    | In the Mac app, beside your account’s |

![The workspace switcher open at the top left: Ada Lovelace's own workspace, the Payments team ticked, and New team at the foot.](https://docs.flozu.app/_astro/workspaces-light.C97TXcHL_2jBho7.webp)

Choosing a workspace goes to its home and closes the maps you had open, since they belong to the other one. Flozu remembers the workspace you chose last on each device.

### Maps you made as a guest

Signed in on the web, Flozu shows your account’s maps only. The maps you made in this browser stay there, untouched, and show again if you sign out. Until then, home offers to move them into your own workspace, with their versions and proposals. Nothing moves until you ask. A map that can’t move, such as one whose copy is already in your account, stays in the browser, and home says which.

## Saving

A map in your account saves on its own, a moment after you stop editing, and at most every five seconds while you keep going. If you open the same map in two places and change both, nobody’s work is lost: the second save is kept as a proposal on the map. See [where maps live](https://docs.flozu.app/concepts/where-maps-live.md) for how saving works.

During the beta, an account has fair-use limits that normal use never meets:

| What                              | Up to  |
| --------------------------------- | ------ |
| One map                           | 2 MB   |
| Your own maps, with their history | 250 MB |
| A team’s maps, with their history | 1 GB   |
| Versions and proposals on one map | 250    |

A full workspace still saves the maps already in it. It only stops taking new ones. The [Usage](https://docs.flozu.app/guides/usage.md) page shows how much of each limit a workspace uses.

The beta has room for 5,000 accounts in all. Once it’s full, someone new is told so when they sign in, and everyone who already has an account carries on as before.

## Your account menu

Your picture, last at the top right after the theme switch, opens your account menu. Signed out, the same place has a button to sign in.

| Item                   | What it does                                                                                                                                             |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Usage**              | Shows how much of the beta’s limits the workspace on show uses. See [usage](https://docs.flozu.app/guides/usage.md).                                     |
| **Download my data**   | Saves one file with your own maps, their folders, versions and proposals, who you are, your teams and your first sign-in’s answers. Flozu can import it. |
| **Privacy and terms**  | What Flozu keeps about you and why, and the rules for using it.                                                                                          |
| **Sign out**           | Signs you out on this device and goes back to the maps on it, which are never touched.                                                                   |
| **Delete my account…** | Deletes your account and your own maps for good, after asking and offering the download first.                                                           |

**People**, last in the panel’s menu, opens the [People page](https://docs.flozu.app/guides/teams.md#the-people-page) for the workspace on show. With the panel folded, it’s at the foot of the rail.

### Deleting your account

Deleting takes your own maps, their folders and history, your sign-ins, your places in teams, the invites you sent and the [assistants you allowed](https://docs.flozu.app/guides/map-your-code.md). Maps and versions you made in a team stay with the team. A team always keeps an owner, so if you’re a team’s only owner, Flozu asks you to make someone else an owner first. Maps on your devices aren’t touched.

---

# Teams

> Make a team, invite people by email with a role each, share maps with them, and archive the team when you're done.

Say Ada runs the payments team. She makes a team called “Payments”, invites Sam as an editor and her manager as a viewer, and moves the checkout map in. Sam can change it; the manager can open, present and play scenarios on it, but can’t move a thing. When Sam wants to try something risky, it goes in a proposal for Ada to adopt.

A team is a workspace that several people share. Its maps belong to the team, and each person in it has a role that says what they can do. You need an [account](https://docs.flozu.app/guides/accounts.md) to make or join one, and you can be in any number of teams.

## Make a team

Open the workspace switcher at the top left and choose **New team…**. Give the team a name of up to 60 characters, which you can change later. You become its owner, Flozu switches to it, and its People page opens so you can invite people.

## Roles

Each person in a team has one role:

| Role            | Can                                                                             |
| --------------- | ------------------------------------------------------------------------------- |
| **Owner**       | Everything an admin can, and make other owners. A team always keeps one.        |
| **Admin**       | Invite people, change their roles, remove them and rename the team. Edits maps. |
| **Editor**      | Make, change and delete maps, folders, versions and proposals.                  |
| **Contributor** | Open maps and suggest changes as proposals, changing only their own.            |
| **Viewer**      | Open and present maps, and read their history.                                  |

## The People page

![The People page for the Payments team, one small panel: Invite by email with its role at the top, then Ada as owner, Sam as editor and Lee as viewer, and an invite to jo@example.com waiting as a contributor until 8 November.](https://docs.flozu.app/_astro/people-light.5j0VM7d9_Z1w0Te3.webp)

**People**, in the panel’s menu, opens the People page for the workspace on show. In a team, it lists everyone with their role, and the invites still waiting and when each runs out. The **ⓘ** beside **Members** says what each role can do. Owners and admins manage the team here:

- **Invite by email**, with the address they sign in with and the role beside it: admin, editor, contributor or viewer.
- Change someone’s role, or remove them, after asking.
- Withdraw an invite, or rename the team from the **⋯** beside **Members**.

An admin can’t change or remove an owner, and nobody changes their own role. Everyone else sees the same list, without the controls. Anyone can **Leave team**, after asking, except its last owner, and leaving takes you back to your own workspace.

### Invites

Flozu emails the person you invite: who it’s from, the team, their role, and to sign in with that address. The People page says “Flozu emailed them how to join”. If it didn’t email them, it says so, and asks you to let them know to sign in. They join the next time they sign in with the address you invited, once Google or GitHub has confirmed it’s theirs, so nobody else can take the invite up. An invite waits 30 days. Inviting the same address again replaces it, and someone already in the team keeps their role.

## Share a map with the team

Make a map in the team’s workspace, or move one in: choose **Move to…** from the map’s menu and pick the team in the workspace picker, then a folder. The map takes its versions and proposals with it, and the maps inside its parts too, so no part opens onto nothing. The dialog lists your own workspace and each team where you’re an owner, admin or editor, and says who’ll see the map.

A whole project or folder moves the same way, from its own **Move to…**. Everything in it goes along: its folders, its maps and all their history, and any map their parts open into that’s kept elsewhere in your workspace. If the team already has a project with the same name, yours comes in as “Payments 2”, and the dialog tells you before you move it.

![The Move Shop dialog with Payments picked as the workspace and Not in a project as the place. It says the project's folders and maps go with it, with their versions and proposals, that everyone in Payments can see it, and that there's already a Shop there, so it'll be called Shop 2.](https://docs.flozu.app/_astro/move-project-light.CflgJxrr_g5p6T.webp)

## Maps you can’t change

A contributor or viewer opens a team’s map to look at and present it. The mode menu has no **Edit**, and a note above the island says your role and what you can do, with the map’s proposals.

As a contributor, **Suggest a change** starts a proposal from the map as it is, named after you, and opens it to change freely. Your edits save into the proposal, and an editor can compare and [adopt it](https://docs.flozu.app/guides/versions-and-proposals.md). You can rename or delete your own proposals from their **Actions** menu. Someone else’s proposal opens compared with where it began, to read.

In a team, a map’s history says who made each version and proposal: “by you” or by their name.

## Archive a team

When a team is finished with, its owners can archive it with **Archive team…** in the **⋯** beside **Members** on the People page. An archived team keeps its maps, history and people. Everyone in it can still open, present, compare and export its maps, but nobody can change them, owners included, and nobody new can be invited.

An archived team leaves the workspace switcher and the **Move to…** dialog. It’s listed under **Archived teams** on the People page, where you can open it to look at, and where its owners **Restore team**. Nobody can delete a team, so its maps are never lost with it.

---

# Usage

> See how much of the beta's fair-use limits your account or team uses.

Flozu is free during the beta. Maps kept in an account have fair-use limits that keep it quick for everyone, and normal use never comes close. **Usage** shows how much of each limit the workspace you’re in uses. Maps kept on this device, in the browser or as files on your Mac, have no limits, so there’s nothing to count for them.

## Open it

When you’re signed in, the menu down the left has a **Usage** row with a small ring at its end. The ring fills as the workspace’s storage fills, and turns the warning colour once it’s 80% full, so you can see at a glance how much room is left. The same ring sits first in the bar of buttons at the top right of every screen. Select the ring, the row, or **Usage** in your account’s menu, to open the page.

![The Usage page for Ada Lovelace's own workspace, one small panel: a ring at 38 MB of 250 MB, split into maps and versions, with 212 MB left; then rows for the largest map, Checkout, at 410 KB of 2 MB, the most history on one map at 42 of 250 versions, 14 maps with no limit on how many, and how fast you can go.](https://docs.flozu.app/_astro/usage-light.CLldDf8b_27tPJw.webp)

## What it shows

The page shows the workspace you’re in. Switch workspace to see a team’s: everyone in a team shares its storage.

| Row                     | What it counts                                                                                                                                                                                                                           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Storage                 | Your maps and their versions and proposals, as they’re kept, out of 250 MB for your own workspace or 1 GB for a team. A full workspace still saves the maps already in it, but takes no new maps or versions until something is deleted. |
| Largest map             | The largest map. Each map can hold up to 2 MB; split a large one into [maps inside its parts](https://docs.flozu.app/guides/maps-inside-parts.md).                                                                                       |
| Most history on one map | The map with the most versions and proposals. Each map keeps up to 250; delete ones you don’t need to make room.                                                                                                                         |
| Invites                 | For people who run a team: how many people the team has invited in the last 24 hours, out of 50 a day.                                                                                                                                   |
| Maps                    | For everyone else: how many maps the workspace holds. There’s no limit on how many; only their size counts.                                                                                                                              |
| How fast you can go     | How many saves, assistant tool calls and other requests Flozu takes a minute from each person, so one busy tab or assistant can’t slow it down for everyone. Go faster and Flozu asks you to wait a minute; autosave never comes close.  |

A row that’s 80% full or more says **Nearly full**. Select a map’s name to open it, and an **ⓘ** for what a limit means.

If you need more room, select **Send feedback** under the panel and tell us what you’re mapping.

---

# The Mac app

> Flozu in its own window, with a native menu bar and every map saved as a file you can see in Finder.

The Mac app is Flozu in a native window, with no server and no sign-in. It runs the same app as the browser, in the Mac’s own web view (the one Safari uses), so it’s small and works the same. What it adds:

- **Maps are files.** Each map is a `.flozu.json` file in **Documents › Flozu**, and projects and folders are real folders there. See [files and folders](https://docs.flozu.app/mac/files-and-folders.md).
- **A menu bar,** with the shortcuts below.
- **A window that reopens where you left it,** at the size you left it.

## Get the Mac app

The Mac app is built from the same code as the web app. To build and run it yourself, you need what Flozu needs, plus Rust and Xcode’s command line tools:

```sh
xcode-select --install
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
pnpm install
pnpm desktop      # opens the app
```

The first run compiles the app, which takes a few minutes. Later runs take seconds. [docs/mac-app.md](https://github.com/flozu-app/flozu/blob/main/docs/mac-app.md) in the repo covers packaging, signing and releasing.

> **Note**
>
> The first time, macOS asks whether Flozu may use your Documents folder. Flozu needs it to keep your maps there. A build that isn’t signed yet opens with a warning: right-click the app, choose **Open**, then **Open** again.

## The menu bar

| Menu   | Item                   | Keys    |
| ------ | ---------------------- | ------- |
| File   | New map                | `⌘N`    |
| File   | All maps               | `⇧⌘M`   |
| File   | Import…                | `⌘O`    |
| File   | Export…                | `⌘E`    |
| File   | Export all maps…       | `⌥⌘E`   |
| File   | Close map              | `⌘W`    |
| File   | Show maps in Finder    | `⇧⌘F`   |
| File   | Close window           | `⇧⌘W`   |
| Edit   | Undo                   | `⌘Z`    |
| Edit   | Redo                   | `⇧⌘Z`   |
| View   | Show or hide sidebar   | `⌃⌘S`   |
| View   | Show or hide library   | `⌥⌘1`   |
| View   | Show or hide inspector | `⌥⌘2`   |
| View   | Fit to screen          | `⇧⌘1`   |
| View   | Play or pause          | `⌥⌘P`   |
| View   | Switch theme           | `⌥⌘T`   |
| Window | Show next open map     | `⌃Tab`  |
| Window | Show previous open map | `⌃⇧Tab` |

Undo and redo act on the text when you’re typing in a field, and on the map otherwise. Cut, copy, paste, select all, full screen, minimise, hide and quit are the Mac’s own.

---

# Files and folders on a Mac

> Where the Mac app keeps your maps, projects and versions, and how Finder and Flozu stay in step.

In the Mac app, your maps live as plain files in **Documents › Flozu**, so Finder shows the same tree as Flozu’s **Maps** panel.

- Documents/

  - Flozu/

    - Payments/ a project

      - Services/ a folder in it

        - Orders API.flozu.json

      - Checkout system.flozu.json

    - Web app with a database.flozu.json a map not in a project

    - .versions/ hidden: each map’s history

      - map_9w8ckczt9n/

        - ver_bz5w3wbvym.flozu-version.json

## How they stay in step

- **Each map is its own file,** named after the map. It saves as you edit, and is renamed when you rename the map.
- **Projects and folders are real folders.** Moving a map in Flozu moves its file on disk.
- **Files you drop into the folder** show up on home and the Maps page.
- **Deleting** a map or a folder in Flozu moves it to the Trash, so you can get it back.
- **Export** (`⌘E`) saves a copy to Downloads, and **Import** (`⌘O`) brings files in. See [import and export](https://docs.flozu.app/guides/import-export.md).
- **Show maps in Finder** (`⇧⌘F`) opens the folder.

## Versions on a Mac

A map’s [versions and proposals](https://docs.flozu.app/guides/versions-and-proposals.md) are files too, in a hidden `.versions` folder named after the map’s id rather than its name. Renaming a map leaves its history where it is, and deleting the map moves that folder to the Trash.

## Maps from before the rename

Flozu used to be called Fflo. If you have a **Documents › Fflo** folder, the app renames it to **Documents › Flozu** the first time it opens, so your maps and their history come with it. Older `.fflo.json` files still open, and each one takes the `.flozu.json` ending the next time it saves.

## Back up and sync

Because maps are ordinary files, anything that backs up or syncs your Documents folder, such as Time Machine or iCloud Drive, covers them too. To send maps to someone, [export them](https://docs.flozu.app/guides/import-export.md), or [share a link](https://docs.flozu.app/guides/presenting-and-sharing.md#share-a-link).

## Maps from an earlier version

Maps an earlier version of the Mac app kept in its own browser storage are copied into the folder once, the first time a newer version opens.

---

# The map

> What a Flozu map holds, from parts and lines to zones, notes, views, stories and scenarios, and the rules that keep it consistent.

Everything you draw is one **map**. One document holds it all, and the canvas, the scenarios, the stories and presenting all read from it.

| Thing      | What it is                                                                                                                                           |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Part       | A piece of the system, of one of 28 kinds, with an optional technology and a flag for parts someone else runs.                                       |
| Line       | A connection between two parts. It carries requests or messages, forward or both ways, with a label, a protocol and a rate.                          |
| Zone       | A frame around parts that belong together: a region, network, system, team or any other zone. Zones nest.                                            |
| Note       | Plain words on the canvas, for whoever reads the map later.                                                                                          |
| View       | One way of showing the map to one audience. See [views](https://docs.flozu.app/concepts/views.md).                                                   |
| Story      | A walk through the map for presenting it. See [stories](https://docs.flozu.app/guides/stories.md).                                                   |
| Scenario   | A saved “what if?”, such as Black Friday. See [scenarios](https://docs.flozu.app/guides/scenarios.md).                                               |
| Map inside | Another map a part opens into, such as a payment service’s own modules. See [maps inside parts](https://docs.flozu.app/guides/maps-inside-parts.md). |

## Numbers: rates and limits

A map holds the numbers behind its motion. **Traffic lives on lines,** as a rate: how much each carries each second at the busiest moment of a normal day. **Limits live on parts,** because a limit belongs to the part that enforces it: a capacity, a limit that turns traffic away, or a buffer that holds what’s waiting. See [traffic and limits](https://docs.flozu.app/guides/traffic-and-limits.md).

## What the map keeps true

Flozu checks a map after every change and every time it opens one, so a map can never be broken:

- Every id is unique across the whole map, so anything can be found by its id alone.
- A line joins two different parts that exist.
- A zone a part, note or other zone belongs to exists, and no zone is inside itself.
- Views, stories and scenarios only mention things that exist, and a map always has at least one view.
- Positions are on the canvas as a whole, even inside zones.

When you delete something, Flozu tidies up after it in the same step: deleting a part removes its lines and every mention of it in views and stories; deleting a zone keeps what was inside, in the zone around it.

## Looks never change meaning

A part’s kind says what it does: how traffic moves through it and which limits it can have. How it looks (its card, drawing, size and colours) is separate, so a part can look however suits the map without changing how it behaves.

## Saved as one file

A map saves as one `.flozu.json` file. See [file format](https://docs.flozu.app/reference/file-format.md).

---

# How traffic is worked out

> How Flozu turns a map's rates and limits into load, backed-up work, copies and suggestions, at one moment and over time, and how it estimates response times and cost.

Flozu works out everything from the numbers on the map. It never runs, calls or measures your systems. This page explains the model, so you know what a scenario’s answer means.

## A worked example

Here’s Black Friday on the **Checkout system** template, at ten past midnight, its busiest moment. Shoppers send 7.3 times their busiest on a normal day. Every part passes on 7.3 times what it usually does, so every line’s rate is multiplied by 7.3.

_Diagram: The checkout's order path on Black Friday. The web shop sends the Orders API 40 orders a second on a normal day and 292 at the busiest moment, so the API goes from 10% to 72% busy. The API sends 12 order events a second, 88 on Black Friday, to Order events, which holds up to 10,000, and on to the Email worker, which goes from 60% to 438% busy._

_Every number is multiplied by the same 7.3 at ten past midnight. The part with the least room on a normal day runs out first._

Then each part’s load is compared with what it can take. The Orders API gets 292 a second and can take 400: 72% busy, past the 70% it should stay under, so it’s **tight**. The Email worker gets 88 a second and can take 20: 438% busy, so it’s **over**. To bring it back under 70%, it needs 88 ÷ 0.7, about 126 a second. That’s the fix Flozu suggests.

The rest of this page is the rules behind each step.

## At one moment

Start from where traffic enters: a part no line flows into, such as people or an app. A scenario scales what those parts send, then traffic moves from each line’s source to its target.

- **A part sends on traffic in proportion to what reaches it,** as on a normal day. If twice as much arrives, it sends twice as much down each of its lines. Where several lines meet, each counts by its rate. A two-way line counts once, from source to target.
- **Past a part’s limit,** the excess is turned away, so the parts after it never see it.
- **Past a part’s capacity,** work backs up and its buffer fills. The traffic still flows on as if the part kept up, so one run sizes a whole path rather than only the first bottleneck.
- **A part that auto-scales** runs the fewest copies that keep each one under the spare room target. Its capacity is then its capacity per copy times the copies it runs.
- **Loops** settle after a few passes. If traffic keeps growing round one, the result says it didn’t settle.

Rates are compared as plain numbers, whatever their unit.

### How busy a part is

| Status      | Means                                                        |
| ----------- | ------------------------------------------------------------ |
| OK          | Within its spare room.                                       |
| Tight       | Past the spare room target, 70% busy by default.             |
| Over        | Past its capacity. Work backs up.                            |
| Down        | A failure took it down, so everything that reaches it fails. |
| Not checked | No capacity set, so there’s nothing to compare against.      |

On the canvas, a part’s [health strip](https://docs.flozu.app/guides/scenarios.md#on-the-canvas) splits these into finer zones, from underused to over.

A part is flagged when it’s tight, over or turning traffic away. Each flagged part comes with a fix: the capacity that brings it back under the spare room, how many times today’s that is, and, for a capacity per copy, how many copies to run. For a limit, it’s what to raise the limit to.

## Over time

A scenario over time plays its timeframe in steps, from every 5 seconds up to 5,000 steps, short enough to catch its quickest event. At each step it works out the moment as above, and carries two things from one step to the next:

- **Copies take time to start.** A part that auto-scales asks for the copies it needs at once, but a new copy only takes traffic once it’s started. A spike faster than that runs the part over until its copies are up.
- **Buffers fill and drain.** A part with a buffer keeps what it can’t process waiting, up to its buffer, and turns the rest away. Once the rush passes, it works through what’s waiting at full capacity.

### The day’s rhythm

A part where traffic starts is as busy as its share of the day. With a day’s rhythm, it runs from its quietest number of people to its busiest across the day, quietest at about 4am and busiest at about 8pm, shaped so the day averages out at its typical number. Without people set, its quietest is 15% of its busiest.

Every level in a scenario is a multiple of a normal day’s busiest moment.

## When something fails

A scenario can take a part, a line or a whole zone down for a while, or leave it degraded with only part of its capacity. Flozu then works out where its traffic goes, by rules on the map’s own lines and kinds:

- **A part that’s down takes nothing.** Everything that reaches it fails, and it sends nothing on. A degraded part keeps part of its capacity, or of its copies if it auto-scales.
- **A zone that’s down** takes every part in it down, and every part in the zones inside it.
- **A cut line carries nothing,** and what it would have carried fails where it starts.
- **Failures travel back on requests.** A caller fails as much of its own traffic as its requests fail, back to where traffic starts, so you can say “18% of shoppers’ requests fail”. A message’s sender doesn’t wait, so it only notices a send that fails straight away.
- **Traffic moves off what failed, where it can.** A line that stands by, such as a failover to a replica, takes it over. A load balancer or DNS spreads it over the lines beside it that are still up, which can run them over. A dead cache’s reads fall through to the database behind it. A queue holds work for a part that’s down, until its buffer is full, then works through it when the part is back. Anything with nowhere to go fails.
- **Coming back is cold.** A part that auto-scales comes back with no copies running, waits for its least copies to start, and only then scales out.

Here’s the Orders DB going down on the checkout. The Orders API waits on it, so its orders fail, and so on back to the shoppers. Orders are 40 of the 120 requests shoppers make each second, so a third of their traffic fails. Order events and the Email worker are reached by messages, so they’re out of it.

_Diagram: The Orders DB is down. The Orders API waits on it, so its orders fail; the web shop waits on the Orders API, so a third of what it sends fails; and so a third of the shoppers' requests fail. The Orders API also sends a message to Order events, which passes it to the Email worker. A message's sender doesn't wait, so trouble after Order events never reaches the shoppers._

_Requests carry a failure back to whoever is waiting. Messages don't wait, so trouble further down stays where it is._

Give the Orders DB a standby copy, and the standby line takes its traffic over the moment it goes down. Nobody notices.

_Diagram: The Orders API has a line to the Orders DB and a standby line to a copy of it. The Orders DB is down, so its line carries nothing, and the standby line, drawn thicker, carries the traffic to the copy._

_A standby carries nothing until the line beside it fails, then takes its traffic over._

Failures follow fixed rules, with nothing random about them, so a drill plays the same way every time.

### Comparing two maps

To compare a proposal with where it began, Flozu plays the same scenario on both, leaving out anything it reaches that only one of them has, and asks which went better. A saved scenario the proposal changed still plays as one copy on both, the proposal’s unless you pick the other, so the difference comes from the maps alone. A map that nobody notices anything on beats one where something goes wrong. When both run into trouble, it compares, in this order: how much fails where traffic starts and for how long, how long parts run short of room, how much they turn away, and how busy they get at their worst. Two maps within 1% of each other are as good as each other.

### Randomness that repeats

Random spikes and wobble come from a seed, so a scenario always plays the same way. That’s what lets you show a run again in a presentation or a share link. **Roll again** picks a new seed. [The odds](https://docs.flozu.app/guides/scenarios.md#the-odds) play many seeds and sum them up.

## Estimates

From the load at each moment, Flozu also estimates how long requests take, how much fails and what the map costs. [Response times and cost](https://docs.flozu.app/guides/response-times-and-cost.md) shows where they appear. The rules:

- **Each part takes a time of its own** to handle one thing: the time it’s given, or a [typical time for its kind](https://docs.flozu.app/guides/response-times-and-cost.md#typical-times).

- **It slows down as it gets busy,** by the usual queueing rule: its time divided by how much room it has left, time ÷ (1 − how busy). At 95% busy or more, it stops at 20 times. Work waiting in its buffer adds the time to work through it. For a part that takes 50 ms:

  | How busy    | Takes        | So     |
  | ----------- | ------------ | ------ |
  | 0%          | 1 × its time | 50 ms  |
  | 50%         | 2 ×          | 100 ms |
  | 75%         | 4 ×          | 200 ms |
  | 90%         | 10 ×         | 500 ms |
  | 95% or more | 20 ×         | 1 s    |

  That’s why the spare room matters: the busier a part gets, the more each extra bit of load slows it down. Going from 50% to 75% busy doubles its time; going from 75% to 95% multiplies it by five.

- **A request times out after 30 seconds.** A part over its capacity with no buffer falls further behind, so what it can’t get to times out, and the rest waits as long as it can.

- **A request’s time adds up along the requests it makes.** A part’s time includes the time of each part it calls, counted by how many calls it makes for each thing it handles, by the lines’ rates: three queries a request count three times, and a cache that sends a fifth of what it gets on to the database counts a fifth. A load balancer sends each request down one line only, so each line counts its share. Messages don’t wait for an answer, so they add no time.

- **What fails** is everything a failure breaks, what a limit or a full buffer turns away, and what times out, here or along the requests a part makes. A request’s time only counts the ones that get through.

- **Across a scenario,** each moment counts by the traffic that gets through then. 95% of requests are done within twice the typical time, or within the time at the slowest moments when one request in twenty or more comes then.

- **Cost** adds up what each part costs an hour: once for a part, or once for each copy it runs or is starting, for one that auto-scales. A month at that rate is 730 hours.

## What it can’t tell you

The model is deliberately simple. Its timeout is the same 30 seconds everywhere, it doesn’t know about retries, cold caches or slow queries, and a failure moves traffic only along the lines you’ve drawn. It’s best at finding which part runs out of room first and roughly how much more it needs, and at explaining that to someone. Treat its numbers, its estimates most of all, as a starting point for a conversation, not a guarantee.

---

# Commands and undo

> Every change to a map is a small command, which is why undo always works and why an assistant can build maps safely.

Every change to a map, whatever made it, is a small **command**: add a part, move a zone, change a line’s rate. Hand edits, undo and redo, a scenario’s **Apply** and an assistant such as Claude all go through the same commands, which are checked before they apply.

_Diagram: Three things change a map: you editing, a scenario's Apply, and an assistant such as Claude. Each sends a command. Flozu checks it against the map's rules. If it passes, the map changes and you get one step to undo. If not, it's refused with a message, and the map stays as it was._

_Hand edits, fixes and assistants all go through the same door, so undo always works and nothing can break a map._

Dragging the Orders API across the canvas, for example, is one command: move this part to here. Applying a scenario’s fix is one command: set this part’s capacity to 126. An assistant drawing a whole map is one batch of commands. Each is checked the same way, and each is one step to undo.

## Why it matters to you

- **Undo always works.** Each gesture is one command, so one `⌘Z` puts it back. A drag is one command however far it goes. Putting a part on a line, which may move other parts to make room, is one command too.
- **A map can’t end up broken.** A command that would break one of [the map’s rules](https://docs.flozu.app/concepts/the-map.md#what-the-map-keeps-true) is refused, with a message a person can read, and the map stays as it was.
- **Changes clean up after themselves.** Removing a part removes its lines and every mention of it in views, stories and scenarios, in the same step. A failure in a scenario that has nothing left to break goes too.

Flozu keeps the last 200 steps of history for each open map, for as long as it stays open.

## The commands

| Things                  | Commands                  |
| ----------------------- | ------------------------- |
| The map                 | update, replace           |
| Parts                   | add, update, move, remove |
| Lines                   | add, update, remove       |
| Zones                   | add, update, move, remove |
| Notes                   | add, update, move, remove |
| Views                   | add, update, remove       |
| Stories and their steps | add, update, move, remove |
| Scenarios               | add, update, remove       |

A **batch** applies several commands as one step, all or nothing.

## How an assistant uses them

The commands are plain JSON, described by a JSON Schema that can be handed to an AI model as its tools. When you [connect an assistant such as Claude](https://docs.flozu.app/guides/map-your-code.md) to your account, it changes a map by sending a batch of these commands. They go through the same checks as a hand edit, so an assistant can’t break a map either. Its changes arrive as a [proposal](https://docs.flozu.app/guides/versions-and-proposals.md) for you to compare and adopt, unless you ask it to change the map itself, and then Flozu saves a version first so you can go back.

---

# Where maps live

> Where your maps, folders and versions are kept, in your browser, on your Mac or in your account, and what that means for privacy.

Flozu keeps your maps in one of three places. As a guest in a browser, or in the Mac app, they stay on your computer unless you export them or share a link. Signed in, they’re kept in your account, so they open wherever you sign in.

| Where          | Maps                                     | Projects and folders    | Versions                             |
| -------------- | ---------------------------------------- | ----------------------- | ------------------------------------ |
| In a browser   | The browser’s own storage (IndexedDB)    | Records beside the maps | A separate database of their own     |
| In the Mac app | `.flozu.json` files in Documents › Flozu | Real folders there      | Files in a hidden `.versions` folder |
| In an account  | Flozu’s database, one record per map     | Records beside the maps | Records beside each map              |

## In a browser

Maps are kept in the browser you made them in, for the address Flozu runs at. Another browser, another computer, or a private window doesn’t see them.

> **Caution**
>
> Clearing a browser’s site data deletes the maps in it. Export the maps you care about to keep a copy as a file.

## Moving and sharing maps

- **To move maps** to another browser or computer, [export them](https://docs.flozu.app/guides/import-export.md) and import them there. A bundle takes a whole project, or every map, with its folders and history.
- **To show it to someone,** [share a link](https://docs.flozu.app/guides/presenting-and-sharing.md#share-a-link). The map is packed inside the link, after the `#`, which browsers never send to the server.
- **To keep them safe,** export every map from the Maps page, or use the Mac app and back up your Documents folder.

## What Flozu checks when it reads a map

Every map is checked, and updated if it was made by an older version, as it’s read: from storage, from a file, from a link or from a version. A map that can’t be read is left where it is rather than deleted, and a map from a newer version of Flozu is refused with a message to update.

Every save is stamped with when it happened, which also tells copies of a map apart. Each save from the editor names the copy it started from, so storage refuses to save over a copy that changed since you opened it: a save from another tab, a file edited in another app, or, with an account, another device or another person in your team. Nobody’s work is lost to someone else’s save. Your changes are kept as a proposal on the map, and the editor shows the other copy.

A save that fails, such as with no connection, still counts as waiting. Flozu tries it again after two seconds, then four, and so on up to every thirty, and straight away when the browser is back online. A save made as you close the tab is sent so that it still arrives after the tab has gone, and if a save is still on its way or failing, the browser asks before you leave.

## In an account

Signed in on the web, your maps are kept in your [account](https://docs.flozu.app/guides/accounts.md), on Flozu’s servers, in the same way the browser and the Mac app keep them. Each map is kept whole, exactly as a file holds it, with a short summary beside it (its name, the kinds of part and technologies in it, and its words) so maps can be listed and searched without opening them. Projects and folders work just as they do in the browser, and a map’s versions and proposals travel with it, so its history is there wherever you open it.

Because each save goes over the network, a map in an account saves two seconds after your last edit, and at most every five seconds while you keep editing, rather than after every change. During the free beta, an account has fair-use limits that normal use never meets: a map can hold up to 2 MB, your own maps and their versions up to 250 MB, a team’s up to 1 GB, and each map up to 250 versions and proposals. A full workspace still saves the maps already in it; it only stops taking new ones. The beta also has room for 5,000 accounts in all: once it’s full, someone new is told so when they sign in, and everyone with an account carries on as before. The [Usage](https://docs.flozu.app/guides/usage.md) page shows how much of each limit a workspace uses.

Each map belongs to one workspace: your own, which only you see, or a [team’s](https://docs.flozu.app/guides/teams.md), which everyone in it sees by their role. Signed in, the web shows your account’s maps only, and the maps you made in the browser stay there until you move them in. The Mac app lists its own maps beside the account’s. An assistant such as Claude can draw maps straight into your account once you sign in and allow it, while your code stays on your computer.

Your account menu downloads everything Flozu keeps about you, as a bundle you can import, and deletes your account and your own maps for good; maps you made in a team stay with the team. The privacy notice in the app says what an account keeps and why. As a guest, or in the Mac app, nothing you draw leaves your computer unless you send it.

---

# Views

> One map, shown to different audiences, with things hidden and plain-language wording, without ever drifting apart.

An engineer reading the checkout map wants “Orders DB · PostgreSQL” and every queue. Your client wants “Where orders are kept” and none of the plumbing. Two diagrams would drift apart within a month. Two views of one map can’t.

A view decides what one audience sees. An architect’s view and a plain-language view are two ways of showing the same map, so they never drift apart: edit the map and every view changes with it.

A view holds:

- **What’s hidden:** parts, lines, zones and notes it doesn’t show. A hidden part’s lines go with it, and a hidden zone’s contents still show.
- **Wording:** plain-language names and descriptions that replace the map’s own, such as “Where orders are kept” in place of “Orders DB”.
- **Its audience:** technical or non-technical.

A new map starts with one technical view called “Everything”. The showcase examples on the maps home each have a second view in plain words: present one and switch between them to see the difference.

## Where views show

Presenting and sharing go through a view. With more than one view, a picker on the island, beside the mode menu, switches between them.

A view only hides things. Presenting, what it hides is still there, just not drawn, so [scenarios](https://docs.flozu.app/guides/scenarios.md) and [failure drills](https://docs.flozu.app/guides/failure-drills.md) play on the whole map: a drill that takes down a hidden region still takes down the parts inside it, and the numbers are the map’s own. Nothing on screen names what’s hidden: where a scenario’s results mention it, it’s called “Hidden part” or “Hidden zone”. A story step about something hidden frames what’s still drawn of it, and a step about nothing still drawn shows the whole map and says so.

A [share link](https://docs.flozu.app/guides/presenting-and-sharing.md#share-a-link) holds only what its view shows, so it never carries what its audience wasn’t meant to see. A drill on a zone the view hides is aimed at the parts that were in it instead, so it still takes them down. A hidden part can’t travel with the link, so its scenarios play without it there.

## Coming later

A panel to make and edit views in the editor, and collapsed zones drawn as one box, are on the way. Maps made by other tools or by an assistant can already hold several views.

---

# Keyboard shortcuts

> Every key in Flozu, for building maps, moving around, scenarios, stories and the Mac app.

On Windows and Linux, use `Ctrl` wherever this page says `⌘`. Shortcuts never fire while you’re typing in a field.

## Building a map

| Keys                    | What it does                                                                |
| ----------------------- | --------------------------------------------------------------------------- |
| A part’s letter         | Add that part under the pointer, or in the middle of the screen. See below. |
| `Z`                     | Add a zone, or draw one around what’s selected.                             |
| `N`                     | Write a note where the pointer is.                                          |
| `/`                     | Search the parts library.                                                   |
| `⌘Z`                    | Undo.                                                                       |
| `⇧⌘Z` or `Ctrl+Y`       | Redo.                                                                       |
| `Delete` or `Backspace` | Delete what’s selected.                                                     |
| `Esc`                   | Let go of the selection, or close a menu or search.                         |
| Arrow keys              | Move what’s selected a grid step at a time.                                 |
| `⌘`-click               | Add to the selection, or take something out of it.                          |
| `Shift`-drag            | Select everything in an area.                                               |
| `⌘Enter`                | Finish writing a note.                                                      |

## Maps inside parts

| Keys | What it does                           |
| ---- | -------------------------------------- |
| `⌘↓` | Open the map inside the selected part. |
| `⌘↑` | Go back out to the map above.          |

See [maps inside parts](https://docs.flozu.app/guides/maps-inside-parts.md).

## Adding parts

Press a part’s key with the pointer over the canvas.

| Key | Adds           |
| --- | -------------- |
| `P` | Person         |
| `C` | Client app     |
| `U` | DNS            |
| `E` | CDN            |
| `V` | Firewall       |
| `G` | Gateway        |
| `I` | Sign-in        |
| `L` | Load balancer  |
| `R` | Rate limiter   |
| `S` | Service        |
| `W` | Worker         |
| `F` | Function       |
| `J` | Scheduler      |
| `A` | AI model       |
| `Q` | Queue          |
| `T` | Topic          |
| `D` | Database       |
| `K` | Cache          |
| `H` | Search         |
| `B` | Storage        |
| `O` | Data warehouse |
| `Y` | Endpoint       |
| `M` | Module         |
| `X` | Custom part    |

## Menus and lists

| Keys                             | What it does                                     |
| -------------------------------- | ------------------------------------------------ |
| `↑` `↓`                          | Move through a menu.                             |
| Typing                           | Jump to an option by its name.                   |
| `Enter`                          | Pick the option.                                 |
| `←` `→`                          | Move between the inspector’s tabs.               |
| `Esc` in the panel down the left | Go back up one level, in a map as anywhere else. |

## The timeline

With the timeline focused:

| Keys                  | What it does                             |
| --------------------- | ---------------------------------------- |
| `←` `→`               | Step back or forward a little.           |
| `Shift` + `←` `→`     | Step back or forward further.            |
| `Page Up` `Page Down` | Step forward or back a tenth of the way. |
| `Home` `End`          | Go to the start or the end.              |
| `Space`               | Play or pause the scenario.              |

## Failure drills

While a scenario runs, with a part, a zone or a line focused:

| Keys                            | What it does                                              |
| ------------------------------- | --------------------------------------------------------- |
| The menu key or `Shift` + `F10` | Open its menu, to take it down or cut it at the playhead. |

See [failure drills](https://docs.flozu.app/guides/failure-drills.md).

## Playing a story

| Keys               | What it does     |
| ------------------ | ---------------- |
| `→` or `Page Down` | Next step.       |
| `←` or `Page Up`   | Previous step.   |
| `Esc`              | Leave the story. |

Presentation clickers send `Page Up` and `Page Down`, so they work too.

## The Mac app

| Menu   | Item                   | Keys    |
| ------ | ---------------------- | ------- |
| File   | New map                | `⌘N`    |
| File   | All maps               | `⇧⌘M`   |
| File   | Import…                | `⌘O`    |
| File   | Export…                | `⌘E`    |
| File   | Export all maps…       | `⌥⌘E`   |
| File   | Close map              | `⌘W`    |
| File   | Show maps in Finder    | `⇧⌘F`   |
| File   | Close window           | `⇧⌘W`   |
| Edit   | Undo                   | `⌘Z`    |
| Edit   | Redo                   | `⇧⌘Z`   |
| View   | Show or hide sidebar   | `⌃⌘S`   |
| View   | Show or hide library   | `⌥⌘1`   |
| View   | Show or hide inspector | `⌥⌘2`   |
| View   | Fit to screen          | `⇧⌘1`   |
| View   | Play or pause          | `⌥⌘P`   |
| View   | Switch theme           | `⌥⌘T`   |
| Window | Show next open map     | `⌃Tab`  |
| Window | Show previous open map | `⌃⇧Tab` |

---

# Part kinds

> Every kind of part, the key that adds it, what it's for and what usually comes after it.

Flozu has 28 kinds of part. A kind says what a part does: how traffic moves through it and which [limits](https://docs.flozu.app/guides/traffic-and-limits.md#limits-on-parts) it can have. It doesn’t decide how the part looks, since any part can show [any drawing](https://docs.flozu.app/guides/looks.md#drawings).

A few kinds behave differently from the rest:

- **Rate limiters, firewalls, gateways, sign-in and AI models** can have a limit, and turn away what’s past it.
- **Queues and topics** hold what’s waiting, and lines into and out of them start as messages.
- **Schedulers** start traffic by the clock, so their lines start as messages and a scenario’s busier day doesn’t scale them.
- **People, client apps and schedulers** set the pace with the lines they send, so they have no limits of their own.

“Usually followed by” is what Flozu suggests when you drop a line from that part on empty canvas.

## People and apps

| Kind       | Key | What it is                                                                    | Usually followed by                                |
| ---------- | --- | ----------------------------------------------------------------------------- | -------------------------------------------------- |
| Person     | `P` | Someone who uses the system, such as a customer, an admin or a support agent. | Client app, CDN, Gateway                           |
| Client app | `C` | An app people use: a website, a mobile app, a desktop app or a device.        | Gateway, CDN, DNS, Sign-in, Load balancer, Service |

## The way in

| Kind          | Key | What it is                                                                     | Usually followed by                                     |
| ------------- | --- | ------------------------------------------------------------------------------ | ------------------------------------------------------- |
| DNS           | `U` | Turns names like shop.example.com into the addresses traffic is sent to.       | CDN, Firewall, Load balancer, Gateway                   |
| CDN           | `E` | Serves content from close to people and absorbs traffic before it reaches you. | Gateway, Firewall, Load balancer, Storage, Service      |
| Firewall      | `V` | Lets allowed traffic through and blocks the rest, such as attacks and bots.    | Gateway, Load balancer, Service                         |
| Gateway       | `G` | The front door for requests. It checks who's calling and routes each request.  | Service, Sign-in, Rate limiter, Load balancer, Function |
| Sign-in       | `I` | Checks who people are and hands out the tokens other parts trust.              | Database, Cache, Service                                |
| Load balancer | `L` | Shares traffic between copies of a service so none of them gets swamped.       | Service, Function, Gateway                              |
| Rate limiter  | `R` | Lets a set amount through each second and turns the rest away.                 | Service, Gateway, Function                              |

## Compute

| Kind      | Key | What it is                                                                     | Usually followed by                                  |
| --------- | --- | ------------------------------------------------------------------------------ | ---------------------------------------------------- |
| Service   | `S` | A running program that answers requests, such as an API or a web server.       | Database, Cache, Queue, Topic, Search, Service       |
| Worker    | `W` | Works through jobs in the background, usually taking them from a queue.        | Database, Storage, Service, AI model, Data warehouse |
| Function  | `F` | Code that runs when it's called and scales up and down by itself.              | Database, Storage, Queue, AI model                   |
| Scheduler | `J` | Starts jobs on a timetable, such as a nightly export or a reminder every hour. | Worker, Queue, Function, Service                     |
| AI model  | `A` | A language or machine learning model that the system calls.                    | Service, Database, Storage                           |

## Messaging

| Kind  | Key | What it is                                                                          | Usually followed by                              |
| ----- | --- | ----------------------------------------------------------------------------------- | ------------------------------------------------ |
| Queue | `Q` | Holds work in line until something is free to take it. Each item goes to one taker. | Worker, Function, Service                        |
| Topic | `T` | Broadcasts each event to every part that subscribes.                                | Worker, Function, Service, Queue, Data warehouse |

## Data

| Kind           | Key | What it is                                                                     | Usually followed by                              |
| -------------- | --- | ------------------------------------------------------------------------------ | ------------------------------------------------ |
| Database       | `D` | Keeps the system's records, such as orders, customers and stock.               | Database, Topic, Search, Data warehouse, Service |
| Cache          | `K` | Keeps popular data in memory so it can be read quickly.                        | Database, Service                                |
| Search         | `H` | An index that finds records by their words, such as products in a shop.        | Database, Service                                |
| Storage        | `B` | Holds files such as images, exports and backups.                               | Function, CDN, Worker, Data warehouse            |
| Data warehouse | `O` | Gathers data from across the system so people can report on it and analyse it. | Client app, AI model, Storage                    |

## Inside a service

| Kind      | Key  | What it is                                                                                               | Usually followed by                          |
| --------- | ---- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| Endpoint  | `Y`  | A way into a service that others call, such as an HTTP route, an RPC method or an event handler.         | Module, Service, Code file, Function         |
| Module    | `M`  | A part of a service's code with one job, such as a package or a folder.                                  | Module, Code file, Table, Library, Interface |
| Code file | None | One source file, named by its path.                                                                      | Code file, Interface, Library, Table         |
| Interface | None | A contract code depends on rather than a thing that runs, such as a TypeScript interface or an API spec. | Code file, Module                            |
| Library   | None | A package the code is built on, such as stripe-node or a Go module.                                      | Library                                      |
| Table     | None | A table, collection or index inside a store, where a service keeps its records.                          | Table                                        |

## Anything else

| Kind        | Key | What it is                                                         | Usually followed by      |
| ----------- | --- | ------------------------------------------------------------------ | ------------------------ |
| Custom part | `X` | Anything that doesn't fit another kind. It behaves like a service. | Service, Database, Queue |

---

# Presets

> Every ready-made part on the library's Presets shelf, with its kind and what it is.

The library’s **Presets** shelf has 117 parts ready to go. A preset fills in a part’s kind, name, drawing, card, technology and starting limits; everything it fills in can be changed after. See [start from a preset](https://docs.flozu.app/guides/looks.md#start-from-a-preset).

## People and apps

| Preset              | Kind                           | What it is                                   |
| ------------------- | ------------------------------ | -------------------------------------------- |
| Customers           | Person                         | The people who use what you make.            |
| Admins              | Person                         | The people who run things behind the scenes. |
| Support team        | Person                         | The people who help customers.               |
| On call             | Person                         | Whoever answers when something breaks.       |
| Web app React       | Client app                     | A website people use in their browser.       |
| iPhone app iOS      | Client app                     | An app on people's iPhones.                  |
| Android app Android | Client app                     | An app on people's Android phones.           |
| Desktop app         | Client app                     | An app people install on their computer.     |
| Tills               | Client app                     | The tills in a shop, taking payments.        |
| Sensors             | Client app                     | Devices that send readings on their own.     |
| Partner integration | Client app run by someone else | Another company's system calling your API.   |

## The way in

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

## Compute

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

## AI

| Preset           | Kind                         | What it is                                         |
| ---------------- | ---------------------------- | -------------------------------------------------- |
| Claude           | AI model run by someone else | A language model that answers, writes and reasons. |
| AI agent         | AI model                     | A model that uses tools to get a task done.        |
| Embeddings model | AI model                     | Turns text into numbers that capture its meaning.  |
| Knowledge base   | Search                       | Finds the passages a model needs to answer.        |
| Vector database  | Search                       | Finds the closest matches by meaning.              |
| Recommendations  | AI model                     | Picks what to show each person next.               |
| Moderation       | AI model                     | Checks posts and holds back the harmful ones.      |
| Fraud check      | AI model                     | Scores each payment and holds the risky ones.      |
| Speech to text   | AI model                     | Turns voice into text as people speak.             |

## Messaging

| Preset                | Kind   | What it is                                                           |
| --------------------- | ------ | -------------------------------------------------------------------- |
| SQS queue SQS         | Queue  | Holds jobs until a worker is free.                                   |
| RabbitMQ              | Queue  | Shares messages out between its consumers.                           |
| Priority queue        | Queue  | Lets urgent work go first.                                           |
| Dead-letter queue     | Queue  | Keeps messages that keep failing, to look at later.                  |
| Kafka topic Kafka     | Topic  | A log of events, split into partitions.                              |
| Event bus EventBridge | Topic  | Carries events from the parts that publish to the parts that listen. |
| Pub/Sub topic Pub/Sub | Topic  | Copies each event to every subscriber.                               |
| Outbox                | Worker | Sends each saved change on as an event, so none is lost.             |

## Data

| Preset                      | Kind                       | What it is                                          |
| --------------------------- | -------------------------- | --------------------------------------------------- |
| PostgreSQL                  | Database                   | A relational database for your records.             |
| Read replica PostgreSQL     | Database                   | A copy of the database that takes the reads.        |
| MySQL                       | Database                   | A relational database of tables and rows.           |
| MongoDB                     | Database                   | A database of documents.                            |
| DynamoDB                    | Database                   | A key-value table that scales by itself.            |
| Graph database Neo4j        | Database                   | Keeps records and how they relate.                  |
| Time series database        | Database                   | Keeps readings over time.                           |
| Ledger PostgreSQL           | Database                   | Records every movement of money, always in balance. |
| Redis cache Redis           | Cache                      | Keeps popular data in memory.                       |
| Session store Redis         | Cache                      | Remembers who's signed in.                          |
| Memcached                   | Cache                      | A memory cache that drops the oldest keys first.    |
| Elasticsearch               | Search                     | Finds records by their words.                       |
| Algolia                     | Search run by someone else | Search as you type, run for you.                    |
| S3 bucket S3                | Storage                    | Keeps files of any size.                            |
| Media storage Cloud Storage | Storage                    | Keeps the photos people upload.                     |
| Video library               | Storage                    | Keeps videos ready to stream.                       |
| Backups Backblaze           | Storage                    | A copy of everything, taken every night.            |
| Snowflake                   | Data warehouse             | Gathers data from everywhere for reports.           |
| BigQuery                    | Data warehouse             | A warehouse you ask questions of in SQL.            |
| ClickHouse                  | Data warehouse             | Fast analytics over lots of events.                 |
| ETL job                     | Worker                     | Copies data from your systems into the warehouse.   |

## Outside services

| Preset                      | Kind                        | What it is                                            |
| --------------------------- | --------------------------- | ----------------------------------------------------- |
| Stripe payments Stripe      | Service run by someone else | Takes card payments for you.                          |
| PayPal                      | Service run by someone else | Lets people pay with PayPal.                          |
| Shopify                     | Service run by someone else | A shop run for you, with its cart and checkout.       |
| Email sending SendGrid      | Service run by someone else | Sends your emails and tracks them.                    |
| Text messages Twilio        | Service run by someone else | Sends text messages to people's phones.               |
| Push notifications Firebase | Service run by someone else | Sends notifications to people's phones.               |
| Delivery tracking           | Service run by someone else | A courier's service for sending and tracking parcels. |

## Operations

| Preset                | Kind                            | What it is                                         |
| --------------------- | ------------------------------- | -------------------------------------------------- |
| Monitoring Datadog    | Custom part run by someone else | Watches your systems' requests, errors and speed.  |
| Error tracking Sentry | Custom part run by someone else | Collects the errors your apps hit.                 |
| Logs                  | Custom part                     | Gathers what every part writes down.               |
| Dashboards Grafana    | Custom part                     | Charts of how everything is doing.                 |
| Feature flags         | Service                         | Turns features on for some people before everyone. |
| Build pipeline        | Custom part                     | Builds, tests and ships each change.               |
| Secrets vault         | Custom part                     | Keeps passwords and keys out of the code.          |

## Inside a service

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

---

# Drawings

> Every drawing in the library, by category, with what it shows and the kinds it suits.

The library holds 237 drawings in 17 categories. Any part can show any drawing; “suits” is only which parts Flozu suggests it for. The id under each name is what a map file saves in a part’s `visual`. See [drawings](https://docs.flozu.app/guides/looks.md#drawings) in Make it look right.

## People

| Drawing                             | What it shows                                          | Suits                  |
| ----------------------------------- | ------------------------------------------------------ | ---------------------- |
| People `crowd`                      | A few people, sending requests.                        | Person                 |
| Journey `journey`                   | One person moving from browsing to paying.             | Person                 |
| Online now `online`                 | How many people are here, with a live count.           | Person                 |
| Team `team`                         | A small team, each with a status dot.                  | Person                 |
| Support agent `support`             | Someone with a headset, answering a chat.              | Person                 |
| Admin `admin`                       | Someone with a key, changing settings.                 | Person                 |
| Around the world `around-the-world` | People across time zones, with the awake ones lit.     | Person, CDN            |
| Persona `persona`                   | A profile card with a name, a role and what they need. | Person                 |
| Audiences `audiences`               | People split into groups: new, returning and paying.   | Person, Data warehouse |

## Apps and devices

| Drawing                       | What it shows                                         | Suits                            |
| ----------------------------- | ----------------------------------------------------- | -------------------------------- |
| Browser `browser`             | A web page with a button being pressed.               | Client app                       |
| Phone `phone`                 | A mobile app, with a list and a tap.                  | Client app                       |
| Devices `devices`             | A laptop, a tablet and a phone, all sending requests. | Client app                       |
| Desktop app `desktop`         | A desktop window with a sidebar, syncing.             | Client app                       |
| Watch `watch`                 | A smartwatch with a ring filling up.                  | Client app                       |
| Sensor `sensor`               | A small device sending a reading on every beat.       | Client app, Worker               |
| TV app `tv`                   | A screen playing a stream, with its progress bar.     | Client app                       |
| Terminal `terminal`           | A command typed, and its answer printed.              | Client app, Service, Custom part |
| Point of sale `point-of-sale` | A till, with a card tapped against it.                | Client app                       |
| API client `api-client`       | Code calling an API, and the answer coming back.      | Client app, Service              |
| Vehicle `vehicle`             | A vehicle on a route, sending where it is.            | Client app                       |

## Email and alerts

| Drawing                     | What it shows                                     | Suits                |
| --------------------------- | ------------------------------------------------- | -------------------- |
| Email `email`               | Envelopes leaving an outbox, one at a time.       | Service, Worker      |
| Inbox `inbox`               | An inbox, with new mail arriving at the top.      | Service              |
| Text message `text-message` | A phone with text messages arriving.              | Service              |
| Push notification `push`    | A notification sliding onto a lock screen.        | Service              |
| Chat room `chat-room`       | Several people talking in one room.               | Service, Topic       |
| Webhook `webhook`           | A POST sent to a web address, and the reply code. | Service, Function    |
| Video call `video-call`     | A grid of people on a call, with the speaker lit. | Service              |
| Alerts `alerts`             | A bell ringing, with a count of what's new.       | Service, Custom part |

## Network

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

## Traffic and limits

| Drawing                           | What it shows                                                      | Suits                           |
| --------------------------------- | ------------------------------------------------------------------ | ------------------------------- |
| Gauge `gauge`                     | A needle that edges into the red past the limit.                   | Rate limiter                    |
| Token bucket `token-bucket`       | A bucket of tokens: each request takes one.                        | Rate limiter                    |
| Per second `window`               | Each second's traffic against the limit, with the excess cut.      | Rate limiter                    |
| Leaky bucket `leaky-bucket`       | Requests pour in and drip out at a steady pace.                    | Rate limiter                    |
| Sliding window `sliding-window`   | A window sliding over the last minute of requests.                 | Rate limiter                    |
| Throttle `throttle`               | Bunched-up requests spaced out to a steady pace.                   | Rate limiter, Gateway           |
| Quota `quota`                     | A daily allowance being used up, and what's left of it.            | Rate limiter, Gateway, AI model |
| Bandwidth `bandwidth`             | A pipe filling with traffic towards its limit.                     | CDN, Gateway, Rate limiter      |
| Circuit breaker `circuit-breaker` | A switch that opens when calls fail, and closes once they recover. | Gateway, Service                |
| Retries `retries`                 | A call failing, waiting longer each time, then going through.      | Service, Gateway                |

## Security and sign-in

| Drawing                     | What it shows                                                  | Suits                           |
| --------------------------- | -------------------------------------------------------------- | ------------------------------- |
| Rules `rules`               | A wall of rules: allowed traffic passes, the rest bounces off. | Firewall                        |
| Shield `shield`             | A shield with what it let through and what it blocked.         | Firewall                        |
| Log `log`                   | Allowed and blocked requests as they happen.                   | Firewall                        |
| Password `password`         | A password being typed, then a tick.                           | Sign-in                         |
| Token `token`               | A signed token, issued in three parts.                         | Sign-in                         |
| One-time code `code`        | A six-digit code being filled in.                              | Sign-in                         |
| Lock `lock`                 | A padlock closing over what it keeps safe.                     | Sign-in, Firewall, Storage      |
| Secrets `secrets`           | Keys kept in a vault, handed out one at a time.                | Sign-in, Custom part            |
| Fingerprint `fingerprint`   | A fingerprint being scanned, line by line.                     | Sign-in                         |
| Passkey `passkey`           | A device confirming who it is with a touch, and no password.   | Sign-in                         |
| Two-step sign-in `two-step` | A password, then a code from a phone.                          | Sign-in                         |
| Permissions `permissions`   | Roles, and what each one may do.                               | Sign-in, Gateway                |
| Sessions `sessions`         | Signed-in sessions, each running out in time.                  | Sign-in, Cache                  |
| Certificate `certificate`   | A certificate, who issued it and the days until it expires.    | DNS, Gateway, CDN               |
| Attack `attack`             | A flood of traffic, mostly stopped at the edge.                | Firewall, CDN                   |
| Bot check `bot-check`       | Visitors checked one by one, with the bots turned away.        | Firewall, Sign-in               |
| Audit log `audit-log`       | Who did what and when, written down for later.                 | Firewall, Database, Custom part |
| Encryption `encryption`     | Plain text going in, and scrambled text coming out.            | Storage, Service                |

## Compute

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

## Time

| Drawing                     | What it shows                                         | Suits                          |
| --------------------------- | ----------------------------------------------------- | ------------------------------ |
| Clock `clock`               | A clock, and the job it starts every hour.            | Scheduler                      |
| Timeline `timeline`         | A day's runs on a timeline, with now moving along it. | Scheduler                      |
| Week `week`                 | A week of runs on a calendar.                         | Scheduler                      |
| Countdown `countdown`       | A timer counting down to the next run.                | Scheduler                      |
| Cron `cron`                 | A cron line, and when it next runs.                   | Scheduler                      |
| Month `month`               | A month, with runs on chosen days.                    | Scheduler                      |
| Hourglass `hourglass`       | Sand running through, for something that takes time.  | Scheduler, Worker, Custom part |
| Delayed jobs `delayed-jobs` | Jobs parked until their time comes.                   | Scheduler, Queue               |

## AI

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

## Messaging

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

## Data

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

## Files and media

| Drawing                       | What it shows                                      | Suits                         |
| ----------------------------- | -------------------------------------------------- | ----------------------------- |
| Bucket `bucket`               | Files dropping into a bucket.                      | Storage                       |
| Files `files`                 | Images, documents and archives, kept side by side. | Storage                       |
| Space used `usage`            | How much space each kind of file takes.            | Storage                       |
| Images `images`               | A grid of photos, with a new one uploading.        | Storage                       |
| Video `video`                 | A video playing, with its buffer filling ahead.    | Storage, CDN, Client app      |
| Upload `upload`               | A file uploading in chunks.                        | Storage, Function             |
| Cold storage `cold-storage`   | Files moving from hot to cold as they age.         | Storage                       |
| Folders `folders`             | Folders, and the files inside them.                | Storage                       |
| File versions `file-versions` | One file, and its earlier versions behind it.      | Storage                       |
| Audio `audio`                 | A sound wave playing.                              | Storage, AI model, Client app |

## Analytics

| Drawing                 | What it shows                                       | Suits                       |
| ----------------------- | --------------------------------------------------- | --------------------------- |
| Bars `bars`             | Data flowing in, and a chart growing from it.       | Data warehouse              |
| Heatmap `heatmap`       | A grid of figures, darker where there's more.       | Data warehouse              |
| Trend `trend`           | A figure over time, with this week's point.         | Data warehouse              |
| Funnel `funnel`         | Steps from visiting to buying, each one narrower.   | Data warehouse              |
| Dashboard `dashboard`   | A dashboard of tiles: a figure, a chart and a list. | Data warehouse, Custom part |
| Breakdown `donut`       | A ring split into shares.                           | Data warehouse, Custom part |
| Extract and load `etl`  | Data copied from several sources into tables.       | Data warehouse, Worker      |
| Cohorts `cohorts`       | Each week's sign-ups, and how many came back.       | Data warehouse              |
| Report `report`         | A report with a headline figure and a chart.        | Data warehouse              |
| Places `places`         | Activity by place, as dots on a map.                | Data warehouse, CDN         |
| Top list `top-list`     | The top items, ranked, each with a bar.             | Data warehouse, Search      |
| Big number `big-number` | One large figure, and how it's changed.             | Custom part, Data warehouse |

## Payments and shopping

| Drawing                     | What it shows                                        | Suits               |
| --------------------------- | ---------------------------------------------------- | ------------------- |
| Card payment `card-payment` | A card tapped, and the payment approved.             | Service             |
| Checkout `checkout`         | A basket, its total and a pay button.                | Service, Client app |
| Receipt `receipt`           | A receipt printing line by line.                     | Service, Database   |
| Invoice `invoice`           | An invoice with its lines, a total and a paid stamp. | Service             |
| Subscription `subscription` | A plan renewing each month.                          | Service, Scheduler  |
| Cart `cart`                 | Items dropping into a shopping cart.                 | Service, Client app |
| Stock `stock`               | Products on shelves, with how many are left.         | Database, Service   |
| Orders `orders`             | Orders moving from placed, to packed, to shipped.    | Service, Worker     |
| Refunds `refunds`           | Payments going out, and a few coming back.           | Service             |
| Fraud check `fraud-check`   | Each payment scored, with the risky ones held.       | Service, AI model   |
| Ledger `ledger`             | Debits and credits that always balance.              | Database, Service   |
| Delivery `delivery`         | A parcel moving along its route to a door.           | Service, Worker     |
| Prices `prices`             | A price tag that follows demand.                     | Service             |

## Operations

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

## Inside a service

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

## General

| Drawing               | What it shows                                         | Suits                         |
| --------------------- | ----------------------------------------------------- | ----------------------------- |
| Blank `blank`         | An empty box, for anything.                           | Custom part                   |
| Cog `cog`             | A turning cog, for something that does work.          | Custom part                   |
| Modules `modules`     | Blocks fitted together, for something made of parts.  | Custom part                   |
| Sparkline `sparkline` | A small line chart, drawing as it goes.               | Custom part, Service          |
| Bar chart `bar-chart` | Bars rising and falling.                              | Custom part                   |
| Ring `ring`           | A ring filling to a share.                            | Custom part                   |
| Status `status`       | A list of checks, each passing or failing.            | Custom part                   |
| Flowchart `flowchart` | Boxes and arrows, with something moving through them. | Custom part                   |
| Stack `stack`         | Layers stacked one on another.                        | Custom part                   |
| Checklist `checklist` | Tasks being ticked off.                               | Custom part                   |
| Hub `hub`             | One centre joined to many.                            | Custom part, Gateway, Topic   |
| Filter `filter`       | Many go in, and few come out.                         | Custom part, Firewall, Search |
| Cycle `cycle`         | Steps going round and round.                          | Custom part, Worker           |
| Signal `signal`       | A pulse sent out in rings.                            | Custom part, Client app       |
| Transform `transform` | Shapes going in, and changed shapes coming out.       | Custom part, Function, Worker |

---

# Ready-made scenarios

> The scenarios the scenario panel offers out of the box, and what each one tests.

The scenario panel offers 9 ready-made scenarios. Levels are multiples of a normal day’s busiest moment, so they suit a map of any size. Pick one, then change anything under **Set up** to make it your own. See [scenarios](https://docs.flozu.app/guides/scenarios.md).

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

---

# File format

> What's inside a .flozu.json map file and a .flozu-bundle.json bundle, how Flozu checks them, and how older files keep opening.

A map saves as one `.flozu.json` file: indented JSON, readable in any text editor, and friendly to version control. The current format is version 17. Files saved before the rename end in `.fflo.json` and still open: the contents are the same, and only the ending changed.

## What’s inside

```ts
FlozuMap    { schemaVersion, id, name, description?,
             components, connections, groups, notes, views,   // each keyed by id
             stories?, scenarios?,                            // left out while there are none
             lineRoute?: "square" | "straight" }             // how its lines run, curved if left out


Component  { id, kind, name, description?, technology?, external?: true,
             position, size?, layout?, visual?, style?, groupId?, flow?,
             inside?: { mapId }, meta? }                    // the map it opens into
Connection { id, source: { componentId, port?, side? }, target: { componentId, port?, side? },
             kind: "request" | "message", direction: "forward" | "both",
             label?, protocol?, flow?, style?, standby?: true }
Group      { id, kind, name, description?, position, size, parentId?, style? }
Note       { id, text, position, width?, groupId?, style? }
View       { id, name, audience: "technical" | "non-technical",
             hidden, collapsed, wording }
Story      { id, name, steps }
```

In a file, parts are `components`, lines are `connections` and zones are `groups`. Traffic lives on a connection’s `flow` (`rate`, `unit`), and limits on a component’s `flow` (`capacity`, `limit`, `buffer`, `scaling`, `people`). A component’s `flow` can also say how many seconds it takes to handle one thing (`latency`, such as `0.05`) and what it costs to run for an hour, in dollars (`cost`, for one copy of a part that auto-scales), for a scenario’s [estimates](https://docs.flozu.app/guides/response-times-and-cost.md). Anything left at its default, such as a standard card or a kind’s own drawing, is left out of the file.

A line with `standby: true` carries nothing until a line beside it fails, then takes its traffic over. A saved scenario’s `events` can include failures: `{ kind: "failure", at, length?, target: { components?, connections?, zone? }, mode: "down" | "degraded", keep? }`. A failure without a `length` lasts to the end, and `keep` is the share a degraded one keeps.

A line’s `side` on an end is the side of the part it meets (`left`, `right`, `top` or `bottom`), left out for the usual right side out and left side in. A line’s `style` can add `hidden: true` (draw only what moves along it), an `effect` (`traffic`, `pulse`, `flow` or `none`) and a `route` (`curved`, `square` or `straight`), which wins over the map’s `lineRoute`. A colour in any `style` is a palette name such as `"blue"`, or a colour of your own as six hex digits such as `"#3a7bd5"`.

A story’s steps can each show a moment of a saved scenario (`scenario: { scenarioId, at }`, `at` in seconds from its start) and compare one of the map’s proposals with where it began (`compare: { proposalId }`). The proposal lives in the map’s history, not in the file, so a copy without its history shows that step on the map.

A part’s `inside` names the [map it opens into](https://docs.flozu.app/guides/maps-inside-parts.md) by its id alone, so moving or renaming either map never breaks the link. A line’s `port` on an end names the part inside that map it joins, when you’ve chosen one with **Lands on** or **Leaves from**.

The full schema lives in [`packages/core/src/model.ts`](https://github.com/flozu-app/flozu/blob/main/packages/core/src/model.ts), and `mapJsonSchema()` exports it as JSON Schema.

## What a file doesn’t hold

- **Where it was kept.** A map’s project or folder belongs to storage, not to the map.
- **Its history.** Versions and proposals are kept beside the map. A map file is always the map as it is now. A bundle carries the history.

## Bundles

A bundle (`.flozu-bundle.json`) holds several maps in one file: a map with its history, a project, a folder or every map. It’s JSON too:

```ts
Bundle      { bundleFormat: 1, name, scope: "map" | "folder" | "library", exportedAt,
              folders,                  // paths inside the bundle, such as "Payments/Services"
              maps: BundledMap[] }
BundledMap  { folder?, createdAt?, updatedAt?, map, versions?,
              linked?: true }           // only here because a part in the bundle opens into it
```

Each map and version in a bundle is checked and updated like any file, so an old bundle keeps importing. See [import](https://docs.flozu.app/guides/import-export.md#import) for what happens to each when it comes in.

## Outlines

An outline (`.flozu-outline.json`) is a map with nothing placed: its parts, the lines between them and the zones they sit in, how they look, the traffic they carry, and the notes, views, scenarios and stories that go with them. It’s what Claude writes when it [maps your code](https://docs.flozu.app/guides/map-your-code.md), and Flozu lays it out as a new map when you import it.

```ts
Outline      { outlineFormat: 2,                      // 1 still reads: parts, links and zones only
               name, description?,
               lineRoute?: "curved" | "square" | "straight",
               parts: OutlinePart[],                  // 1 to 300
               links?: OutlineLink[],                 // up to 1,000
               zones?: OutlineZone[],                 // up to 100
               notes?: OutlineNote[],                 // up to 100
               views?: OutlineView[],                 // up to 20
               scenarios?: OutlineScenario[],         // up to 20
               stories?: OutlineStory[] }             // up to 20
OutlinePart  { id, name,
               kind?, preset?,                        // a kind, a ready-made part, or both
               description?, technology?, external?: boolean,
               zone?,                                 // the id of the zone it sits in
               code?,                                 // where it lives, such as "services/orders"
               meta?,
               opens?,                                // the id of a saved map of what's inside it
               layout?: "standard" | "showcase" | "wide" | "slim",
               size?: "small" | "standard" | "large" | "extra-large",
               drawing?,                              // a drawing's id, such as "hit-rate"
               style?,                                // as a part's style in a map
               flow? }                                // as a part's flow in a map
OutlineLink  { id?, from, to,                         // part ids
               kind?: "request" | "message" | "uses", // worked out from its ends if left out
               label?, protocol?, direction?: "forward" | "both",
               rate?, unit?,                          // per second; a unit needs a rate
               fromSide?, toSide?,                    // "left" | "right" | "top" | "bottom"
               style?,                                // as a line's style in a map
               standby?: boolean }
OutlineZone  { id, name, kind?: "zone" | "network" | "region" | "system" | "team",
               description?, parent?,                 // the id of the zone it sits inside
               style? }
OutlineNote  { id?, text, zone?, width?, style? }     // without a zone, it sits under the map
OutlineView  { id?, name, audience: "technical" | "non-technical",
               hide?: id[], collapse?: zoneId[], wording?: { [id]: { name?, description? } } }
OutlineScenario { id?, preset?,                       // a ready-made scenario's key
               name?, duration?,                      // needed without a preset
               ...the rest of a scenario's plan }     // anything set wins over the preset
OutlineStory { id?, name,
               steps: { id?, title, text?, focus?: id[],
                        scenario?: { id, at },        // a moment of one of the outline's scenarios
                        overrides? }[] }              // 1 to 60
```

Ids are yours to choose, such as `orders-api`, and they become the ids on the map. Every id is used once across the outline, and everything an outline names by id is in it. A part starts from its preset’s kind, technology, drawing, layout and limits, and anything set on the part wins. A named size is its layout’s own (a large wide card is 448 × 208). A part’s `code` shows under **Code** in its details, and `opens` makes it a [part with a map inside](https://docs.flozu.app/guides/maps-inside-parts.md), such as a repository’s own map on a project’s overview. A drill scenario, such as `region-down`, takes down what matters on the map as drawn. An outline that breaks a rule is refused with a message that says what to fix and where. `outlineJsonSchema()` in core exports the outline as JSON Schema, and the full guide Claude follows is at [map-your-code.md](https://docs.flozu.app/map-your-code.md).

## Checked before it opens

Flozu checks every file against the schema and [the map’s rules](https://docs.flozu.app/concepts/the-map.md#what-the-map-keeps-true) before it opens it, whether it comes from storage, an import, a share link or a version. A file that fails says why.

## Older and newer files

Every time the format changes, its version goes up and Flozu learns to update older files as they open, so a file from any earlier version keeps working. A file from a newer version of Flozu is refused with a message to update.

A map that names a drawing this version of Flozu doesn’t know still opens; that part shows its kind’s own drawing.

---

# Glossary

> The words Flozu uses, in one place.

**Auto-scaling.** A part that runs more copies of itself as traffic grows. See [auto-scaling](https://docs.flozu.app/guides/traffic-and-limits.md#auto-scaling).

**Blast radius.** Everything a failure touches, and how much of the traffic fails where it starts. See [failure drills](https://docs.flozu.app/guides/failure-drills.md).

**Bundle.** One `.flozu-bundle.json` file holding several maps, with their folders and, if you like, their versions and proposals. See [import and export](https://docs.flozu.app/guides/import-export.md).

**Buffer.** How much a queue or topic can hold while it waits to be worked through. Shown as **Holds** in the inspector.

**Capacity.** The most a part can handle each second. More than this backs up.

**Copy.** One running instance of a part that auto-scales.

**Draft.** A scenario you’ve changed but not saved with the map. It belongs to this window only.

**Drawing.** The small live picture in a part’s panel. Any part can show any drawing.

**Drill.** A scenario that takes a part, a line or a zone down for a while, to see what fails and what takes over. See [failure drills](https://docs.flozu.app/guides/failure-drills.md).

**Entry point.** A part no line flows into, such as people or an app. Scenarios scale the traffic that starts there.

**Estimate.** A scenario’s rough figure for how long requests take, how much fails, or what the map costs to run, worked out from the map rather than measured. See [response times and cost](https://docs.flozu.app/guides/response-times-and-cost.md).

**Limit.** The most a part lets through each second. The rest is turned away.

**Line.** A connection between two parts, carrying requests or messages. Called a connection in the file format.

**Map.** One document holding parts, lines, zones, notes, views, stories and saved scenarios.

**Map inside.** Another map a part opens into, to show what’s inside it. See [maps inside parts](https://docs.flozu.app/guides/maps-inside-parts.md).

**Message.** Traffic that’s sent and left, like an event or a job. Drawn as a dashed lime line.

**Moment.** A point in a scenario worth stopping at, such as the busiest moment or when a part first runs over.

**Note.** Plain words on the canvas.

**Part.** A piece of the system, such as a service or a database. Called a component in the file format.

**Preset.** A ready-made part on the library’s Presets shelf, such as a Redis cache.

**Project.** A folder at the top level, holding maps and folders. The **Maps** panel lists each one as a tree.

**Proposal.** A copy of a map to change freely, which remembers where it began so it can be compared and adopted.

**Rate.** How much a line carries each second at the busiest moment of a normal day.

**Replay.** The same scenario played on two maps, such as a proposal and where it began, to see what a change does to how the map copes. See [replay a scenario](https://docs.flozu.app/guides/versions-and-proposals.md#replay-a-scenario).

**Request.** Traffic that asks and waits for an answer, like an HTTP call. Drawn as a solid pale blue line.

**Response time.** How long a request takes, its part’s own time and the time of the requests that part makes in turn. A scenario [estimates](https://docs.flozu.app/guides/response-times-and-cost.md) it.

**Run by someone else.** A part another company runs, drawn with a dashed outline.

**Scenario.** A “what if?” played over time on a map, such as Black Friday.

**Single point of failure.** A part or zone that nothing takes over from, so traffic fails when it goes down. Fixed by a change to the map’s shape, such as a standby copy beside it. See [failure drills](https://docs.flozu.app/guides/failure-drills.md#fix-it).

**Spare room.** How much headroom a part should keep. A part past it is tight. 30% by default.

**Standby line.** A line that carries nothing until a line beside it fails, like a failover to a replica. See [lines](https://docs.flozu.app/guides/lines.md#standby-lines).

**Story.** A walk through a map, one step at a time, for presenting it.

**Tight.** Busier than its spare room allows, but not yet over its capacity.

**Uses line.** A dotted grey line saying one part depends on another, such as code using a library. It carries no traffic.

**Version.** The map as it was at one moment, kept beside it.

**Weak spot.** A part or zone the map can least afford to lose, found by taking each down in turn. See [failure drills](https://docs.flozu.app/guides/failure-drills.md#find-weak-spots).

**View.** One way of showing a map to one audience, with things hidden and plain wording.

**Zone.** A frame around parts that belong together, such as a region or a team. Called a group in the file format.

---

# Getting help and sending feedback

> The Help menu, the question mark at the top right, leads to these docs, a short feedback form, the support address and the legal pages.

**Help**, the question mark at the top right of every screen, beside the theme switch, opens everything for getting help and telling us things.

![The Help menu open from the question mark at the top right: Read the docs, Send feedback, Email support, then Privacy notice, Terms of use and Impressum.](https://docs.flozu.app/_astro/help-menu-light.RwqjFxcp_YT50Q.webp)

| Item               | What it does                                                    |
| ------------------ | --------------------------------------------------------------- |
| **Read the docs**  | Opens these docs in a new tab.                                  |
| **Send feedback…** | Opens a short form. Write anything: a bug, an idea, a question. |
| **Email support**  | Starts an email to <support@flozu.app>.                         |
| **Privacy notice** | What Flozu keeps about you, and why.                            |
| **Terms of use**   | The rules for using Flozu during the beta.                      |
| **Impressum**      | Who runs Flozu, as German law asks.                             |

## Sending feedback

Write what’s on your mind and press **Send**. Every message is read. The form also says which screen you sent it from, such as the editor or the Maps page, but never the map you had open.

If you’re signed in, tick **Reply to me at** your address to get an answer by email. Your address is kept with your feedback only when you tick it, and your feedback goes when your account does. Without ticking it, your feedback is kept with your account but nobody writes back.

In the Mac app, and anywhere Flozu runs without its online service, **Send feedback** starts an email to support instead.

## When something breaks

If Flozu stops, it shows a page that offers to download the map you had open, then reload. It also tells us what went wrong, without anything from your map or who you are, so it can be fixed even if you don’t write in. If it keeps happening, use **Send feedback** or email support and say what you were doing.

---

# Questions and answers

> Answers to common questions about Flozu, from where maps are kept to how accurate scenarios are.

## Is Flozu free?

Yes, during the beta. It isn’t sold yet.

## Do I need an account?

No. On the web you can continue as a guest, and your maps stay in your browser. The Mac app keeps them as files and never asks you to sign in. An [account](https://docs.flozu.app/guides/accounts.md) keeps your maps online, so they open on any computer, and lets you share them with a [team](https://docs.flozu.app/guides/teams.md). During the beta, signing in is for invited addresses. See [where maps live](https://docs.flozu.app/concepts/where-maps-live.md).

## Does Flozu connect to my systems?

No. Flozu never calls, deploys, monitors or runs anything. The motion and the scenarios come from the numbers you put on the map. That’s what lets it work offline and in front of a client.

## Can my assistant work with my maps?

Yes. [Connect an assistant](https://docs.flozu.app/guides/connect-an-assistant.md) such as Claude, Cursor or Codex to your account, and it can map your code, read your maps, run scenarios on them and suggest changes, each one a proposal for you to adopt. Without an account, an assistant can still [map your code into a file](https://docs.flozu.app/guides/map-your-code.md) that you import.

## Is my map sent anywhere when I share a link?

No. A share link carries the map inside it, after the `#`, and browsers never send that part of an address to a server. Whoever you send it to can read the map, so only share what its audience should see. Sharing from a view leaves out what that view hides.

## How accurate are scenarios?

They’re as good as the numbers on the map, and the model is simple on purpose. It’s good at finding which part runs out of room first and roughly how much more it needs. It times every request out at 30 seconds, and it doesn’t know about retries, cold caches or slow queries. See [what it can’t tell you](https://docs.flozu.app/concepts/how-traffic-is-worked-out.md#what-it-cant-tell-you).

## Can Flozu show what happens when something breaks?

Yes. A [failure drill](https://docs.flozu.app/guides/failure-drills.md) takes a part, a line or a whole zone down in a scenario, and shows what fails, what takes over and what to change. **Find weak spots** tries each part and zone in turn. Flozu works it out from the map; it never touches your real systems.

## Why is a part marked “Not checked”?

It has no capacity set, so there’s nothing to compare its load against. Set its capacity in its **Traffic** tab.

## Why doesn’t the scheduler get busier on Black Friday?

A scheduler starts traffic by the clock, not because people arrive, so a scenario’s busier day doesn’t scale it. To make it busier, raise the rates of the lines it sends.

## Can I use my own icons or shapes?

A part’s mark is its technology’s logo, when Flozu knows it, or the kind’s icon. You can pick any of the library’s drawings for any part, and give anything your own colours. Plain drawing shapes aren’t part of Flozu: a map holds parts, zones and notes, so it always means something.

## Why don’t I see AWS or OpenAI logos?

Those brands don’t allow their logos in Simple Icons, where Flozu’s logos come from, so those parts keep the kind’s icon.

## Can several people work on one map?

Yes, in a [team](https://docs.flozu.app/guides/teams.md). Everyone in it opens the team’s maps, and each person’s role says whether they can edit them, suggest changes as proposals, or only look. Two people can’t edit the same map at the same moment yet: if both save, the second save is kept as a proposal, so nobody’s work is lost. Without an account, share a link for people to look, or export the map with its history for someone to change, then [compare](https://docs.flozu.app/guides/versions-and-proposals.md#compare) versions.

## Can I use Flozu offline?

Yes, with maps kept in the browser or on your Mac. Once Flozu has loaded, everything works without a connection, and the Mac app never needs one. Maps in an account need a connection to save.

## Does Flozu work on a phone?

You can look at, present and share maps on a phone, and the sidebar slides over the page. Building a map is easier with a mouse or trackpad and a bigger screen.

## How do I get a map from one computer to another?

Keep it in your [account](https://docs.flozu.app/guides/accounts.md), and it opens wherever you sign in. Without one, export it from its menu on the Maps page, and import the file on the other computer. To move everything, select **Export…** in the **⋯** menu on the Maps page: one file holds every map, in its projects and folders. In the Mac app, maps are files, so anything that syncs your Documents folder moves them too. See [import and export](https://docs.flozu.app/guides/import-export.md).

## Can I put a map in a slide deck?

Yes. In the editor, select **Export** and choose a PNG image, an SVG drawing or a PDF of the whole map, dark or light, with a see-through background if you like.

## Can one part show what’s inside it?

Yes. Give it a [map inside](https://docs.flozu.app/guides/maps-inside-parts.md): its own map of modules, endpoints and what they call, which you open from the card and leave by the trail above it.

## Where do I report a problem or ask for something?

Choose **Help**, then **Send feedback…**, or email <support@flozu.app>. See [getting help](https://docs.flozu.app/help/getting-help.md).

---

# Troubleshooting

> What to do when you can't sign in, a map won't import, a link won't open, traffic doesn't move or a key does nothing.

## I can’t sign in

- **Your address hasn’t been invited.** During the beta, only invited addresses can make an account. Sign in with the address you were invited with, or [continue as a guest](https://docs.flozu.app/guides/accounts.md#continue-as-a-guest) and keep your maps in the browser for now.
- **You signed in with another address.** An invite is for one email address, so choose the Google or GitHub account that uses it.

## I can’t see a team’s maps

Maps in a team show only while that team is chosen in the workspace switcher at the top left. If the team isn’t listed, your invite may still be waiting: sign in with the address it was sent to. An invite runs out after 30 days, so ask an owner or admin to invite you again. See [teams](https://docs.flozu.app/guides/teams.md#invites).

## A file won’t import

Flozu says why. The usual reasons:

- **It isn’t from Flozu.** Flozu imports the maps, bundles and versions it exports. See [import and export](https://docs.flozu.app/guides/import-export.md).
- **It was made by a newer version of Flozu.** Update Flozu, then import it again.
- **It’s been edited by hand and breaks a rule,** such as a line to a part that doesn’t exist. The message names what’s wrong.
- **Part of a bundle came in.** Whatever in a bundle can’t be read is left out and named, and the rest still comes in.
- **Its folders are too deep.** A bundle that would nest folders more than six deep is refused. Export a folder further down instead.

## A part’s badge says “Map not here”

The map it opens into isn’t saved here. It may have been deleted, or not come with the file or link. Export the map **with its history** to take the maps inside its parts along, or give the part a new one from its **Map inside** section. See [maps inside parts](https://docs.flozu.app/guides/maps-inside-parts.md).

## A share link doesn’t open

- **It was cut short.** Some apps trim long links. Flozu goes to home and says the link is incomplete. Ask for it again, or for the exported file.
- **It’s too big.** Flozu refuses a link that would unpack to more than 5 MB. Share the file instead.
- **It was made from Flozu’s source.** A link made while Flozu runs on someone’s own computer, at a `localhost` address, only opens there. Ask them for a link from [my.flozu.app](https://my.flozu.app/). See [share a link](https://docs.flozu.app/guides/presenting-and-sharing.md#share-a-link).

## Traffic isn’t moving

- **The map is paused.** Press play on the island at the foot of the canvas.
- **The lines have no rate.** Give a line a rate in its **Traffic** tab.
- **Your computer asks for reduced motion.** Flozu then opens maps paused, and moves only when you press play.

## A key does nothing

- **You’re typing in a field.** Shortcuts don’t fire there. Press `Esc` or click the canvas first.
- **The map is presented.** Keys that edit do nothing while presenting. Choose **Edit** in the mode menu on the island.
- **The pointer isn’t over the canvas.** A part’s key adds it under the pointer, or in the middle of the screen when the pointer is elsewhere.

## My maps are gone

- **You’re signed in, and the maps were made as a guest.** Signed in, Flozu shows your account’s maps only. The maps you made in the browser are still there: home offers to move them in, and they show again if you sign out.
- **Another workspace is chosen.** Each map is kept in one workspace. Choose another in the switcher at the top left.
- **Another browser or a private window.** Maps are kept per browser. Open Flozu in the browser you made them in.
- **Site data was cleared.** Clearing a browser’s site data deletes its maps. Import a copy you exported, if you have one.
- **On a Mac,** maps are files in Documents › Flozu. Check the Trash for anything deleted.

## The Mac app says it can’t be checked

A build that isn’t signed yet opens with a warning the first time. Right-click the app, choose **Open**, then **Open** again.

---

# Writing the docs

> How these docs are built, where each page lives, and how to keep them in step with the app.

These docs live in the Flozu repo, next to the code, in `apps/docs`. They’re built with [Starlight](https://starlight.astro.build) into a static site, so any static host can serve them.

- apps/docs/

  - public/\_headers Cloudflare’s headers for the Markdown copies

  - scripts/

    - check-twins.ts checks every page’s Markdown copy after the build
    - screens.ts takes the screenshots
    - shots.ts the steps for each screenshot

  - src/

    - assets/screens/ the screenshots, in both themes

      - …

    - components/

      - Diagram.astro a diagram drawn in SVG, in the page’s colours

      - diagrams/ each diagram, such as how a failure travels

        - …

      - DocsSearch.astro search, as a command menu over Pagefind’s index

      - PageActions.astro the Copy page menu beside each title

      - Screen.astro shows a screenshot in the reader’s theme

      - ShotToCome.astro a dashed box where a screenshot still to take will go

      - overrides/ the head, header, sidebar, page title, page outline, page foot, phone menu and theme picker, in place of Starlight’s

        - …

      - reference/ tables read from the code

        - …

    - content/docs/ one Markdown page per file

      - …

    - data/reference.ts

    - pages/ the Markdown copies, llms.txt and llms-full.txt

      - …

    - styles/theme.css the docs’ look

    - brand.ts the product’s name, logo and addresses

    - drill.ts the sections the sidebar, header and search list

    - search.ts turns Pagefind’s results into search’s rows

    - sections.ts a line and an icon for each section, for the Guides menu and the sidebar

    - icons.ts the few Lucide icons the docs draw, through components/Icon.astro

    - markdown.ts turns a page’s HTML into Markdown

    - twins.ts renders every page for its Markdown copy

    - sidebar.ts the sidebar, in reading order

    - pages.test.ts checks every page

    - markdown.test.ts checks the Markdown copies read well

    - theme.test.ts checks the colours stay readable

## Run them

```sh
pnpm docs:dev                      # http://localhost:4321, reloading as you edit
pnpm --filter @flozu/docs build     # the site, in apps/docs/dist
```

Use `pnpm docs:dev`, not `pnpm docs`: that one is pnpm’s own command, which opens a package’s page on npm. The site runs in the foreground until you press `Ctrl`+`C`. Astro starts its dev server in the background when it thinks an AI agent ran it, and the docs’ `dev` script turns that off. If a background one is ever left running, `pnpm --filter @flozu/docs exec astro dev stop` stops it.

## How they look

The docs are a plain reference site, so nothing competes with the words. The colours follow Vercel’s docs and the sizes follow Linear’s: a light grey page in light and a black one in dark, with no rules between the header, the sidebar, the page and its outline; a slim header, a narrow sidebar of small rows, and the words in 15px type in a column of about 75 characters, under calm, lightly tracked headings (`theme.test.ts` holds the sizes). On a wide screen the sidebar, the words and “On this page” sit together as one centred block, the outline as wide as the sidebar, and the words start in the same place on every page, outline or not. The header has **Get started** and a **Guides** menu of every section. Search sits at the top of the sidebar, stays there as the sidebar scrolls, and opens a command menu of pages and headings. Under it the sidebar lists every section (`src/drill.ts` works them out from `src/sidebar.ts`), each a row with its icon in a small square (`sectionIcons` in `src/sections.ts`) that folds its pages away. The section you’re in is always open, folded ones stay folded from page to page in that browser, and the sidebar opens scrolled to the page you’re on, which is a grey pill. **Contact support** and **Get help** stay at its foot. In “On this page”, one bar slides down a grey track to the section you’re reading. The theme picker at the top right is a button that opens a menu of System, Light and Dark. Code, notes, tables and cards are white boxes with a hairline. Text is near black, with grey for everything that isn’t the text you came for, and links are the text’s own colour with a soft underline. Flozu’s orange is only in the logo. Every colour comes from `src/styles/theme.css`, and `theme.test.ts` checks that the orange is the app’s and that text, links and buttons stay readable in both themes. The docs don’t copy the app’s or the homepage’s look.

The name and logo live in `src/brand.ts` and `src/assets/logo-*.svg`, so a new name or logo changes those files and nothing else.

## For assistants

Every page is also plain Markdown at its own address plus `.md`, such as [`/guides/lines.md`](https://docs.flozu.app/guides/lines.md), so an assistant can read it without the page around it. [`/llms.txt`](https://docs.flozu.app/llms.txt) lists every page with a line about it, and [`/llms-full.txt`](https://docs.flozu.app/llms-full.txt) holds them all in one file. Each page’s head links to its copy, and **Copy page**, beside each title, copies it, opens it, or hands the page to Claude or ChatGPT.

The copies are made from each page’s rendered HTML (`src/twins.ts` and `src/markdown.ts`), so a screenshot becomes its picture with its alt text, an aside a quote, tabs a list, and a table read from the code the same table. Nothing is written twice. After every build, `scripts/check-twins.ts` fails if a page has no copy, if a copy still holds a component tag, if it holds fewer words than the page shows, or if `llms.txt` doesn’t list it. A new component that draws something special needs a rule in `markdown.ts` and a test in `markdown.test.ts`.

## When you change the app

A pull request that changes what someone sees or does updates the docs in the same pull request:

1. **Find the page.** Each feature has a guide under `src/content/docs/guides`. A new feature gets a new page, listed in `src/sidebar.ts`.
2. **Update the words.** Say what a person does and sees, in the app’s own words: the same button names, in bold.
3. **Update the screenshots** if the screen looks different. Run `pnpm --filter @flozu/docs screens <name>` for the shots that changed, or with no name for all of them. Add a new shot to `scripts/shots.ts` as the steps that get the app there. If a shot can’t be taken yet, put a `ShotToCome` component where it goes, with the alt text the shot will have: it draws a dashed box that says what the picture will show. Swap it for a `Screen` with the same alt once the shot is taken. `grep -rn ShotToCome src/content` lists the ones left.
4. **Run the checks.** `pnpm check` builds the docs and fails on a broken link, a page missing from the sidebar or a screenshot that doesn’t exist.

## What updates itself

Some pages read straight from the code, so they never need editing by hand:

- [Part kinds](https://docs.flozu.app/reference/part-kinds.md) and the part keys, from the app’s parts catalogue.
- [Presets](https://docs.flozu.app/reference/presets.md) and [drawings](https://docs.flozu.app/reference/drawings.md), from `@flozu/core`.
- [Ready-made scenarios](https://docs.flozu.app/reference/scenario-presets.md), from `@flozu/core`.
- The [Mac app’s menu](https://docs.flozu.app/mac/overview.md#the-menu-bar), from the Mac app’s Rust source.
- Counts in the prose, such as how many presets there are, through `<Count of="presets" />`.

When a list like these appears in a guide, prefer one of these components to typing it out.

## How a guide reads

Every guide follows the same shape, so a reader always knows where to look:

1. **What it’s for,** in a sentence or two, as the question the reader has. “Will your checkout cope on Black Friday?”
2. **Try it,** three to six steps on the **Checkout system** template, ending in something they can see. Every guide uses the same map, so readers learn it once.
3. **What you’re looking at,** with the screenshot, and what each colour or number means.
4. **Doing more,** each task under a heading named for the job, such as “Take a whole region down”.
5. **Good to know,** the exact rules and edge cases, at the foot, for whoever needs them.

Use real numbers from the map, worked out by Flozu, rather than made-up ones: the reader will see the same numbers when they try it. Walkthroughs go further and answer one question from start to finish. Concepts pages are where the docs get technical: the rules, the maths and diagrams. A diagram is an SVG component in `src/components/diagrams`, drawn with the `dg-` classes in the theme, so it follows light and dark and never needs retaking when the app changes.

## How to write

- **Short, plain and in sentence case.** Write for someone who has never seen Flozu.
- **Say what to do, then what happens.** “Select **Save version**. The map is kept as it is now.”
- **Use the app’s words.** A part, a line, a zone, a note. Bold the names of buttons and tabs.
- **Show, don’t list.** One screenshot near the top of a guide beats a long description of it.
- **Write alt text that teaches.** Say what the picture shows, so the Markdown copy makes sense without it.
- **Every page has a description,** used by search and link previews.

## Publish them

`pnpm --filter @flozu/docs build` writes a plain static site to `apps/docs/dist`, with its own search index, so any static host can serve it, such as Cloudflare. Set `DOCS_SITE` to the address it’s served from, such as `https://docs.example.com`, so its sitemap and links point there.