Architecture Concepts

Architecture Concepts

Acepe's core architecture vocabulary is documented in the repository under docs/concepts/.

Core map

%%{init: {'theme':'base','flowchart': {'curve': 'basis', 'nodeSpacing': 28, 'rankSpacing': 34}, 'themeVariables': {'fontFamily': 'Inter, ui-sans-serif, system-ui', 'primaryTextColor': '#1f2937', 'primaryBorderColor': '#9ca3af', 'lineColor': '#6b7280', 'tertiaryColor': '#ffffff', 'background': '#ffffff'}}}%%
flowchart TB
    n_sessionGraph("Session graph") --> n_transcript("Transcript history")
    n_sessionGraph --> n_operations("Operations")
    n_sessionGraph --> n_interactions("Interactions")
    n_sessionGraph --> n_runtime("Runtime lifecycle")
    n_sessionGraph --> n_capabilities("Capabilities / config")
    n_sessionGraph --> n_telemetry("Telemetry")

    classDef blue fill:#B4D2F0,stroke:#8BA7C0,color:#1f2937,stroke-width:1px;
    classDef green fill:#B4E6C8,stroke:#8FB9A2,color:#1f2937,stroke-width:1px;
    classDef purple fill:#D2BEF0,stroke:#A999C4,color:#1f2937,stroke-width:1px;
    classDef gray fill:#DCDCE1,stroke:#A6A6AD,color:#1f2937,stroke-width:1px;

    class n_sessionGraph purple;
    class n_operations,n_interactions green;
    class n_runtime,n_capabilities,n_telemetry blue;
    class n_transcript gray;

Loading

Start here

Order	Topic	Why it matters
1	Concepts landing page	Defines the vocabulary and ownership model
2	Session graph	Explains the one true product-state authority
3	Operations	Explains durable runtime work state
4	Interactions	Explains permissions, questions, and approvals
5	Reconnect and resume	Explains what state survives and how it restores

Architecture rule

The intended authority path is:

provider signal -> backend projection -> canonical session graph -> desktop stores -> UI selectors

Ownership cheatsheet

If you need to know...	Ask...
What is authoritative?	The session graph
What is the current runtime work item?	Operations
What is blocking user progress?	Interactions linked to operations
What should survive reopen/reconnect?	Canonical graph state, not local UI state

If code drifts from those docs, the fix should be to either:

• update code to match the documented model, or
• explicitly revise the concept docs in the same change.

Page boundary

Put it in the wiki when...	Put it in repo docs when...
It helps people navigate or understand the doc set	It defines architecture that code must obey
It is a portal, guide, or reading order	It is the canonical source of truth
It can point to versioned docs	It should evolve in the same PR as code