# number7even/continuum architecture

> Architecture diagram of the GitHub repository number7even/continuum, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/number7even/continuum
- Repository: https://github.com/number7even/continuum

## Overview

1. **This is a monorepo with three major product surfaces**
   - The main platform is **Continuum**: an MCP-based persistence layer for AI assistants.
   - The repo also contains two separate Next.js apps: **`apps/amf`** and **`apps/console`**, plus a documentation site in **`apps/docs`**.
   - Shared engineering primitives live under **`packages/*`**; operational scripts, runbooks, and proofs live under **`docs/`** and **`scripts/`**.

2. **Continuum’s core runtime is split into packages, not a single app**
   - **`packages/core`** is the storage and state engine.
   - **`packages/mcp-server`** is the protocol boundary exposed to AI clients.
   - **`packages/cli`** is the local operator entrypoint.
   - **`packages/adapters/*`** ingest external sources into the core.
   - This separation is important: the MCP server is the front door, while the core owns persistence and domain state.

3. **The core engine centers on persistent project memory**
   - `packages/core` provides the actual data model and storage behavior: observations, todos, checkpoints, state snapshots, tenant boundaries, and hybrid storage.
   - The presence of SQLite/FTS5-related files and hybrid storage code indicates the core is optimized for **local indexed retrieval** and **timestamped state history**.
   - The core also includes embedding-related code, suggesting semantic retrieval alongside structured lookup.

4. **The MCP server is the main integration boundary with AI clients**
   - `packages/mcp-server` exposes tools, prompts, and resources over the MCP protocol.
   - Its tools include operations like getting state, fetching digests, searching docs, managing todos, and recording checkpoints.
   - The README describes this as the primary way Claude Code or another MCP-aware client talks to Continuum.
   - In architecture terms, this is the **runtime façade** that sits between the AI client and the core data store.

5. **Adapters are the ingestion layer for Continuum’s “five sources of truth”**
   - The adapters under `packages/adapters` connect the system to external content sources:
     - **docs**: project documentation and knowledge base content
     - **git**: repository history
     - **remote-git**: remote repository ingestion/digesting
     - **export**: export/parsing pipeline
   - These packages appear to normalize source-specific content into the core’s observation/state model.
   - Diagrammatically, they are upstream data feeders into the core index/state pipeline.

6. **The CLI is the local operator/control plane**
   - `packages/cli` is the user-facing command layer for initializing, starting, and serving the Continuum server.
   - It likely handles local setup, project bootstrapping, and convenience commands rather than domain logic.
   - In an architecture diagram, this belongs on the edge between developer terminal and the MCP server/core stack.

7. **Continuum’s data flow is: ingest → normalize → index → checkpoint → retrieve**
   - External sources enter through adapters or client hooks.
   - The core normalizes them into canonical observations and state records.
   - Retrieval is layered: compact search results first, then timeline context, then full records when needed.
   - Checkpoints are the durable output: immutable snapshots of project state used for session briefings and history reconstruction.

8. **`apps/console` is a separate internal web surface for search/chat/dashboard workflows**
   - It is a Next.js app with API routes for **chat**, **dashboard search**, and **dashboard session** operations.
   - The UI includes chat and dashboard pages, plus a dedicated memory search component.
   - This app looks like an operator/admin console for browsing and querying Continuum-like memory/session data, distinct from the MCP runtime itself.

9. **`apps/amf` is another independent product subsystem with a media-processing backend**
   - `apps/amf` is a Next.js app with API routes for **audio submit**, **audio status**, **audio webhook**, **auth**, **generate**, and **trends**.
   - It also has a substantial **worker** directory with Node and Python scripts for pipeline stages such as discovery, analysis, compose, render, transcribe, syndicate, and checkpoint-like processing.
   - The presence of Auphonic integration code and webhook handling suggests this subsystem orchestrates external audio production services and async job workflows.
   - This is architecturally separate from Continuum, but it lives in the same repo and likely shares design patterns around pipelines, state, and automation.

10. **`apps/amf/worker` is a job pipeline, not just utility code**
    - The worker contains multiple named stages and brandbook-driven content generation assets.
    - Files like `pipeline.mjs`, `event-loop.mjs`, `cron-trigger.mjs`, and `voice_pipeline.py` suggest a long-running or scheduled orchestration layer.
    - The worker likely receives jobs from the app/API side, performs multi-step processing, and publishes results back through webhooks or storage.

