Developer docs
Quality

User flows

How an actor moves through the product: step, screen, endpoint.

7 journeys · 3 complete. A flow is only done when every step is — press play to walk one.

UF-001

Sign up → organization created → dashboard

done

The bootstrap path. Creates the organization and its owner in one transaction, so there is never an org without an owner or a user without a tenant.

5 steps · 5 done

  1. Submit the signup form

    /signupPOST /api/v1/auth/signup

  2. API creates Organization + owner User in one transaction

  3. First audit row written

  4. Tokens stored, session established

  5. Land on the command centre

    /dashboardGET /api/v1/auth/me

Claude: The signup UI is not built yet — the API path is, and is covered by tests.

UF-002

Read the build board

done

What is built, what is next, how it is architected, what is tested, and the docs — without leaving the app or opening the repo.

5 steps · 5 done

  1. Open the landing page

    /

  2. Follow through to the command centre

    /dashboard

  3. Overview shows progress and what's coming up, computed across sections

    /dashboard

  4. Open the Features tab, expand an item for its remarks and updates

    /dashboard

  5. Open the Docs tab and read any doc in place

    /dashboard

Claude: Server-rendered from data/dashboard/*.json and docs/*.md — no client fetch, no waterfall.

UF-003

Plan a quarter for a project

planned

The core planning loop: brief in, plan out, calendar populated.

5 steps · 0 done

  1. Create a project

    /projects/newPOST /api/v1/projects

  2. Write the campaign brief — audience, offer, budget, success metric

    /projects/{id}/briefPOST /api/v1/projects/{id}/brief

  3. Generate a plan (channel mix, budget split, cadence)

    /projects/{id}/planPOST /api/v1/projects/{id}/plan/generate

  4. Edit the plan — the AI output is a draft, not a decision

    /projects/{id}/planPATCH /api/v1/projects/{id}/plan

  5. Accept — plan expands into calendar slots across the three tracks

    /projects/{id}/schedulerPOST /api/v1/projects/{id}/plan/accept

Claude: Step 4 is deliberate: a generated plan that lands straight on the calendar removes the judgement the plan needs.

UF-004

Agency drafts → lead approves → publishes

planned

The approval gate in its normal shape. An outside contributor produces work; an internal owner takes responsibility for it before it ships.

7 steps · 0 done

  1. Agency member logs in, sees only assigned projects

    /projectsGET /api/v1/projects

  2. Drafts a multi-channel post with per-channel overrides

    /composerPOST /api/v1/posts

  3. Submits for approval

    /composerPOST /api/v1/posts/{id}/submit

  4. Lead is notified

  5. Lead reviews and approves (or rejects with a comment)

    /approvalsPOST /api/v1/posts/{id}/approve

  6. Post is scheduled into a calendar slot

    /calendarPOST /api/v1/posts/{id}/schedule

  7. Worker publishes at the slot time; failures retry with backoff

Claude: Step 1 is the security-critical one: org scope is not enough for an agency user, the project assignment is checked too.

UF-005

Agent proposes → human approves → it is applied

done

The agentic loop, and the gate that makes it safe. An agent writes its whole proposal while the run is `awaiting_approval` — nothing has touched content, a budget or a platform at that point, so a rejected run costs model tokens and nothing else. There is deliberately no `running → applied` edge in the state machine.

6 steps · 6 done

  1. Press Run now on an agent

    /projects/:id/agentsPOST /api/v1/agents/runs

  2. Plan + project visibility checked; run written as `queued` and published to RabbitMQ

  3. Worker picks it up (`running`), the agent reads the project, and writes its proposal (`awaiting_approval`)

  4. Proposal appears beside the team it came from

    /projects/:id/agents/proposalsGET /api/v1/agents/runs

  5. Someone with `agents:approve` reads what it found and decides

    /projects/:id/agents/proposalsPOST /api/v1/agents/runs/:id/approve

  6. `apply.ts` runs — the Drafter creates posts, the others record or unlock the next step

    /projects/:id/content

Claude: No auto-apply mode. adwords-adsense planned autopilot as the default; that is where the money risk lives.

Claude: Marked done. The flow shipped; this row still described the planned shape, including a /approvals screen that now means something else — post sign-off, not agent proposals. Full walkthrough with diagrams in docs/AGENT_FLOW.md.

UF-006

Answer 'what is running and what is it returning?'

planned

The success metric from the brief: under 60 seconds, no spreadsheet.

4 steps · 0 done

  1. Open the KPI surface

    /kpisGET /api/v1/analytics/kpis

  2. Every channel, organic and paid, with spend, return and freshness

    /kpis

  3. Compare against vertical benchmarks

    /kpisGET /api/v1/ads/benchmarks

  4. Drill into a project or a channel

    /kpis/{scope}

Claude: Step 2 carries an as-of timestamp per source. A stale number that looks live is worse than no number.

UF-007

Connect a channel

planned

OAuth into a platform and keep the connection alive without anyone watching it.

5 steps · 0 done

  1. Pick a platform

    /settings/channels

  2. Redirect to the platform's consent screen

    GET /api/v1/channels/{platform}/oauth/start

  3. Callback exchanges the code; tokens encrypted at rest

    GET /api/v1/channels/{platform}/oauth/callback

  4. Profile fetched, account listed as connected

    /settings/channels

  5. Hourly job refreshes tokens expiring within 24h; a 6-hourly health check flags a break before a publish fails

Claude: Step 5 matters more than it looks — a silently expired token surfaces as a mysterious publish failure days later.