These flows are lifecycle stories that span multiple UC groups. They are intentionally high-level — for state-machine detail go to specification/flows/, for endpoint-level detail go to the relevant UC.

The diagrams below are inline Mermaid sequenceDiagram. Structural and infrastructure views are also inline Mermaid — see infrastructure.md. The legacy Structurizr DSL workflow (overview/workspace.dsl + pre-rendered SVGs) was retired on 2026-05-23.

Project lifecycle

How a project goes from “an idea in the user’s head” to “a published web app”.

sequenceDiagram
    actor U as User
    participant FE as TalkIDE FE
    participant BE as TalkIDE BE
    participant NFS as NFS
    participant PG as Platform PG
    participant Mara as Mara (worker / CLI)
    participant Build as BuildService
    participant K8s as K8s API
    participant Reg as DO Registry

    U->>FE: Create Project (name, slug, accent, stack)
    FE->>BE: POST /projects
    BE->>PG: insert PROJECT (status=DRAFT)
    BE->>NFS: scaffold output-projects/{slug}/ (.talkide/, backend/, frontend/, CLAUDE.md)
    BE-->>FE: 201 Created
    FE-->>U: project card on dashboard

    U->>FE: open project, send first message
    FE->>BE: POST /conversations + /messages
    BE->>Mara: spawn turn (via Gateway, UC-08001)
    Mara->>NFS: edit files, run tests
    Mara-->>BE: AGENT_MESSAGE / TASK_COMPLETED activities
    BE->>PG: insert ACTIVITY rows
    BE-->>FE: SSE activity events (UC-05001)

    U->>FE: "ship it" → Apply Version
    FE->>BE: POST /projects/{id}/versions/{n}/apply
    BE->>Build: trigger build job (Kaniko, ADR-019)
    Build->>NFS: read source
    Build->>Reg: push image
    BE->>K8s: ensure tenant ns, app DB, deploy (ADR-015..017, 021)
    K8s-->>BE: rollout complete
    BE->>PG: PROJECT.status=LIVE, ProjectVersion.status=APPLIED
    BE-->>FE: 200 OK
    FE-->>U: Live link {slug}.talkide.app

    Note over U,K8s: ARCHIVE / DELETE flows mirror this in reverse —<br/>K8s ns torn down immediately, DB+NFS kept 14 days

State-machine details live in specification/flows/project-management-flow.md and specification/flows/project-creation-flow.md.

Conversation lifecycle

Structural view (C4 L2 dynamic) — who talks to whom:

{/* Image missing: Conversation turn — structural view (../assets/diagrams/maraTurn.svg) */}

A multi-turn chat with Mara, including fatigue gating (planned, UC-08002) and session resume.

sequenceDiagram
    actor U as User
    participant FE as TalkIDE FE
    participant BE as TalkIDE BE
    participant FUP as FUP / Fatigue (UC-08002, planned)
    participant GW as Anthropic Gateway (UC-08001)
    participant Mara as Mara (worker / CLI)
    participant Ant as Anthropic API

    U->>FE: send message
    FE->>BE: POST /messages
    BE->>FUP: check 5h + weekly windows
    alt both windows have headroom
        BE->>GW: invokeMaraTurn(conversation, prompt)
        GW->>Mara: POST /sessions (worker) or spawn (CLI)<br/>resume by sessionId if set
        Mara->>Ant: tokens in / tokens out
        Ant-->>Mara: streamed turn
        Mara-->>GW: tool_use, agent_message, task_completed
        GW->>BE: persist api_usage_ledger row
        BE-->>FE: SSE activity stream + final PM message
    else any window at 100 %
        BE-->>FE: 429 ASLEEP envelope (fatigue avatar degradation)
    end

    Note over U,FE: User can close conversation any time → status=CLOSED.<br/>Starting a new conversation auto-closes the previous ACTIVE one.

State-machine details: specification/flows/conversation-flow.md. FUP details: specification/mara-fatigue-fup.md and ADR-020.

Deploy lifecycle

Structural view (C4 L2 dynamic) — who calls whom:

{/* Image missing: Deploy user app — structural view (../assets/diagrams/deployUserApp.svg) */}

A ProjectVersion going from DRAFT → APPLYING → APPLIED, exercising Stopa B.

sequenceDiagram
    actor U as User
    participant BE as TalkIDE BE
    participant Snap as SnapshotService<br/>(Stopa B.0.1, ADR-018)
    participant Build as BuildService<br/>(Stopa B.0.2, ADR-019)
    participant Dep as AppDeployer<br/>(Stopa B.4, ADR-017)
    participant K8s as K8s API
    participant DB as Data-plane provisioner<br/>(ADR-023)
    participant Ing as Ingress reconciler<br/>(Stopa B.5, ADR-021)
    participant Reg as DO Registry

    U->>BE: Apply Version OR Publish (B.7)
    BE->>Snap: snapshot working tree → tarball
    Snap-->>BE: snapshot ready
    BE->>Build: enqueue Kaniko build job
    Build->>Reg: push image talkide/{slug}:{version}
    Build-->>BE: image digest
    BE->>K8s: ensure namespace {tenant}-{env} (ADR-015 / ADR-026)
    BE->>DB: ensure per-app schema + role on cluster B (ADR-023)
    BE->>Dep: deploy(image, namespace, env)
    Dep->>K8s: apply Deployment + Service + Secret
    K8s-->>Dep: rollout ready
    Dep-->>BE: deployed
    BE->>Ing: reconcile ingress (DEV uuid host or PROD slug host)
    Ing->>K8s: upsert Ingress object
    BE-->>U: URL live

    Note over BE,Ing: DEV (preview) and PROD (published) are two parallel<br/>namespaces per project. DEV refreshes per build,<br/>PROD only on explicit Publish (B.7).

ADR refs: ADR-015 namespaces, ADR-023 data-plane DB & pooling, ADR-017 deployer, ADR-018 snapshots, ADR-019 builds, ADR-021 ingress.

Auth lifecycle (signup → JWT → refresh)

Captured for completeness. State-level detail in specification/flows/user-auth-flow.md.

sequenceDiagram
    actor U as User
    participant FE as TalkIDE FE
    participant BE as TalkIDE BE
    participant PG as Platform PG

    U->>FE: signup (email, password, name)
    FE->>BE: POST /auth/signup
    BE->>PG: insert USER + auto TENANT (owner=newUser)
    BE-->>FE: { accessToken, refreshToken }
    FE-->>U: redirect to workspace

    Note over FE,BE: Subsequent requests carry Bearer JWT.<br/>15 min access / 14 day refresh.<br/>Axios interceptor refreshes on 401 transparently.