# aiosai/aipass architecture

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

- Interactive diagram: https://gitdiagram.com/aiosai/aipass
- Repository: https://github.com/aiosai/aipass

## Overview

AIPass is a local, CLI-native workspace that scaffolds projects with persistent, collaborating AI agents. The main path is user setup or project adoption, followed by an agent conversation that can resume with identity and memory; agents share project files and can be reached through Drone for delegated work. Supporting branches provide scheduling, hooks, shared collaboration, host APIs, and backup. README statements support the high-level workflow; sampled source confirms selected notification, hook, feedback, and API behavior, but not every subsystem’s wiring.

Main entry points: [`src/aipass/aipass/apps/aipass.py`](https://github.com/aiosai/aipass/blob/main/src/aipass/aipass/apps/aipass.py) (AIPass CLI), [`src/aipass/drone/apps/drone.py`](https://github.com/aiosai/aipass/blob/main/src/aipass/drone/apps/drone.py) (Drone CLI), [`src/aipass/commons/apps/modules/post.py`](https://github.com/aiosai/aipass/blob/main/src/aipass/commons/apps/modules/post.py) (Shared Collaboration), [`src/aipass/aipass/apps/modules/init_flow.py`](https://github.com/aiosai/aipass/blob/main/src/aipass/aipass/apps/modules/init_flow.py) (Guided Init)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup & Projects"]
  node_aipass_cli["AIPass CLI<br/>[aipass.py]"]
  node_init_flow["Guided Init<br/>[init_flow.py]"]
  node_new_project["New Project<br/>[new_project.py]"]
  node_adopt["Project Adoption<br/>[adopt.py]"]
  node_doctor["Health Check<br/>[doctor.py]"]
  node_project_files["Project Workspace"]
end

subgraph group_agents["Agent Runtime"]
  node_drone["Drone CLI<br/>[drone.py]"]
  node_agent_registry["Agent Registry<br/>[registry.py]"]
  node_memory_search["Memory Search<br/>[query_executor.py]"]
  node_governance["Memory Governance<br/>[engine.py]"]
  node_hooks["Hook Dispatcher<br/>[engine.py]"]
end

subgraph group_coordination["Coordination"]
  node_daemon["Daemon Scheduler<br/>[schedule.py]"]
  node_mail["Agent Mail<br/>[email.py]"]
  node_commons["Shared Collaboration<br/>[post.py]"]
  node_commons_db[("Commons Database<br/>[db.py]")]
end

subgraph group_services["Workspace Services"]
  node_backup["Backup &amp; Restore"]
end

subgraph group_integrations["External Interfaces"]
  node_host_api["Host API<br/>[host_api.py]"]
  node_integrations_mgr["Integration Contracts"]
end

node_user(("User"))
node_claude(("Claude Code"))
node_external_api(("Opt-in APIs"))

node_user -->|"runs commands"| node_aipass_cli
node_aipass_cli -->|"starts guided setup"| node_init_flow
node_aipass_cli -->|"creates project"| node_new_project
node_aipass_cli -->|"adopts project"| node_adopt
node_aipass_cli -->|"checks health"| node_doctor
node_init_flow -->|"scaffolds workspace"| node_project_files
node_new_project -->|"creates workspace"| node_project_files
node_adopt -->|"uses directory"| node_project_files
node_claude -->|"works in"| node_project_files
node_drone -->|"resolves agents"| node_agent_registry
node_drone -->|"dispatches work"| node_project_files
node_project_files -->|"stores agent memory"| node_memory_search
node_project_files -->|"provides surfaced items"| node_governance
node_claude -->|"emits hook events"| node_hooks
node_daemon -->|"schedules workspace work"| node_project_files
node_commons -->|"reads and writes"| node_commons_db
node_commons -->|"notifies agents"| node_mail
node_backup -->|"snapshots files"| node_project_files
node_host_api -->|"serves workspace data"| node_project_files
node_integrations_mgr -.->|"invokes contracts"| node_external_api

click node_aipass_cli "https://github.com/aiosai/aipass/blob/main/src/aipass/aipass/apps/aipass.py"
click node_init_flow "https://github.com/aiosai/aipass/blob/main/src/aipass/aipass/apps/modules/init_flow.py"
click node_new_project "https://github.com/aiosai/aipass/blob/main/src/aipass/aipass/apps/modules/new_project.py"
click node_adopt "https://github.com/aiosai/aipass/blob/main/src/aipass/aipass/apps/modules/adopt.py"
click node_doctor "https://github.com/aiosai/aipass/blob/main/src/aipass/aipass/apps/modules/doctor.py"
click node_drone "https://github.com/aiosai/aipass/blob/main/src/aipass/drone/apps/drone.py"
click node_agent_registry "https://github.com/aiosai/aipass/blob/main/src/aipass/drone/apps/modules/registry.py"
click node_memory_search "https://github.com/aiosai/aipass/blob/main/src/aipass/memory/apps/handlers/search/query_executor.py"
click node_governance "https://github.com/aiosai/aipass/blob/main/src/aipass/memory/apps/handlers/governance/engine.py"
click node_hooks "https://github.com/aiosai/aipass/blob/main/src/aipass/hooks/apps/modules/engine.py"
click node_daemon "https://github.com/aiosai/aipass/blob/main/src/aipass/daemon/apps/modules/schedule.py"
click node_mail "https://github.com/aiosai/aipass/blob/main/src/aipass/ai_mail/apps/modules/email.py"
click node_commons "https://github.com/aiosai/aipass/blob/main/src/aipass/commons/apps/modules/post.py"
click node_commons_db "https://github.com/aiosai/aipass/blob/main/src/aipass/commons/apps/handlers/database/db.py"
click node_host_api "https://github.com/aiosai/aipass/blob/main/src/aipass/api/apps/modules/host_api.py"
click node_integrations_mgr "https://github.com/aiosai/aipass/blob/main/src/aipass/api/apps/modules/integrations_manager.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_aipass_cli,node_init_flow,node_new_project,node_adopt,node_doctor,node_project_files,node_user toneBlue
class node_drone,node_agent_registry,node_memory_search,node_governance,node_hooks toneAmber
class node_daemon,node_mail,node_commons,node_commons_db,node_external_api toneMint
class node_backup toneRose
class node_host_api,node_integrations_mgr,node_claude toneIndigo
```

## Components

### Setup & Projects

- [AIPass CLI](https://github.com/aiosai/aipass/blob/main/src/aipass/aipass/apps/aipass.py): `src/aipass/aipass/apps/aipass.py`
- [Guided Init](https://github.com/aiosai/aipass/blob/main/src/aipass/aipass/apps/modules/init_flow.py): `src/aipass/aipass/apps/modules/init_flow.py`
- [New Project](https://github.com/aiosai/aipass/blob/main/src/aipass/aipass/apps/modules/new_project.py): `src/aipass/aipass/apps/modules/new_project.py`
- [Project Adoption](https://github.com/aiosai/aipass/blob/main/src/aipass/aipass/apps/modules/adopt.py): `src/aipass/aipass/apps/modules/adopt.py`
- [Health Check](https://github.com/aiosai/aipass/blob/main/src/aipass/aipass/apps/modules/doctor.py): `src/aipass/aipass/apps/modules/doctor.py`
- **Project Workspace**

### Agent Runtime

- [Drone CLI](https://github.com/aiosai/aipass/blob/main/src/aipass/drone/apps/drone.py): `src/aipass/drone/apps/drone.py`
- [Agent Registry](https://github.com/aiosai/aipass/blob/main/src/aipass/drone/apps/modules/registry.py): `src/aipass/drone/apps/modules/registry.py`
- [Memory Search](https://github.com/aiosai/aipass/blob/main/src/aipass/memory/apps/handlers/search/query_executor.py): `src/aipass/memory/apps/handlers/search/query_executor.py`
- [Memory Governance](https://github.com/aiosai/aipass/blob/main/src/aipass/memory/apps/handlers/governance/engine.py): `src/aipass/memory/apps/handlers/governance/engine.py`
- [Hook Dispatcher](https://github.com/aiosai/aipass/blob/main/src/aipass/hooks/apps/modules/engine.py): `src/aipass/hooks/apps/modules/engine.py`

### Coordination

- [Daemon Scheduler](https://github.com/aiosai/aipass/blob/main/src/aipass/daemon/apps/modules/schedule.py): `src/aipass/daemon/apps/modules/schedule.py`
- [Agent Mail](https://github.com/aiosai/aipass/blob/main/src/aipass/ai_mail/apps/modules/email.py): `src/aipass/ai_mail/apps/modules/email.py`
- [Shared Collaboration](https://github.com/aiosai/aipass/blob/main/src/aipass/commons/apps/modules/post.py): `src/aipass/commons/apps/modules/post.py`
- [Commons Database](https://github.com/aiosai/aipass/blob/main/src/aipass/commons/apps/handlers/database/db.py): `src/aipass/commons/apps/handlers/database/db.py`

### Workspace Services

- **Backup & Restore**

### External Interfaces

- [Host API](https://github.com/aiosai/aipass/blob/main/src/aipass/api/apps/modules/host_api.py): `src/aipass/api/apps/modules/host_api.py`
- [Integration Contracts](https://github.com/aiosai/aipass/blob/main/src/aipass/api/apps/modules/integrations_manager.py): `src/aipass/api/apps/modules/integrations_manager.py`

### Other components

- **User**
- **Claude Code**
- **Opt-in APIs**

## Connections

- User → AIPass CLI: runs commands
- AIPass CLI → Guided Init: starts guided setup
- AIPass CLI → New Project: creates project
- AIPass CLI → Project Adoption: adopts project
- AIPass CLI → Health Check: checks health
- Guided Init → Project Workspace: scaffolds workspace
- New Project → Project Workspace: creates workspace
- Project Adoption → Project Workspace: uses directory
- Claude Code → Project Workspace: works in
- Drone CLI → Agent Registry: resolves agents
- Drone CLI → Project Workspace: dispatches work
- Project Workspace → Memory Search: stores agent memory
- Project Workspace → Memory Governance: provides surfaced items
- Claude Code → Hook Dispatcher: emits hook events
- Daemon Scheduler → Project Workspace: schedules workspace work
- Shared Collaboration → Commons Database: reads and writes
- Shared Collaboration → Agent Mail: notifies agents
- Backup & Restore → Project Workspace: snapshots files
- Host API → Project Workspace: serves workspace data
- Integration Contracts → Opt-in APIs: invokes contracts