# kamalllx/mosaic architecture

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

- Interactive diagram: https://gitdiagram.com/kamalllx/mosaic
- Repository: https://github.com/kamalllx/mosaic

## Overview

mOSaic is an on-premises runtime for organizational AI, with browser, phone, and Linux-shell entry points. A user submits work through the gateway; the kernel schedules a task, creates bounded agent processes, and mediates privileged tool actions through policy, human approval, sandboxing, and audit. Agents use organizational knowledge and local models to produce sourced results. The README documents broader knowledge, identity, connector, memory, and surface capabilities; some are represented at subsystem-directory level because their implementation was not sampled. Edges cite the README or source excerpts that support them; unsampled relationships are not inferred.

Main entry points: [`kernel/mosaic_kernel/syscalls/gateway.py`](https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/syscalls/gateway.py) (Syscall mediation), [`agents/mosaic_agents/library`](https://github.com/kamalllx/mosaic/tree/main/agents/mosaic_agents/library) (Role agents), [`kernel/mosaic_kernel/gateway/app.py`](https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/gateway/app.py) (API gateway), [`apps/mobile/App.tsx`](https://github.com/kamalllx/mosaic/blob/main/apps/mobile/App.tsx) (Mobile app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_web["Browser desktop<br/>[page.tsx]"]
  node_phone["Mobile app<br/>[App.tsx]"]
  node_shell["Linux shell<br/>[cli.py]"]
end

subgraph group_runtime["Kernel runtime"]
  node_gateway["API gateway<br/>[app.py]"]
  node_kernel["Kernel<br/>[kernel.py]"]
  node_tasks["Task manager<br/>[manager.py]"]
  node_lifecycle["Agent lifecycle<br/>[manager.py]"]
  node_contracts["Shared contracts<br/>[common.py]"]
end

subgraph group_governance["Governance"]
  node_policy["Policy engine<br/>[engine.py]"]
  node_approvals["Human approvals<br/>[queue.py]"]
  node_syscalls["Syscall mediation<br/>[gateway.py]"]
  node_audit[("Audit journal<br/>[log.py]")]
end

subgraph group_intelligence["Agents and knowledge"]
  node_agents["Role agents"]
  node_knowledge[("Knowledge and memory")]
  node_models["Local models<br/>[router.py]"]
end

subgraph group_execution["Tools and state"]
  node_tools["Execution tools"]
  node_connectors["Connected apps"]
  node_state[("Kernel state store<br/>[store.py]")]
  node_filesystem[("Mounted org files")]
end

node_person(("Team member"))

node_person -->|"uses"| node_web
node_person -->|"uses"| node_phone
node_person -->|"uses"| node_shell
node_web -->|"requests"| node_gateway
node_phone -->|"calls API"| node_gateway
node_shell -->|"calls API"| node_gateway
node_gateway -->|"routes work"| node_kernel
node_kernel -->|"manages tasks"| node_tasks
node_kernel -->|"restores state"| node_state
node_tasks -->|"drops agents"| node_lifecycle
node_lifecycle -->|"spawns role"| node_agents
node_agents -->|"retrieves evidence"| node_knowledge
node_agents -.->|"requests inference"| node_models
node_agents -->|"requests actions"| node_syscalls
node_syscalls -.->|"checks policy"| node_policy
node_syscalls -.->|"waits approval"| node_approvals
node_syscalls -.->|"dispatches tools"| node_tools
node_tools -.->|"uses integrations"| node_connectors
node_syscalls -.->|"journals actions"| node_audit
node_knowledge -->|"mounts knowledge"| node_filesystem
node_lifecycle -->|"uses schemas"| node_contracts
node_policy -->|"evaluates requests"| node_contracts
node_phone -.->|"shares platform"| node_web

click node_web "https://github.com/kamalllx/mosaic/blob/main/apps/web/app/page.tsx"
click node_phone "https://github.com/kamalllx/mosaic/blob/main/apps/mobile/App.tsx"
click node_shell "https://github.com/kamalllx/mosaic/blob/main/sdk/python/src/mosaic_os/cli.py"
click node_gateway "https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/gateway/app.py"
click node_kernel "https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/kernel.py"
click node_tasks "https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/tasks/manager.py"
click node_lifecycle "https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/lifecycle/manager.py"
click node_contracts "https://github.com/kamalllx/mosaic/blob/main/shared/python/mosaic_contracts/schema/common.py"
click node_policy "https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/policy/engine.py"
click node_approvals "https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/approvals/queue.py"
click node_syscalls "https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/syscalls/gateway.py"
click node_audit "https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/audit/log.py"
click node_agents "https://github.com/kamalllx/mosaic/tree/main/agents/mosaic_agents/library"
click node_knowledge "https://github.com/kamalllx/mosaic/tree/main/knowledge/mosaic_knowledge"
click node_models "https://github.com/kamalllx/mosaic/blob/main/models/mosaic_models/router/router.py"
click node_tools "https://github.com/kamalllx/mosaic/tree/main/execution/mosaic_execution/tools"
click node_connectors "https://github.com/kamalllx/mosaic/tree/main/execution/mosaic_execution/connectors"
click node_state "https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/persistence/store.py"
click node_filesystem "https://github.com/kamalllx/mosaic/tree/main/knowledge/mosaic_knowledge/okf"

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,node_phone,node_shell toneBlue
class node_gateway,node_kernel,node_tasks,node_lifecycle,node_contracts toneAmber
class node_policy,node_approvals,node_syscalls,node_audit toneMint
class node_agents,node_knowledge,node_models toneRose
class node_tools,node_connectors,node_state,node_filesystem,node_person toneIndigo
```

## Components

### User surfaces

- [Browser desktop](https://github.com/kamalllx/mosaic/blob/main/apps/web/app/page.tsx): `apps/web/app/page.tsx`
- [Mobile app](https://github.com/kamalllx/mosaic/blob/main/apps/mobile/App.tsx): `apps/mobile/App.tsx`
- [Linux shell](https://github.com/kamalllx/mosaic/blob/main/sdk/python/src/mosaic_os/cli.py): `sdk/python/src/mosaic_os/cli.py`

### Kernel runtime

- [API gateway](https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/gateway/app.py): `kernel/mosaic_kernel/gateway/app.py`
- [Kernel](https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/kernel.py): `kernel/mosaic_kernel/kernel.py`
- [Task manager](https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/tasks/manager.py): `kernel/mosaic_kernel/tasks/manager.py`
- [Agent lifecycle](https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/lifecycle/manager.py): `kernel/mosaic_kernel/lifecycle/manager.py`
- [Shared contracts](https://github.com/kamalllx/mosaic/blob/main/shared/python/mosaic_contracts/schema/common.py): `shared/python/mosaic_contracts/schema/common.py`

### Governance

- [Policy engine](https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/policy/engine.py): `kernel/mosaic_kernel/policy/engine.py`
- [Human approvals](https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/approvals/queue.py): `kernel/mosaic_kernel/approvals/queue.py`
- [Syscall mediation](https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/syscalls/gateway.py): `kernel/mosaic_kernel/syscalls/gateway.py`
- [Audit journal](https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/audit/log.py): `kernel/mosaic_kernel/audit/log.py`

### Agents and knowledge

- [Role agents](https://github.com/kamalllx/mosaic/tree/main/agents/mosaic_agents/library): `agents/mosaic_agents/library`
- [Knowledge and memory](https://github.com/kamalllx/mosaic/tree/main/knowledge/mosaic_knowledge): `knowledge/mosaic_knowledge`
- [Local models](https://github.com/kamalllx/mosaic/blob/main/models/mosaic_models/router/router.py): `models/mosaic_models/router/router.py`

### Tools and state

- [Execution tools](https://github.com/kamalllx/mosaic/tree/main/execution/mosaic_execution/tools): `execution/mosaic_execution/tools`
- [Connected apps](https://github.com/kamalllx/mosaic/tree/main/execution/mosaic_execution/connectors): `execution/mosaic_execution/connectors`
- [Kernel state store](https://github.com/kamalllx/mosaic/blob/main/kernel/mosaic_kernel/persistence/store.py): `kernel/mosaic_kernel/persistence/store.py`
- [Mounted org files](https://github.com/kamalllx/mosaic/tree/main/knowledge/mosaic_knowledge/okf): `knowledge/mosaic_knowledge/okf`

### Other components

- **Team member**

## Connections

- Team member → Browser desktop: uses (evidence: `README.md`)
- Team member → Mobile app: uses (evidence: `README.md`)
- Team member → Linux shell: uses (evidence: `README.md`)
- Browser desktop → API gateway: requests (evidence: `README.md`)
- Mobile app → API gateway: calls API
- Linux shell → API gateway: calls API (evidence: `README.md`)
- API gateway → Kernel: routes work (evidence: `kernel/mosaic_kernel/gateway/app.py`)
- Kernel → Task manager: manages tasks (evidence: `kernel/mosaic_kernel/kernel.py`)
- Kernel → Kernel state store: restores state (evidence: `kernel/mosaic_kernel/kernel.py`)
- Task manager → Agent lifecycle: drops agents (evidence: `kernel/mosaic_kernel/tasks/manager.py`)
- Agent lifecycle → Role agents: spawns role (evidence: `kernel/mosaic_kernel/lifecycle/manager.py`)
- Role agents → Knowledge and memory: retrieves evidence (evidence: `agents/mosaic_agents/library/engineering.py`)
- Role agents → Local models: requests inference
- Role agents → Syscall mediation: requests actions (evidence: `README.md`)
- Syscall mediation → Policy engine: checks policy
- Syscall mediation → Human approvals: waits approval
- Syscall mediation → Execution tools: dispatches tools
- Execution tools → Connected apps: uses integrations
- Syscall mediation → Audit journal: journals actions
- Knowledge and memory → Mounted org files: mounts knowledge (evidence: `README.md`)
- Agent lifecycle → Shared contracts: uses schemas (evidence: `kernel/mosaic_kernel/lifecycle/manager.py`)
- Policy engine → Shared contracts: evaluates requests (evidence: `kernel/mosaic_kernel/policy/engine.py`)
- Mobile app → Browser desktop: shares platform
