Architecture Concepts

Architecture Concepts

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

Core map

session graph
  |
  +--> transcript history
  +--> operations
  +--> interactions
  +--> runtime lifecycle
  +--> capabilities/config
  +--> telemetry

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.