# starmynd-org/infinite-brain-os architecture

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

- Interactive diagram: https://gitdiagram.com/starmynd-org/infinite-brain-os
- Repository: https://github.com/starmynd-org/infinite-brain-os

## Overview

1. **What this repo is**
   Infinite Brain OS is a git-backed operating system for AI-assisted business operations. The runtime is not a server or database; it is a file-reading agent (Claude Code, Codex, or similar) acting on plain Markdown/YAML in the repository.

2. **Core architectural boundary: `_system/`**
   `_system/` is the contract layer. It contains schemas, registry rules, validation scripts, load-order policies, routing maps, and enforcement tiers. This is the “source of truth” for what node types exist, how they relate, and what must validate before the repo is considered healthy.

3. **Knowledge as a namespace graph**
   `knowledge/` is the main knowledge plane and is organized by namespace, not by application feature. Namespaces such as `ai-architecture`, `personal-operator`, and `emberline-studio` each contain canon, concepts, decisions, playbooks, support, and synthesis. The architecture emphasizes “namespace-first” retrieval and explicit promotion from working knowledge to operator-approved canon.

4. **Canon vs. support vs. synthesis**
   The repo distinguishes stable, approved doctrine from supporting material and synthesized guidance. Canon lives inside each namespace’s `canon/` folder; support and synthesis are secondary layers. This split matters because agents are expected to draft and operate from lower-trust layers while canon requires operator approval and verification metadata.

5. **Executable primitives in `entities/`**
   `entities/` holds the typed operational building blocks: agents, commands, skills, rules, and related reusable assets. These are not code in the traditional sense; they are structured operational definitions that agents compose into behavior. The duplicate presence of `.claude/` and `.codex/` mirrors these entities into agent-specific runtime adapters.

6. **Work orchestration: `workflows/`, `projects/`, `departments/`, `swarms/`**
   - `workflows/` contains reasoning and execution loops, including review, onboarding, correction, and weekly/monthly cycles.
   - `projects/` is the work container layer, with one `PLAN.md` per project and inline task tracking.
   - `departments/` assembles entities into operating lanes with charters and indexes.
   - `swarms/` packages multi-agent sprint execution.  
   Together these represent the planning-to-execution ladder: doctrine informs workflows, workflows shape projects, projects are assembled into departments, and swarms handle bounded burst work.

7. **Inbound flow: `intake/`**
   `intake/` is the ingress system for external items such as repo sources, web items, research items, and social/media items. It includes playbooks, routing rules, schemas, and processed receipts. The flow is: capture input → route it to a destination/namespace/department → record the routing decision → store a processed receipt. Residual ambiguity is explicitly tracked rather than hidden.

8. **Operational data boundaries: `data/`, `memory/`, `outputs/`**
   These folders separate different kinds of persisted artifacts:
   - `data/` stores pointers to live numbers, not the numbers themselves.
   - `memory/` stores reviewed lessons and durable learnings.
   - `outputs/` stores produced artifacts with lineage.
   This boundary is important: the repo avoids acting as a live database and instead stores references, lessons, and deliverables with provenance.

9. **Session audit trail: `sessions/`**
   `sessions/` is the work ledger for AI activity. It includes active, closed, logs, reviews, and templates for session records and closeouts. This makes AI work traceable and reviewable, and it supports the repo’s governance model around closure, accountability, and freshness.

10. **Automation and deterministic execution**
   `automations/n8n/` is the main deterministic workflow area and shows that the repo supports machine-executed processes alongside agentic reasoning. The split is clear: agentic workflows live in `workflows/`, while deterministic automations are represented as n8n JSON plus companion docs. That separation is a key architectural boundary.

11. **Runtime adapters and editor surfaces**
   `.claude/` and `.codex/` contain runtime-specific shims: agents, commands, skills, hooks, and settings tailored to each AI toolchain. `.obsidian/` config makes the repo usable as an Obsidian vault. These surfaces do not define the architecture, but they shape how humans and agents enter and operate the graph.

12. **Validation and governance**
   The repository is held together by validation scripts in `_system/checks/` and `validate.sh`, plus repo-level rules for linting, session status, output linkage, and adapter sync. The architectural assumption is that the repo stays correct through continuous contract checks, not through a database or centralized service.