11. **`apps/docs` is the public documentation site**
    - This is an Astro-based docs site with content collections and product/architecture pages.
    - It is the outward-facing documentation layer, separate from the engineering docs under `/docs`.
    - In a system diagram, it is a read-only publishing surface for product and architecture material.

12. **The `/docs` directory is an engineering control plane, not just prose**
    - The root `docs/` directory contains architecture decisions, integration contracts, deployment runbooks, sprint notes, benchmarks, and proof artifacts.
    - Files like `ARCHITECTURE.md`, integration handshakes, and runbooks indicate this repo treats documentation as part of the system design.
    - For diagramming, this is the source of truth for boundaries, contracts, and deployment procedures.

13. **Operationally, the repo targets local dev, CI, Docker, and Fly.io**
    - Root files like `Dockerfile`, `fly.toml`, `.github/workflows/ci.yml`, and `entrypoint.sh` show the project is containerized and CI-driven.
    - There are deployment runbooks for self-hosted and Fly.io paths under `docs/`.
    - This matters because the Continuum MCP server is intended to run locally or as a lightweight service, while the apps can be deployed as standalone web services.

14. **There are also experimental/probe subsystems and verification scripts**
    - `dolt-probe/` and many `scripts/*` files are used for smoke tests, benchmarks, checkpoint validation, isolation testing, and integration probes.
    - These are supporting subsystems for proving behavior, measuring retrieval savings, and validating the architecture rather than end-user features.
    - They are useful to show in a diagram as “verification/experimentation” around the main runtime.

15. **Boundary summary for a diagram**
    - **AI clients** connect to **`packages/mcp-server`**.
    - The MCP server delegates to **`packages/core`** for state, retrieval, and checkpoint persistence.
    - **Adapters** feed external source data into the core.
    - **CLI/ops scripts** manage local setup, runs, and verification.
    - Separate application stacks live in **`apps/console`** and **`apps/amf`**, each with its own API/UI/worker boundaries.
    - Documentation and runbooks sit alongside the code as the architecture governance layer.

