# natebjones-projects/ob1 architecture

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

- Interactive diagram: https://gitdiagram.com/natebjones-projects/ob1
- Repository: https://github.com/natebjones-projects/ob1

## Overview

1. **What this repo is**
   Open Brain is a multi-surface “personal memory” platform, not a single app. The core idea is one shared database-backed brain that multiple AI clients, capture sources, dashboards, and workflows can all read from and write to.

2. **Canonical data layer**
   The architectural center is PostgreSQL/Supabase with vector search support. The `schemas/` directory defines the durable storage model, with `thoughts` as the base concept and additional sidecar schemas such as agent memory, provenance, audit, search, deduplication, and workflow status.

3. **Data lifecycle**
   The main flow is: capture/import → enrich/embed/classify → store in the database → search/retrieve → review/update/delete. Many recipes and integrations exist to move data into that loop, while dashboards and agent tools sit on top of it for human and AI interaction.

4. **Agent and protocol boundary**
   MCP is the primary access boundary for AI clients. The repo includes a standalone `server/` MCP server, a `primitives/remote-mcp/` concept, and several integrations that expose memory actions like recall, writeback, update, delete, and inspection through standardized tool interfaces.

5. **User-facing dashboards**
   The `dashboards/` folder contains deployable frontends. The main ones are a Next.js dashboard and a SvelteKit dashboard, both centered on browsing thoughts, search, ingest, audit, and memory operations. The Next.js version is more feature-rich and includes API routes, middleware/auth, kanban, settings, and agent-memory views.

6. **Backend surface in the dashboards**
   The dashboard apps are not just static UIs; they also host server routes for operations like ingest, search, audit, duplicates resolution, restricted toggles, logout, and thought connections. That makes each dashboard a thin app shell plus a server-side API layer that talks to the core brain.

7. **Ingestion and capture integrations**
   `integrations/` holds runtime adapters that push external signals into Open Brain. These include Slack/Discord capture, agent-memory APIs, entity extraction, consolidation workers, and deployment-specific adapters like Kubernetes and OpenClaw plugin support. These are the main entry points for live data.

8. **Recipes as operational workflows**
   `recipes/` contains one-off or repeatable pipelines for importing and transforming external data: Gmail, ChatGPT, Obsidian, X/Twitter, Instagram, Google Activity, Grok, Readwise, Blogger, and more. Many recipes also include SQL migrations, backfills, or smoke tests, so they represent full data-engineering workflows rather than just docs.

9. **Extensions as productized brain modules**
   `extensions/` are the curated, user-facing “learning path” modules such as household knowledge, home maintenance, family calendar, meal planning, professional CRM, and job hunt. These are larger app-level subsystems intended to compound on the shared brain data model.

10. **Skills and prompts as non-runtime assets**
   `skills/` is a library of reusable agent instructions, and `resources/` and `docs/` contain companion content, walkthroughs, diagrams, and setup material. These are not runtime services; they are part of the product architecture because they shape how agents and humans use the system.

11. **Primitives as cross-cutting patterns**
   `primitives/` collects reusable architectural patterns such as deployment, remote MCP connectivity, RLS, troubleshooting, and shared MCP access. In the repo structure, primitives sit below extensions and recipes as shared building blocks used across multiple workflows.

12. **Governance and automation**
   GitHub workflows handle review automation, triage, labeling, announcements, README updates, and contributor onboarding. This means repository governance is part of the architecture: contributions are machine-checked before human review, which matters because the repo contains many independently maintained modules.

13. **Technology mix matters**
   The repo is intentionally polyglot: Next.js/TypeScript, SvelteKit, Deno edge functions, SQL migrations, shell scripts, Python utilities, and some Python plugin code. The stack varies by subsystem, but the boundary is consistent: all roads lead back to the shared brain database and its MCP-accessible tools.

14. **How to draw it**
   A good diagram would show a central database brain, surrounded by:
   - AI clients connected through MCP/server tools
   - capture/import integrations feeding the brain
   - dashboards reading and modifying the same data
   - recipes/skills/docs as operational and instructional layers
   - GitHub automation governing changes and publishing

