Flows

A flow describes a goal-oriented sequence of steps a real person performs against a surface, with the entities and endpoints touched along the way.

A flow is not an API trace — it’s an answer to “how does <actor> accomplish <goal> right now”. If a flow can’t be described without naming a specific button on a specific screen, it’s at the right level.

Layout

flows/
  business/        # admin panel flows (tktspace-business)
  client-web/      # public web flows (tktspace-web)
  client-mobile/
    gym-app/       # apps/gym_app
    tickets-app/   # apps/tickets_app

Landing (tktspace-landing) is intentionally absent — it’s mostly static and rarely has multi-step flows worth documenting. If a landing flow needs documenting (e.g. lead-capture funnel), put it in client-web/ and call out the surface in frontmatter.

Phase 0.5

Flow content is empty. Phase 2 — content population — will start filling 2-3 priority flows once Phase 1 entity skeletons land.

Adding a new flow

1. Copy ../../templates/_flow-template.mdx into the right surface folder, rename to {flow-slug}.mdx.
2. Ask docs-writer for the next free FLOW-NNN ID.
3. Fill frontmatter: title, id, type: flow, actor, surface, entities_touched, status: draft.
4. Write Steps in order — each step names the actor, the action, and the API call (if any).
5. Include a Mermaid sequence diagram only if the flow has 3+ parties or non-linear branches. For simple linear flows, prose is enough.

What counts as a flow worth documenting

• Yes — any flow touching 2+ entities, with business-meaningful states, or with known edge cases.
• No — trivial CRUD (“admin edits a user’s email”); the entity doc’s surfaces table covers it.
• Yes — any flow crossing surfaces (e.g. business creates a thing → client consumes it). Split into one flow per surface, link them via related_flows.