Main entry points: [`packages/core`](https://github.com/number7even/continuum/tree/main/packages/core) (Core), [`packages/mcp-server`](https://github.com/number7even/continuum/tree/main/packages/mcp-server) (MCP server), [`packages/adapters`](https://github.com/number7even/continuum/tree/main/packages/adapters) (Adapters), [`apps/amf`](https://github.com/number7even/continuum/tree/main/apps/amf) (AMF app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_apps["Apps"]
  node_apps_amf["AMF app<br/>nextjs app"]
  node_apps_amf_api["AMF API<br/>api routes"]
  node_apps_amf_worker["AMF worker<br/>job pipeline"]
  node_apps_console["Console app<br/>nextjs app"]
  node_apps_console_api["Console API<br/>api routes"]
  node_apps_docs["Docs site<br/>astro site"]
end

subgraph group_group_packages["Packages"]
  node_packages_core[("Core<br/>state engine")]
  node_packages_core_storage[("Storage<br/>sqlite+hybrid<br/>[storage-hybrid.ts]")]
  node_packages_core_state["State model<br/>domain model"]
  node_packages_core_embedder(("Embedder<br/>semantic retrieval<br/>[embedder.ts]"))
  node_packages_mcp["MCP server<br/>protocol façade"]
  node_packages_mcp_tools["Tools"]
  node_packages_mcp_resources["Resources"]
  node_packages_mcp_prompts["Prompts"]
  node_packages_cli["CLI"]
  node_packages_adapters["Adapters<br/>ingestion layer"]
  node_packages_adapters_docs["Docs adapter"]
  node_packages_adapters_git["Git adapter"]
  node_packages_adapters_remote_git["Remote git<br/>adapter"]
  node_packages_adapters_export["Export adapter"]
end

subgraph group_group_ops["Ops & Docs"]
  node_docs_root["Repo docs<br/>engineering docs"]
  node_scripts_root["Scripts"]
  node_dolt_probe["Dolt probe<br/>probe suite"]
end

node_repo_root["Continuum<br/>monorepo"]

node_repo_root -->|"AI client boundary"| node_packages_mcp
node_packages_mcp -->|"exposes"| node_packages_mcp_tools
node_packages_mcp -->|"exposes"| node_packages_mcp_resources
node_packages_mcp -->|"exposes"| node_packages_mcp_prompts
node_packages_mcp -->|"delegates to"| node_packages_core
node_packages_core -->|"persists via"| node_packages_core_storage
node_packages_core -->|"models"| node_packages_core_state
node_packages_core -->|"augments"| node_packages_core_embedder
node_packages_adapters -->|"includes"| node_packages_adapters_docs
node_packages_adapters -->|"includes"| node_packages_adapters_git
node_packages_adapters -->|"includes"| node_packages_adapters_remote_git
node_packages_adapters -->|"includes"| node_packages_adapters_export
node_packages_adapters_docs -->|"feeds"| node_packages_core
node_packages_adapters_git -->|"feeds"| node_packages_core
node_packages_adapters_remote_git -->|"feeds"| node_packages_core
node_packages_adapters_export -->|"feeds"| node_packages_core
node_packages_cli -->|"starts/serves"| node_packages_mcp
node_docs_root -.->|"documents"| node_packages_mcp
node_docs_root -.->|"documents"| node_packages_core
node_scripts_root -.->|"verifies"| node_packages_core
node_scripts_root -.->|"probes"| node_packages_mcp
node_dolt_probe -.->|"probes"| node_packages_core
node_apps_console -->|"contains"| node_apps_console_api
node_apps_console_api -->|"queries"| node_packages_mcp
node_apps_amf -->|"contains"| node_apps_amf_api
node_apps_amf -->|"orchestrates"| node_apps_amf_worker
node_apps_amf_api -->|"enqueues"| node_apps_amf_worker
node_apps_docs -->|"publishes"| node_docs_root
node_repo_root -->|"hosts"| node_apps_amf
node_repo_root -->|"hosts"| node_apps_console
node_repo_root -->|"hosts"| node_apps_docs
node_repo_root -->|"hosts"| node_packages_adapters
node_repo_root -->|"hosts"| node_packages_cli
node_repo_root -->|"hosts"| node_packages_core
node_repo_root -->|"hosts"| node_packages_mcp

click node_apps_amf "https://github.com/number7even/continuum/tree/main/apps/amf"
click node_apps_amf_api "https://github.com/number7even/continuum/tree/main/apps/amf/app/api"
click node_apps_amf_worker "https://github.com/number7even/continuum/tree/main/apps/amf/worker"
click node_apps_console "https://github.com/number7even/continuum/tree/main/apps/console"
click node_apps_console_api "https://github.com/number7even/continuum/tree/main/apps/console/app/api"
click node_apps_docs "https://github.com/number7even/continuum/tree/main/apps/docs"
click node_packages_core "https://github.com/number7even/continuum/tree/main/packages/core"
click node_packages_core_storage "https://github.com/number7even/continuum/blob/main/packages/core/src/storage-hybrid.ts"
click node_packages_core_state "https://github.com/number7even/continuum/tree/main/packages/core/src"
click node_packages_core_embedder "https://github.com/number7even/continuum/blob/main/packages/core/src/embedder.ts"
click node_packages_mcp "https://github.com/number7even/continuum/tree/main/packages/mcp-server"
click node_packages_mcp_tools "https://github.com/number7even/continuum/tree/main/packages/mcp-server/src/tools"
click node_packages_mcp_resources "https://github.com/number7even/continuum/tree/main/packages/mcp-server/src/resources"
click node_packages_mcp_prompts "https://github.com/number7even/continuum/tree/main/packages/mcp-server/src/prompts"
click node_packages_cli "https://github.com/number7even/continuum/tree/main/packages/cli"
click node_packages_adapters "https://github.com/number7even/continuum/tree/main/packages/adapters"
click node_packages_adapters_docs "https://github.com/number7even/continuum/tree/main/packages/adapters/docs"
click node_packages_adapters_git "https://github.com/number7even/continuum/tree/main/packages/adapters/git"
click node_packages_adapters_remote_git "https://github.com/number7even/continuum/tree/main/packages/adapters/remote-git"
click node_packages_adapters_export "https://github.com/number7even/continuum/tree/main/packages/adapters/export"
click node_docs_root "https://github.com/number7even/continuum/tree/main/docs"
click node_scripts_root "https://github.com/number7even/continuum/tree/main/scripts"
click node_dolt_probe "https://github.com/number7even/continuum/tree/main/dolt-probe"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_apps_amf,node_apps_amf_api,node_apps_amf_worker,node_apps_console,node_apps_console_api,node_apps_docs toneBlue
class node_packages_core,node_packages_core_storage,node_packages_core_state,node_packages_core_embedder,node_packages_mcp,node_packages_mcp_tools,node_packages_mcp_resources,node_packages_mcp_prompts,node_packages_cli,node_packages_adapters,node_packages_adapters_docs,node_packages_adapters_git,node_packages_adapters_remote_git,node_packages_adapters_export toneAmber
class node_docs_root,node_scripts_root,node_dolt_probe toneMint
class node_repo_root toneNeutral
```

## Components

### Apps

Standalone application surfaces in the monorepo.

- [AMF app](https://github.com/number7even/continuum/tree/main/apps/amf): nextjs app · Independent media-processing product surface with API routes and UI. · `apps/amf`
- [AMF API](https://github.com/number7even/continuum/tree/main/apps/amf/app/api): api routes · Audio submit/status/webhook, auth, generation, and trends endpoints. · `apps/amf/app/api`
- [AMF worker](https://github.com/number7even/continuum/tree/main/apps/amf/worker): job pipeline · Long-running orchestration and stage-based processing pipeline. · `apps/amf/worker`
- [Console app](https://github.com/number7even/continuum/tree/main/apps/console): nextjs app · Internal operator console for chat, dashboard search, and session workflows. · `apps/console`
- [Console API](https://github.com/number7even/continuum/tree/main/apps/console/app/api): api routes · Chat, dashboard search, and dashboard session endpoints. · `apps/console/app/api`
- [Docs site](https://github.com/number7even/continuum/tree/main/apps/docs): astro site · Public documentation and product publishing surface. · `apps/docs`

### Packages

Shared runtime and product building blocks for Continuum and related systems.

- [Core](https://github.com/number7even/continuum/tree/main/packages/core): state engine · Persistence and domain state engine for observations, todos, checkpoints, and hybrid storage. · `packages/core`
- [Storage](https://github.com/number7even/continuum/blob/main/packages/core/src/storage-hybrid.ts): sqlite+hybrid · SQLite/FTS5-backed and hybrid storage implementations for indexed retrieval and history. · `packages/core/src/storage-hybrid.ts`
- [State model](https://github.com/number7even/continuum/tree/main/packages/core/src): domain model · Observations, todos, checkpoints, tenants, and state snapshot behavior. · `packages/core/src`
- [Embedder](https://github.com/number7even/continuum/blob/main/packages/core/src/embedder.ts): semantic retrieval · Embedding-related code supporting semantic lookup alongside structured state queries. · `packages/core/src/embedder.ts`
- [MCP server](https://github.com/number7even/continuum/tree/main/packages/mcp-server): protocol façade · Primary runtime boundary for AI clients; exposes tools, prompts, and resources over MCP. · `packages/mcp-server`
- [Tools](https://github.com/number7even/continuum/tree/main/packages/mcp-server/src/tools): mcp tools · Operations for state, digests, docs search, todos, checkpoints, and timeline access. · `packages/mcp-server/src/tools`
- [Resources](https://github.com/number7even/continuum/tree/main/packages/mcp-server/src/resources): mcp resources · Session briefing, current state, open todos, and latest digest resources. · `packages/mcp-server/src/resources`
- [Prompts](https://github.com/number7even/continuum/tree/main/packages/mcp-server/src/prompts): mcp prompts · Session and citation prompts used by MCP-aware clients. · `packages/mcp-server/src/prompts`
- [CLI](https://github.com/number7even/continuum/tree/main/packages/cli): operator cli · Local command entrypoint for initialization, serving, and operator workflows. · `packages/cli`
- [Adapters](https://github.com/number7even/continuum/tree/main/packages/adapters): ingestion layer · Source-specific ingestion packages that normalize external data into core state. · `packages/adapters`
- [Docs adapter](https://github.com/number7even/continuum/tree/main/packages/adapters/docs): adapter · Ingests project documentation and knowledge base content. · `packages/adapters/docs`
- [Git adapter](https://github.com/number7even/continuum/tree/main/packages/adapters/git): adapter · Ingests repository history and git-derived source material. · `packages/adapters/git`
- [Remote git](https://github.com/number7even/continuum/tree/main/packages/adapters/remote-git): adapter · Remote repository ingest and digest pipeline. · `packages/adapters/remote-git`
- [Export adapter](https://github.com/number7even/continuum/tree/main/packages/adapters/export): adapter · Export and parsing pipeline for normalized content ingress. · `packages/adapters/export`

### Ops & Docs

Architecture governance, runbooks, proofs, scripts, and deployment support.

- [Repo docs](https://github.com/number7even/continuum/tree/main/docs): engineering docs · Architecture, contracts, runbooks, benchmarks, proofs, and governance material. · `docs`
- [Scripts](https://github.com/number7even/continuum/tree/main/scripts): ops scripts · Smoke tests, benchmarks, probes, checkpoint generation, and verification utilities. · `scripts`
- [Dolt probe](https://github.com/number7even/continuum/tree/main/dolt-probe): probe suite · Containerized probe and scenario runner for validation experiments. · `dolt-probe`

### Other components

- **Continuum**: monorepo · Top-level repository coordinating multiple products and shared packages.

## Connections

- Continuum → MCP server: AI client boundary · AI clients enter the Continuum runtime through the MCP server.
- MCP server → Tools: exposes · Server publishes tool operations to clients.
- MCP server → Resources: exposes · Server publishes read-only resources for context and state.
- MCP server → Prompts: exposes · Server provides reusable prompts for MCP workflows.
- MCP server → Core: delegates to · Protocol layer resolves state and persistence through the core engine.
- Core → Storage: persists via · Core uses hybrid and SQLite-backed storage for indexed state and history.
- Core → State model: models · Core defines canonical observations, todos, checkpoints, and tenants.
- Core → Embedder: augments · Core adds semantic retrieval support through embeddings.
- Adapters → Docs adapter: includes · Docs ingestion is one adapter family.
- Adapters → Git adapter: includes · Git ingestion is one adapter family.
- Adapters → Remote git: includes · Remote git ingestion is one adapter family.
- Adapters → Export adapter: includes · Export/parsing is one adapter family.
- Docs adapter → Core: feeds · Normalized documentation content enters core state.
- Git adapter → Core: feeds · Repository history is normalized into core observations and snapshots.
- Remote git → Core: feeds · Remote repository digests flow into core ingestion.
- Export adapter → Core: feeds · Parsed export artifacts are normalized into core state.
- CLI → MCP server: starts/serves · CLI provides the local operator entrypoint for the MCP runtime.
- Repo docs → MCP server: documents · Runbooks and architecture docs govern the MCP surface.
- Repo docs → Core: documents · Architecture and contracts describe the persistence engine.
- Scripts → Core: verifies · Benchmarks and probes validate storage, retrieval, and isolation.
- Scripts → MCP server: probes · Smoke tests and probes exercise the server boundary.
- Dolt probe → Core: probes · Experimental validation suite targets core behavior.
- Console app → Console API: contains · Console UI is backed by its own API routes.
- Console API → MCP server: queries · Console workflows likely read through the Continuum runtime boundary.
- AMF app → AMF API: contains · AMF UI is backed by its own API routes.
- AMF app → AMF worker: orchestrates · AMF app submits work to the long-running worker pipeline.
- AMF API → AMF worker: enqueues · API endpoints trigger async processing and callbacks.
- Docs site → Repo docs: publishes · Public docs site mirrors selected product and architecture content.
- Continuum → AMF app: hosts · Repository contains the AMF product surface.
- Continuum → Console app: hosts · Repository contains the console product surface.
- Continuum → Docs site: hosts · Repository contains the public documentation site.
- Continuum → Adapters: hosts · Repository contains the shared ingestion packages.
- Continuum → CLI: hosts · Repository contains the operator CLI package.
- Continuum → Core: hosts · Repository contains the core persistence engine.
- Continuum → MCP server: hosts · Repository contains the MCP server package.
