# munch2u-a11y/aimaos architecture

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

- Interactive diagram: https://gitdiagram.com/munch2u-a11y/aimaos
- Repository: https://github.com/munch2u-a11y/aimaos

## Overview

AIMAOS is a local-first office workstation: a user submits matter requests or files through the browser UI, work is recorded and routed to specialist agents, and resulting drafts or updates return for human review. The map includes the documented matter, scheduling, document, security, and memory capabilities. Some subsystems are represented by their exact source paths but were not sampled; their links are included only where the README or SOURCE INDEX supports them.

Main entry points: [`aimaos_ui.py`](https://github.com/munch2u-a11y/aimaos/blob/main/aimaos_ui.py) (Workstation API), [`core/case_agent.py`](https://github.com/munch2u-a11y/aimaos/blob/main/core/case_agent.py) (Matter reviewer), [`core/mrag/memory/belief_store.py`](https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/memory/belief_store.py) (Belief store), [`starter_packs/document_heavy/Marley-AI/core/orchestrator.py`](https://github.com/munch2u-a11y/aimaos/blob/main/starter_packs/document_heavy/Marley-AI/core/orchestrator.py) (Marley scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workstation["Workstation"]
  node_web_ui["Web UI entry<br/>[web_ui.py]"]
  node_dashboard["Workstation API<br/>[aimaos_ui.py]"]
  node_doc_review["Document review<br/>[document_review.py]"]
  node_agent_widgets["Agent status views<br/>[agent_widgets.py]"]
end

subgraph group_coordination["Work Coordination"]
  node_jobs["Background jobs<br/>[jobs.py]"]
  node_board["Office Board<br/>[office_board.py]"]
  node_workflow["Daily workflow review<br/>[workflow_review.py]"]
  node_scheduler["Marley scheduler<br/>[orchestrator.py]"]
end

subgraph group_specialists["Specialist Work"]
  node_agent_kernel["Shared agent kernel<br/>[office_agent.py]"]
  node_delegation["Tool delegation<br/>[delegation.py]"]
  node_case_agent["Matter reviewer<br/>[case_agent.py]"]
  node_kai_ingestion["Drive ingestion<br/>[drive_ingestion.py]"]
  node_client_file["Matter records<br/>[client_file.py]"]
  node_document_engine["Document production<br/>[document_engine.py]"]
  node_template_review["Template review"]
end

subgraph group_memory["Agent Memory"]
  node_memory_ingestor["Memory ingestion<br/>[memory_ingestor.py]"]
  node_belief_store[("Belief store<br/>[belief_store.py]")]
  node_belief_consolidator["Belief consolidation"]
  node_injection["Memory retrieval"]
  node_vector_store[("Vector retrieval<br/>[vector_store.py]")]
  node_token_counting["Token counting<br/>[token_counting.py]"]
end

subgraph group_platform["Local Platform"]
  node_security["Safe access policy<br/>[security.py]"]
  node_sqlite[("Office database<br/>[office_sqlite.py]")]
  node_llm["Local model access<br/>[llm.py]"]
  node_atomic_io["Safe local writes<br/>[atomic_io.py]"]
end

node_user(("Office user"))

node_user -->|"uses workstation"| node_web_ui
node_web_ui -->|"forwards requests"| node_dashboard
node_dashboard -->|"queues model work"| node_jobs
node_dashboard -->|"uses task board"| node_board
node_dashboard -->|"reads and writes"| node_sqlite
node_dashboard -->|"serves review"| node_doc_review
node_dashboard -->|"checks access"| node_security
node_dashboard -->|"renders status"| node_agent_widgets
node_dashboard -->|"uses review logic"| node_workflow
node_board -->|"syncs tasks"| node_sqlite
node_scheduler -->|"reads tasks"| node_board
node_scheduler -.->|"runs daily review"| node_workflow
node_scheduler -.->|"dispatches agents"| node_agent_kernel
node_agent_kernel -.->|"delegates tools"| node_delegation
node_delegation -.->|"plans tool work"| node_llm
node_kai_ingestion -->|"updates records"| node_client_file
node_kai_ingestion -->|"requests matter review"| node_case_agent
node_case_agent -->|"uses shared kernel"| node_agent_kernel
node_case_agent -->|"reads and writes memory"| node_belief_store
node_case_agent -->|"retrieves context"| node_injection
node_case_agent -->|"uses retrieval index"| node_vector_store
node_document_engine -.->|"supports template review"| node_template_review
node_memory_ingestor -->|"stores event chunks"| node_belief_store
node_memory_ingestor -.->|"counts tokens"| node_token_counting
node_belief_consolidator -->|"consolidates beliefs"| node_belief_store
node_belief_consolidator -->|"syncs retrieval context"| node_injection
node_belief_consolidator -->|"counts tokens"| node_token_counting
node_belief_store -.->|"indexes for retrieval"| node_vector_store
node_belief_store -.->|"persists memory"| node_atomic_io
node_client_file -->|"upserts case data"| node_sqlite

click node_web_ui "https://github.com/munch2u-a11y/aimaos/blob/main/ui/web_ui.py"
click node_dashboard "https://github.com/munch2u-a11y/aimaos/blob/main/aimaos_ui.py"
click node_doc_review "https://github.com/munch2u-a11y/aimaos/blob/main/core/document_review.py"
click node_security "https://github.com/munch2u-a11y/aimaos/blob/main/core/security.py"
click node_jobs "https://github.com/munch2u-a11y/aimaos/blob/main/core/jobs.py"
click node_board "https://github.com/munch2u-a11y/aimaos/blob/main/core/comms/office_board.py"
click node_sqlite "https://github.com/munch2u-a11y/aimaos/blob/main/core/db/office_sqlite.py"
click node_workflow "https://github.com/munch2u-a11y/aimaos/blob/main/core/workflow_review.py"
click node_scheduler "https://github.com/munch2u-a11y/aimaos/blob/main/starter_packs/document_heavy/Marley-AI/core/orchestrator.py"
click node_agent_kernel "https://github.com/munch2u-a11y/aimaos/blob/main/core/office_agent.py"
click node_delegation "https://github.com/munch2u-a11y/aimaos/blob/main/core/delegation.py"
click node_case_agent "https://github.com/munch2u-a11y/aimaos/blob/main/core/case_agent.py"
click node_kai_ingestion "https://github.com/munch2u-a11y/aimaos/blob/main/starter_packs/document_heavy/Kai-AI/tools/drive_ingestion.py"
click node_client_file "https://github.com/munch2u-a11y/aimaos/blob/main/starter_packs/document_heavy/Kai-AI/business/client_file.py"
click node_document_engine "https://github.com/munch2u-a11y/aimaos/blob/main/starter_packs/document_heavy/Alix-AI/business/document_engine.py"
click node_template_review "https://github.com/munch2u-a11y/aimaos/blob/main/starter_packs/document_heavy/Alix-AI/business/subagents/template_reviewer.py"
click node_llm "https://github.com/munch2u-a11y/aimaos/blob/main/core/llm.py"
click node_agent_widgets "https://github.com/munch2u-a11y/aimaos/blob/main/core/agent_widgets.py"
click node_atomic_io "https://github.com/munch2u-a11y/aimaos/blob/main/core/atomic_io.py"
click node_memory_ingestor "https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/core/memory_ingestor.py"
click node_belief_store "https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/memory/belief_store.py"
click node_belief_consolidator "https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/core/belief_consolidator.py"
click node_injection "https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/core/pre_generative_injection.py"
click node_vector_store "https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/core/vector_store.py"
click node_token_counting "https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/core/token_counting.py"

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_web_ui,node_dashboard,node_doc_review,node_agent_widgets,node_user toneBlue
class node_jobs,node_board,node_workflow,node_scheduler toneAmber
class node_agent_kernel,node_delegation,node_case_agent,node_kai_ingestion,node_client_file,node_document_engine,node_template_review toneMint
class node_memory_ingestor,node_belief_store,node_belief_consolidator,node_injection,node_vector_store,node_token_counting toneRose
class node_security,node_sqlite,node_llm,node_atomic_io toneIndigo
```

## Components

### Workstation

- [Web UI entry](https://github.com/munch2u-a11y/aimaos/blob/main/ui/web_ui.py): `ui/web_ui.py`
- [Workstation API](https://github.com/munch2u-a11y/aimaos/blob/main/aimaos_ui.py): `aimaos_ui.py`
- [Document review](https://github.com/munch2u-a11y/aimaos/blob/main/core/document_review.py): `core/document_review.py`
- [Agent status views](https://github.com/munch2u-a11y/aimaos/blob/main/core/agent_widgets.py): `core/agent_widgets.py`

### Work Coordination

- [Background jobs](https://github.com/munch2u-a11y/aimaos/blob/main/core/jobs.py): `core/jobs.py`
- [Office Board](https://github.com/munch2u-a11y/aimaos/blob/main/core/comms/office_board.py): `core/comms/office_board.py`
- [Daily workflow review](https://github.com/munch2u-a11y/aimaos/blob/main/core/workflow_review.py): `core/workflow_review.py`
- [Marley scheduler](https://github.com/munch2u-a11y/aimaos/blob/main/starter_packs/document_heavy/Marley-AI/core/orchestrator.py): `starter_packs/document_heavy/Marley-AI/core/orchestrator.py`

### Specialist Work

- [Shared agent kernel](https://github.com/munch2u-a11y/aimaos/blob/main/core/office_agent.py): `core/office_agent.py`
- [Tool delegation](https://github.com/munch2u-a11y/aimaos/blob/main/core/delegation.py): `core/delegation.py`
- [Matter reviewer](https://github.com/munch2u-a11y/aimaos/blob/main/core/case_agent.py): `core/case_agent.py`
- [Drive ingestion](https://github.com/munch2u-a11y/aimaos/blob/main/starter_packs/document_heavy/Kai-AI/tools/drive_ingestion.py): `starter_packs/document_heavy/Kai-AI/tools/drive_ingestion.py`
- [Matter records](https://github.com/munch2u-a11y/aimaos/blob/main/starter_packs/document_heavy/Kai-AI/business/client_file.py): `starter_packs/document_heavy/Kai-AI/business/client_file.py`
- [Document production](https://github.com/munch2u-a11y/aimaos/blob/main/starter_packs/document_heavy/Alix-AI/business/document_engine.py): `starter_packs/document_heavy/Alix-AI/business/document_engine.py`
- [Template review](https://github.com/munch2u-a11y/aimaos/blob/main/starter_packs/document_heavy/Alix-AI/business/subagents/template_reviewer.py): `starter_packs/document_heavy/Alix-AI/business/subagents/template_reviewer.py`

### Agent Memory

- [Memory ingestion](https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/core/memory_ingestor.py): `core/mrag/core/memory_ingestor.py`
- [Belief store](https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/memory/belief_store.py): `core/mrag/memory/belief_store.py`
- [Belief consolidation](https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/core/belief_consolidator.py): `core/mrag/core/belief_consolidator.py`
- [Memory retrieval](https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/core/pre_generative_injection.py): `core/mrag/core/pre_generative_injection.py`
- [Vector retrieval](https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/core/vector_store.py): `core/mrag/core/vector_store.py`
- [Token counting](https://github.com/munch2u-a11y/aimaos/blob/main/core/mrag/core/token_counting.py): `core/mrag/core/token_counting.py`

### Local Platform

- [Safe access policy](https://github.com/munch2u-a11y/aimaos/blob/main/core/security.py): `core/security.py`
- [Office database](https://github.com/munch2u-a11y/aimaos/blob/main/core/db/office_sqlite.py): `core/db/office_sqlite.py`
- [Local model access](https://github.com/munch2u-a11y/aimaos/blob/main/core/llm.py): `core/llm.py`
- [Safe local writes](https://github.com/munch2u-a11y/aimaos/blob/main/core/atomic_io.py): `core/atomic_io.py`

### Other components

- **Office user**

## Connections

- Office user → Web UI entry: uses workstation (evidence: `README.md`)
- Web UI entry → Workstation API: forwards requests (evidence: `ui/web_ui.py`)
- Workstation API → Background jobs: queues model work (evidence: `aimaos_ui.py`)
- Workstation API → Office Board: uses task board (evidence: `aimaos_ui.py`)
- Workstation API → Office database: reads and writes (evidence: `aimaos_ui.py`)
- Workstation API → Document review: serves review (evidence: `aimaos_ui.py`)
- Workstation API → Safe access policy: checks access (evidence: `aimaos_ui.py`)
- Workstation API → Agent status views: renders status (evidence: `aimaos_ui.py`)
- Workstation API → Daily workflow review: uses review logic (evidence: `aimaos_ui.py`)
- Office Board → Office database: syncs tasks (evidence: `core/comms/office_board.py`)
- Marley scheduler → Office Board: reads tasks (evidence: `starter_packs/document_heavy/Marley-AI/core/orchestrator.py`)
- Marley scheduler → Daily workflow review: runs daily review
- Marley scheduler → Shared agent kernel: dispatches agents
- Shared agent kernel → Tool delegation: delegates tools
- Tool delegation → Local model access: plans tool work
- Drive ingestion → Matter records: updates records (evidence: `starter_packs/document_heavy/Kai-AI/tools/drive_ingestion.py`)
- Drive ingestion → Matter reviewer: requests matter review (evidence: `starter_packs/document_heavy/Kai-AI/tools/drive_ingestion.py`)
- Matter reviewer → Shared agent kernel: uses shared kernel (evidence: `core/case_agent.py`)
- Matter reviewer → Belief store: reads and writes memory (evidence: `core/case_agent.py`)
- Matter reviewer → Memory retrieval: retrieves context (evidence: `core/case_agent.py`)
- Matter reviewer → Vector retrieval: uses retrieval index (evidence: `core/case_agent.py`)
- Document production → Template review: supports template review
- Memory ingestion → Belief store: stores event chunks (evidence: `core/mrag/core/memory_ingestor.py`)
- Memory ingestion → Token counting: counts tokens (evidence: `core/mrag/core/memory_ingestor.py`)
- Belief consolidation → Belief store: consolidates beliefs (evidence: `core/mrag/core/belief_consolidator.py`)
- Belief consolidation → Memory retrieval: syncs retrieval context (evidence: `core/mrag/core/belief_consolidator.py`)
- Belief consolidation → Token counting: counts tokens (evidence: `core/mrag/core/belief_consolidator.py`)
- Belief store → Vector retrieval: indexes for retrieval
- Belief store → Safe local writes: persists memory
- Matter records → Office database: upserts case data (evidence: `starter_packs/document_heavy/Kai-AI/business/client_file.py`)