Main entry points: [`schemas`](https://github.com/natebjones-projects/ob1/tree/main/schemas) (Brain DB), [`server/index.ts`](https://github.com/natebjones-projects/ob1/blob/main/server/index.ts) (MCP Server), [`.github/workflows`](https://github.com/natebjones-projects/ob1/blob/main/.github/workflows) (GitHub automation), [`dashboards/open-brain-dashboard-next`](https://github.com/natebjones-projects/ob1/tree/main/dashboards/open-brain-dashboard-next) (Next dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core brain"]
  node_brain_db[("Brain DB<br/>postgres/supabase memory store")]
  node_schema_thoughts["Thoughts<br/>base schema<br/>[schema.sql]"]
  node_schema_sidecars["Sidecars<br/>memory metadata schemas"]
  node_schema_search["Search<br/>retrieval schema<br/>[schema.sql]"]
  node_schema_provenance["Provenance<br/>trace schema<br/>[schema.sql]"]
end

subgraph group_clients["Clients and surfaces"]
  node_mcp_server["MCP Server<br/>AI tool boundary<br/>[index.ts]"]
  node_dashboard_next["Next dashboard<br/>next.js app"]
  node_dashboard_svelte["Svelte dashboard<br/>sveltekit app"]
  node_dashboard_pro["Pro dashboard<br/>next.js app"]
end

subgraph group_ingest["Ingestion and processing"]
  node_integrations_capture["Capture adapters<br/>runtime adapters"]
  node_integrations_workers["Workers<br/>enrichment pipeline"]
  node_integrations_mcp["MCP integrations<br/>tool plugins"]
  node_recipes_imports["Import recipes<br/>data workflows"]
  node_recipes_ops["Ops recipes<br/>maintenance workflows"]
end

subgraph group_product["Product modules"]
  node_extensions_apps["Extensions<br/>product modules"]
  node_skills_lib["Skills<br/>agent instruction library"]
  node_docs_resources["Docs & assets<br/>product content"]
  node_primitives_lib["Primitives<br/>shared patterns"]
end

subgraph group_governance["Governance"]
  node_github_automation["GitHub automation<br/>repo governance<br/>[workflows]"]
  node_repo_scripts["Repo scripts<br/>maintenance automation"]
end

node_schema_thoughts -->|"defines"| node_brain_db
node_schema_sidecars -->|"extends"| node_brain_db
node_schema_search -->|"supports"| node_brain_db
node_schema_provenance -->|"tracks"| node_brain_db
node_mcp_server -->|"reads/writes"| node_brain_db
node_dashboard_next -->|"queries"| node_brain_db
node_dashboard_svelte -->|"queries"| node_brain_db
node_dashboard_pro -->|"queries"| node_brain_db
node_integrations_capture -->|"ingests"| node_brain_db
node_integrations_workers -->|"enriches"| node_brain_db
node_integrations_mcp -->|"exposes"| node_mcp_server
node_recipes_imports -->|"imports"| node_brain_db
node_recipes_ops -->|"maintains"| node_brain_db
node_extensions_apps -->|"builds on"| node_brain_db
node_skills_lib -->|"guides"| node_mcp_server
node_docs_resources -->|"documents"| node_skills_lib
node_primitives_lib -->|"reuses"| node_mcp_server
node_github_automation -->|"governs"| node_extensions_apps
node_github_automation -->|"governs"| node_recipes_imports
node_repo_scripts -->|"supports"| node_github_automation
node_dashboard_next -.->|"optionally calls"| node_mcp_server
node_dashboard_pro -.->|"optionally calls"| node_mcp_server

click node_brain_db "https://github.com/natebjones-projects/ob1/tree/main/schemas"
click node_schema_thoughts "https://github.com/natebjones-projects/ob1/blob/main/schemas/enhanced-thoughts/schema.sql"
click node_schema_sidecars "https://github.com/natebjones-projects/ob1/tree/main/schemas"
click node_schema_search "https://github.com/natebjones-projects/ob1/blob/main/schemas/text-search-trgm/schema.sql"
click node_schema_provenance "https://github.com/natebjones-projects/ob1/blob/main/schemas/provenance-chains/schema.sql"
click node_mcp_server "https://github.com/natebjones-projects/ob1/blob/main/server/index.ts"
click node_dashboard_next "https://github.com/natebjones-projects/ob1/tree/main/dashboards/open-brain-dashboard-next"
click node_dashboard_svelte "https://github.com/natebjones-projects/ob1/tree/main/dashboards/open-brain-dashboard"
click node_dashboard_pro "https://github.com/natebjones-projects/ob1/tree/main/dashboards/open-brain-dashboard-pro"
click node_integrations_capture "https://github.com/natebjones-projects/ob1/tree/main/integrations"
click node_integrations_workers "https://github.com/natebjones-projects/ob1/tree/main/integrations/entity-extraction-worker"
click node_integrations_mcp "https://github.com/natebjones-projects/ob1/tree/main/integrations/openclaw-agent-memory"
click node_recipes_imports "https://github.com/natebjones-projects/ob1/tree/main/recipes"
click node_recipes_ops "https://github.com/natebjones-projects/ob1/tree/main/recipes/brain-backup"
click node_extensions_apps "https://github.com/natebjones-projects/ob1/tree/main/extensions"
click node_skills_lib "https://github.com/natebjones-projects/ob1/tree/main/skills"
click node_docs_resources "https://github.com/natebjones-projects/ob1/tree/main/docs"
click node_primitives_lib "https://github.com/natebjones-projects/ob1/tree/main/primitives"
click node_github_automation "https://github.com/natebjones-projects/ob1/blob/main/.github/workflows"
click node_repo_scripts "https://github.com/natebjones-projects/ob1/blob/main/scripts/update-readme-contributions.mjs"

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_brain_db,node_schema_thoughts,node_schema_sidecars,node_schema_search,node_schema_provenance toneBlue
class node_mcp_server,node_dashboard_next,node_dashboard_svelte,node_dashboard_pro toneAmber
class node_integrations_capture,node_integrations_workers,node_integrations_mcp,node_recipes_imports,node_recipes_ops toneMint
class node_extensions_apps,node_skills_lib,node_docs_resources,node_primitives_lib toneRose
class node_github_automation,node_repo_scripts toneIndigo
```

## Components

### Core brain

Shared database-backed memory model and durable schemas

- [Brain DB](https://github.com/natebjones-projects/ob1/tree/main/schemas): postgres/supabase memory store · Canonical PostgreSQL/Supabase brain with vector search and shared durable state · `schemas`
- [Thoughts](https://github.com/natebjones-projects/ob1/blob/main/schemas/enhanced-thoughts/schema.sql): base schema · Primary thought record and core memory entity · `schemas/enhanced-thoughts/schema.sql`
- [Sidecars](https://github.com/natebjones-projects/ob1/tree/main/schemas): memory metadata schemas · Agent memory, provenance, audit, search, deduplication, and workflow status layers · `schemas`
- [Search](https://github.com/natebjones-projects/ob1/blob/main/schemas/text-search-trgm/schema.sql): retrieval schema · Text and vector retrieval support for recall and discovery · `schemas/text-search-trgm/schema.sql`
- [Provenance](https://github.com/natebjones-projects/ob1/blob/main/schemas/provenance-chains/schema.sql): trace schema · Source tracking and lineage for captured and transformed memories · `schemas/provenance-chains/schema.sql`

### Clients and surfaces

MCP access and user-facing dashboards

- [MCP Server](https://github.com/natebjones-projects/ob1/blob/main/server/index.ts): AI tool boundary · Standalone MCP access layer for recall, writeback, update, delete, and inspection · `server/index.ts`
- [Next dashboard](https://github.com/natebjones-projects/ob1/tree/main/dashboards/open-brain-dashboard-next): next.js app · Feature-rich dashboard with API routes, auth, ingest, audit, duplicates, kanban, and agent-memory views · `dashboards/open-brain-dashboard-next`
- [Svelte dashboard](https://github.com/natebjones-projects/ob1/tree/main/dashboards/open-brain-dashboard): sveltekit app · Dashboard surface with MCP route and shared memory browsing/editing views · `dashboards/open-brain-dashboard`
- [Pro dashboard](https://github.com/natebjones-projects/ob1/tree/main/dashboards/open-brain-dashboard-pro): next.js app · Alternate dashboard app with settings and server-side memory operations · `dashboards/open-brain-dashboard-pro`

### Ingestion and processing

Adapters, importers, and enrichment workflows that write into the brain

- [Capture adapters](https://github.com/natebjones-projects/ob1/tree/main/integrations): runtime adapters · Slack, Discord, Telegram, Readwise, and similar entry points for external signals · `integrations`
- [Workers](https://github.com/natebjones-projects/ob1/tree/main/integrations/entity-extraction-worker): enrichment pipeline · Entity extraction, consolidation, and smart-ingest processing for incoming data · `integrations/entity-extraction-worker`
- [MCP integrations](https://github.com/natebjones-projects/ob1/tree/main/integrations/openclaw-agent-memory): tool plugins · Memory action adapters such as update, delete, agent-memory API, and OpenClaw plugin support · `integrations/openclaw-agent-memory`
- [Import recipes](https://github.com/natebjones-projects/ob1/tree/main/recipes): data workflows · One-off and repeatable import pipelines for Gmail, ChatGPT, Obsidian, X, Instagram, Readwise, and more · `recipes`
- [Ops recipes](https://github.com/natebjones-projects/ob1/tree/main/recipes/brain-backup): maintenance workflows · Backups, smoke tests, health checks, deduplication, provenance, and lifecycle automation · `recipes/brain-backup`

### Product modules

Curated extensions, skills, docs, and reusable primitives

- [Extensions](https://github.com/natebjones-projects/ob1/tree/main/extensions): product modules · Curated brain apps such as household knowledge, family calendar, CRM, meal planning, and job hunt · `extensions`
- [Skills](https://github.com/natebjones-projects/ob1/tree/main/skills): agent instruction library · Reusable prompts and operating skills that shape how agents use the brain · `skills`
- [Docs & assets](https://github.com/natebjones-projects/ob1/tree/main/docs): product content · Guides, walkthroughs, diagrams, and companion assets for using and understanding the system · `docs`
- [Primitives](https://github.com/natebjones-projects/ob1/tree/main/primitives): shared patterns · Reusable patterns for remote MCP, RLS, deployment, troubleshooting, and shared access · `primitives`

### Governance

Repository automation and contribution workflows

- [GitHub automation](https://github.com/natebjones-projects/ob1/blob/main/.github/workflows): repo governance · Workflows for triage, review, release drafting, contributor onboarding, and README updates · `.github/workflows`
- [Repo scripts](https://github.com/natebjones-projects/ob1/blob/main/scripts/update-readme-contributions.mjs): maintenance automation · Repository-level automation such as contribution updates and administrative scripts · `scripts/update-readme-contributions.mjs`

## Connections

- Thoughts → Brain DB: defines · Defines the core persisted memory entity
- Sidecars → Brain DB: extends · Adds agent memory, audit, dedup, and workflow metadata
- Search → Brain DB: supports · Implements retrieval and search behavior on the shared store
- Provenance → Brain DB: tracks · Attaches lineage and source history to memories
- MCP Server → Brain DB: reads/writes · Primary AI tool boundary for memory actions
- Next dashboard → Brain DB: queries · Dashboard UI and server routes operate on the same memory store
- Svelte dashboard → Brain DB: queries · SvelteKit dashboard reads and writes shared brain data
- Pro dashboard → Brain DB: queries · Alternate dashboard surface backed by the canonical database
- Capture adapters → Brain DB: ingests · External signals are captured into the brain
- Workers → Brain DB: enriches · Workers classify, extract entities, and consolidate records
- MCP integrations → MCP Server: exposes · Standardized tool adapters sit on the MCP boundary
- Import recipes → Brain DB: imports · Bulk import and migration recipes land data in the shared model
- Ops recipes → Brain DB: maintains · Operational workflows monitor and repair the memory system
- Extensions → Brain DB: builds on · Productized modules compose on top of the shared brain
- Skills → MCP Server: guides · Agent instructions shape how tools are used
- Docs & assets → Skills: documents · Walkthroughs and assets explain workflows and agent behavior
- Primitives → MCP Server: reuses · Common access and deployment patterns support multiple workflows
- GitHub automation → Extensions: governs · Automation reviews and labels contributions across modules
- GitHub automation → Import recipes: governs · Automation helps manage workflow submissions and updates
- Repo scripts → GitHub automation: supports · Repository scripts back contributor and content maintenance
- Next dashboard → MCP Server: optionally calls · Dashboard backend routes can proxy memory operations through standardized tools
- Pro dashboard → MCP Server: optionally calls · Pro dashboard can also use the MCP-facing memory boundary