13. **Worked-example pattern**
   The `knowledge/_examples/` and `departments/example-studio-ops/` content form a complete reference implementation. The README’s Emberline Studio walkthrough demonstrates the intended data flow end to end: canon informs rules, rules inform skills, skills inform agents, workflows produce outputs, and departments assemble the whole operating lane.

14. **What to draw in an architecture diagram**
   The diagram should center on `_system/` as the contract spine, `knowledge/` as the retrieval and doctrine graph, `entities/` as the executable primitive layer, and `workflows/projects/departments` as the orchestration layers. Around that core, show intake as the inbound funnel, sessions as the audit trail, outputs/memory/data as distinct persistence classes, and `.claude/.codex/.obsidian` as runtime/editor access surfaces.

Main entry points: [`knowledge/ai-architecture`](https://github.com/starmynd-org/infinite-brain-os/tree/main/knowledge/ai-architecture) (AI arch), [`entities`](https://github.com/starmynd-org/infinite-brain-os/tree/main/entities) (Entities), [`_system`](https://github.com/starmynd-org/infinite-brain-os/tree/main/_system) (_system), [`sessions`](https://github.com/starmynd-org/infinite-brain-os/tree/main/sessions) (Sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contracts["Contracts"]
  node_system["_system<br/>contract spine"]
  node_system_checks["Checks<br/>validation"]
  node_system_namespaces["Namespace rules<br/>registry"]
end

subgraph group_knowledge["Knowledge"]
  node_knowledge_ai["AI arch<br/>namespace"]
  node_knowledge_personal["Personal op<br/>namespace"]
  node_knowledge_examples["Examples<br/>reference set"]
  node_knowledge_emberline["Emberline<br/>namespace"]
end

subgraph group_execution["Execution"]
  node_entities["Entities<br/>primitive layer"]
  node_workflows["Workflows<br/>orchestration"]
  node_projects["Projects<br/>work container"]
  node_departments["Departments<br/>operating lane"]
  node_swarms["Swarms<br/>multi-agent sprint"]
end

subgraph group_ingress["Ingress"]
  node_intake["Intake<br/>ingress flow"]
end

subgraph group_audit["Audit"]
  node_sessions["Sessions<br/>ledger"]
end

subgraph group_persistence["Persistence"]
  node_data[("Data<br/>live pointers")]
  node_memory[("Memory<br/>durable lessons")]
  node_outputs["Outputs<br/>deliverables"]
end

subgraph group_surfaces["Surfaces"]
  node_claude["Claude<br/>runtime surface<br/>[.claude]"]
  node_codex["Codex<br/>runtime surface<br/>[.codex]"]
  node_obsidian["Obsidian<br/>editor surface<br/>[.obsidian]"]
end

subgraph group_automation["Automation"]
  node_n8n["n8n<br/>deterministic automation"]
end

node_system -->|"validated by"| node_system_checks
node_system -->|"governs"| node_system_namespaces
node_system -->|"defines"| node_knowledge_ai
node_system -->|"types"| node_entities
node_knowledge_ai -->|"frames"| node_knowledge_personal
node_knowledge_ai -->|"demonstrates"| node_knowledge_examples
node_knowledge_ai -->|"informs"| node_workflows
node_knowledge_emberline -->|"exemplifies"| node_departments
node_entities -->|"composed by"| node_workflows
node_entities -->|"assembled into"| node_departments
node_workflows -->|"drives"| node_projects
node_projects -->|"spawns"| node_swarms
node_intake -->|"routes to"| node_knowledge_ai
node_intake -->|"routes to"| node_departments
node_intake -->|"records"| node_sessions
node_sessions -->|"closes into"| node_outputs
node_sessions -->|"distills"| node_memory
node_data -->|"references"| node_knowledge_ai
node_outputs -.->|"feeds"| node_knowledge_ai
node_claude -->|"hosts"| node_entities
node_codex -->|"hosts"| node_entities
node_obsidian -->|"browses"| node_knowledge_examples
node_n8n -->|"automates"| node_workflows
node_system_checks -.->|"syncs"| node_claude
node_system_checks -.->|"checks"| node_sessions

click node_system "https://github.com/starmynd-org/infinite-brain-os/tree/main/_system"
click node_system_checks "https://github.com/starmynd-org/infinite-brain-os/tree/main/_system/checks"
click node_system_namespaces "https://github.com/starmynd-org/infinite-brain-os/tree/main/_system/namespaces"
click node_knowledge_ai "https://github.com/starmynd-org/infinite-brain-os/tree/main/knowledge/ai-architecture"
click node_knowledge_personal "https://github.com/starmynd-org/infinite-brain-os/tree/main/knowledge/personal-operator"
click node_knowledge_examples "https://github.com/starmynd-org/infinite-brain-os/tree/main/knowledge/_examples"
click node_knowledge_emberline "https://github.com/starmynd-org/infinite-brain-os/tree/main/knowledge/emberline-studio"
click node_entities "https://github.com/starmynd-org/infinite-brain-os/tree/main/entities"
click node_workflows "https://github.com/starmynd-org/infinite-brain-os/tree/main/workflows"
click node_projects "https://github.com/starmynd-org/infinite-brain-os/tree/main/projects"
click node_departments "https://github.com/starmynd-org/infinite-brain-os/tree/main/departments"
click node_swarms "https://github.com/starmynd-org/infinite-brain-os/tree/main/swarms"
click node_intake "https://github.com/starmynd-org/infinite-brain-os/tree/main/intake"
click node_sessions "https://github.com/starmynd-org/infinite-brain-os/tree/main/sessions"
click node_data "https://github.com/starmynd-org/infinite-brain-os/tree/main/data"
click node_memory "https://github.com/starmynd-org/infinite-brain-os/tree/main/memory"
click node_outputs "https://github.com/starmynd-org/infinite-brain-os/tree/main/outputs"
click node_claude "https://github.com/starmynd-org/infinite-brain-os/blob/main/.claude"
click node_codex "https://github.com/starmynd-org/infinite-brain-os/blob/main/.codex"
click node_obsidian "https://github.com/starmynd-org/infinite-brain-os/blob/main/.obsidian"
click node_n8n "https://github.com/starmynd-org/infinite-brain-os/tree/main/automations/n8n"

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_system,node_system_checks,node_system_namespaces,node_claude,node_codex,node_obsidian toneBlue
class node_knowledge_ai,node_knowledge_personal,node_knowledge_examples,node_knowledge_emberline,node_n8n toneAmber
class node_entities,node_workflows,node_projects,node_departments,node_swarms toneMint
class node_intake toneRose
class node_sessions toneIndigo
class node_data,node_memory,node_outputs toneTeal
```

## Components

### Contracts

Repository-wide schemas, rules, validation, and registry policies.

- [_system](https://github.com/starmynd-org/infinite-brain-os/tree/main/_system): contract spine · Source-of-truth layer for schemas, rules, routing maps, validation, and enforcement tiers. · `_system`
- [Checks](https://github.com/starmynd-org/infinite-brain-os/tree/main/_system/checks): validation · Repository validation scripts and contract checks. · `_system/checks`
- [Namespace rules](https://github.com/starmynd-org/infinite-brain-os/tree/main/_system/namespaces): registry · Namespace index, profiles, routing, load-order, and promotion policies. · `_system/namespaces`

### Knowledge

Namespace-first doctrine graph with canon, support, and synthesis layers.

- [AI arch](https://github.com/starmynd-org/infinite-brain-os/tree/main/knowledge/ai-architecture): namespace · Primary doctrine namespace for repository architecture and operating model. · `knowledge/ai-architecture`
- [Personal op](https://github.com/starmynd-org/infinite-brain-os/tree/main/knowledge/personal-operator): namespace · Namespace for operator profile, goals, and review cadence. · `knowledge/personal-operator`
- [Examples](https://github.com/starmynd-org/infinite-brain-os/tree/main/knowledge/_examples): reference set · Worked examples that demonstrate the namespace pattern and canonical structure. · `knowledge/_examples`
- [Emberline](https://github.com/starmynd-org/infinite-brain-os/tree/main/knowledge/emberline-studio): namespace · Brand-specific namespace used as an example operating lane. · `knowledge/emberline-studio`

### Execution

Operational primitives and orchestration layers that turn doctrine into work.

- [Entities](https://github.com/starmynd-org/infinite-brain-os/tree/main/entities): primitive layer · Typed operational building blocks for agents, commands, skills, and rules. · `entities`
- [Workflows](https://github.com/starmynd-org/infinite-brain-os/tree/main/workflows): orchestration · Reasoning and execution loops for review, onboarding, correction, and cadence work. · `workflows`
- [Projects](https://github.com/starmynd-org/infinite-brain-os/tree/main/projects): work container · Project plans and inline task tracking as the unit of managed work. · `projects`
- [Departments](https://github.com/starmynd-org/infinite-brain-os/tree/main/departments): operating lane · Assemblies of entities into structured business operating lanes. · `departments`
- [Swarms](https://github.com/starmynd-org/infinite-brain-os/tree/main/swarms): multi-agent sprint · Bounded burst execution for multi-agent work. · `swarms`

### Ingress

Inbound routing for external items and intake receipts.

- [Intake](https://github.com/starmynd-org/infinite-brain-os/tree/main/intake): ingress flow · Capture, route, and record external items into destinations and namespaces. · `intake`

### Audit

Session ledger and review trail for AI work.

- [Sessions](https://github.com/starmynd-org/infinite-brain-os/tree/main/sessions): ledger · Work ledger for AI activity, closeouts, logs, and reviews. · `sessions`

### Persistence

Distinct stored artifact classes and operational references.

- [Data](https://github.com/starmynd-org/infinite-brain-os/tree/main/data): live pointers · Pointers to live numbers and external operational values. · `data`
- [Memory](https://github.com/starmynd-org/infinite-brain-os/tree/main/memory): durable lessons · Reviewed lessons and durable learnings. · `memory`
- [Outputs](https://github.com/starmynd-org/infinite-brain-os/tree/main/outputs): deliverables · Produced artifacts with lineage and provenance. · `outputs`

### Surfaces

Runtime adapters and editor-facing access points.

- [Claude](https://github.com/starmynd-org/infinite-brain-os/blob/main/.claude): runtime surface · Claude-specific agents, commands, skills, hooks, and rules. · `.claude`
- [Codex](https://github.com/starmynd-org/infinite-brain-os/blob/main/.codex): runtime surface · Codex-specific agents, commands, and skills mirroring the Claude surface. · `.codex`
- [Obsidian](https://github.com/starmynd-org/infinite-brain-os/blob/main/.obsidian): editor surface · Vault configuration for human browsing and graph-oriented editing. · `.obsidian`

### Automation

Deterministic machine-executed workflows.

- [n8n](https://github.com/starmynd-org/infinite-brain-os/tree/main/automations/n8n): deterministic automation · Machine-executed workflow artifacts and docs. · `automations/n8n`

## Connections

- _system → Checks: validated by · Contract spine is enforced through repository checks and linting.
- _system → Namespace rules: governs · Defines namespace profiles, routing, and load-order policy.
- _system → AI arch: defines · System rules describe how doctrine namespaces are structured and validated.
- _system → Entities: types · System schemas determine the operational primitives available in the repo.
- AI arch → Personal op: frames · Architecture doctrine shapes operator-profile namespaces.
- AI arch → Examples: demonstrates · Example namespaces show the canonical pattern in practice.
- AI arch → Workflows: informs · Doctrine informs workflow design and review loops.
- Emberline → Departments: exemplifies · Brand namespace demonstrates the department assembly pattern.
- Entities → Workflows: composed by · Agents, skills, commands, and rules are assembled into workflows.
- Entities → Departments: assembled into · Operational primitives are packaged into department lanes.
- Workflows → Projects: drives · Workflow loops shape project planning and execution.
- Projects → Swarms: spawns · Projects can trigger bounded multi-agent sprint work.
- Intake → AI arch: routes to · Incoming items are routed into namespaces for processing and canonization.
- Intake → Departments: routes to · Some intake is routed into department lanes.
- Intake → Sessions: records · Routing and processing decisions are captured in sessionable work trails.
- Sessions → Outputs: closes into · Completed work produces outputs with lineage.
- Sessions → Memory: distills · Reviewed sessions become durable lessons.
- Data → AI arch: references · Operational data is kept separate from doctrine and points outward.
- Outputs → AI arch: feeds · Produced artifacts can feed back into knowledge synthesis.
- Claude → Entities: hosts · Claude surface mirrors operational primitives as toolchain assets.
- Codex → Entities: hosts · Codex surface mirrors operational primitives as toolchain assets.
- Obsidian → Examples: browses · Obsidian surface supports human navigation of the knowledge graph.
- n8n → Workflows: automates · Deterministic automations complement agentic workflows.
- Checks → Claude: syncs · Validation includes adapter and surface synchronization.
- Checks → Sessions: checks · Repo checks enforce session ledger status and freshness.