# rush86999/atom architecture

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

- Interactive diagram: https://gitdiagram.com/rush86999/atom
- Repository: https://github.com/rush86999/atom

## Overview

Atom is a self-hosted, governed AI agent workforce. A user delegates a task in plain language; Atom builds and runs a workflow, with approvals and scoped governance around actions, then checks outcomes and records activity. The platform also ingests documents and business communications into searchable memory, supports integrations and local or hosted LLMs, and includes finance and analytics capabilities. The README documents the main product workflow and safeguards; source excerpts expose parts of ingestion and persistence, but not the full request-to-execution path.

Main entry points: [`backend/core/agent_execution_service.py`](https://github.com/rush86999/atom/blob/main/backend/core/agent_execution_service.py) (Agent execution), [`frontend-nextjs`](https://github.com/rush86999/atom/tree/main/frontend-nextjs) (Web workspace), [`backend/core/hybrid_data_ingestion.py`](https://github.com/rush86999/atom/blob/main/backend/core/hybrid_data_ingestion.py) (Hybrid data ingestion), [`backend/integrations/atom_communication_ingestion_pipeline.py`](https://github.com/rush86999/atom/blob/main/backend/integrations/atom_communication_ingestion_pipeline.py) (Communication ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_frontend["Web workspace"]
  node_canvas["Interactive canvas<br/>[AppCanvas.tsx]"]
end

subgraph group_agents["Agents and governance"]
  node_workflow["Workflow automation"]
  node_agent_execution["Agent execution"]
  node_trigger["AI trigger coordinator"]
  node_governance["Governance and safety<br/>[policy_engine.py]"]
  node_verification["Outcome verification"]
  node_approvals["Human approvals"]
end

subgraph group_ingestion["Data and memory"]
  node_data_routes["Data ingestion API"]
  node_document_routes["Document ingestion API"]
  node_ingestion_pipeline["Knowledge ingestion"]
  node_hybrid_ingestion["Hybrid data ingestion"]
  node_communication_ingestion["Communication ingestion"]
  node_vector_memory[("Vector memory<br/>[lancedb_handler.py]")]
end

subgraph group_integrations["Integrations"]
  node_gmail["Gmail integration<br/>[gmail_service.py]"]
  node_webhooks["Ingestion webhooks"]
end

subgraph group_platform["Platform services"]
  node_database[("Application database<br/>[database.py]")]
  node_llm_oauth["LLM provider credentials"]
  node_accounting["Finance operations"]
  node_analytics["Analytics"]
end

node_user(("Business user"))

node_user -->|"delegates work"| node_frontend
node_frontend -.->|"describes workflow"| node_workflow
node_workflow -.->|"runs workflow"| node_agent_execution
node_agent_execution -.->|"enforces boundaries"| node_governance
node_agent_execution -.->|"requests approval"| node_approvals
node_agent_execution -.->|"checks outcomes"| node_verification
node_trigger -->|"coordinates triggers"| node_agent_execution
node_user -->|"configures sync"| node_data_routes
node_data_routes -->|"starts sync"| node_hybrid_ingestion
node_document_routes -.->|"syncs documents"| node_ingestion_pipeline
node_hybrid_ingestion -->|"writes vectors"| node_vector_memory
node_ingestion_pipeline -->|"stores knowledge"| node_vector_memory
node_webhooks -.->|"triggers ingestion"| node_communication_ingestion
node_gmail -->|"feeds communications"| node_communication_ingestion
node_communication_ingestion -.->|"indexes messages"| node_vector_memory
node_hybrid_ingestion -->|"reads and writes"| node_database
node_llm_oauth -->|"stores credentials"| node_database
node_frontend -.->|"presents workspace"| node_canvas
node_user -.->|"uses finance tools"| node_accounting
node_user -.->|"reviews analytics"| node_analytics

click node_frontend "https://github.com/rush86999/atom/tree/main/frontend-nextjs"
click node_workflow "https://github.com/rush86999/atom/blob/main/backend/ai/automation_engine.py"
click node_agent_execution "https://github.com/rush86999/atom/blob/main/backend/core/agent_execution_service.py"
click node_trigger "https://github.com/rush86999/atom/blob/main/backend/core/ai_trigger_coordinator.py"
click node_governance "https://github.com/rush86999/atom/blob/main/backend/core/governance/policy_engine.py"
click node_verification "https://github.com/rush86999/atom/blob/main/backend/independent_ai_validator/core/validator_engine.py"
click node_approvals "https://github.com/rush86999/atom/blob/main/backend/api/approvals_routes.py"
click node_data_routes "https://github.com/rush86999/atom/blob/main/backend/api/data_ingestion_routes.py"
click node_document_routes "https://github.com/rush86999/atom/blob/main/backend/api/document_ingestion_routes.py"
click node_ingestion_pipeline "https://github.com/rush86999/atom/blob/main/backend/core/ingestion_pipeline.py"
click node_hybrid_ingestion "https://github.com/rush86999/atom/blob/main/backend/core/hybrid_data_ingestion.py"
click node_communication_ingestion "https://github.com/rush86999/atom/blob/main/backend/integrations/atom_communication_ingestion_pipeline.py"
click node_vector_memory "https://github.com/rush86999/atom/blob/main/backend/core/lancedb_handler.py"
click node_database "https://github.com/rush86999/atom/blob/main/backend/core/database.py"
click node_gmail "https://github.com/rush86999/atom/blob/main/backend/integrations/gmail_service.py"
click node_webhooks "https://github.com/rush86999/atom/blob/main/backend/api/routes/webhooks/ingestion_webhooks.py"
click node_llm_oauth "https://github.com/rush86999/atom/blob/main/backend/core/llm_oauth_handler.py"
click node_canvas "https://github.com/rush86999/atom/blob/main/archive/2026-07-consolidation/source/src/components/canvas/AppCanvas.tsx"
click node_accounting "https://github.com/rush86999/atom/tree/main/backend/accounting"
click node_analytics "https://github.com/rush86999/atom/tree/main/backend/analytics"

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_frontend,node_canvas,node_user toneBlue
class node_workflow,node_agent_execution,node_trigger,node_governance,node_verification,node_approvals toneAmber
class node_data_routes,node_document_routes,node_ingestion_pipeline,node_hybrid_ingestion,node_communication_ingestion,node_vector_memory toneMint
class node_gmail,node_webhooks toneRose
class node_database,node_llm_oauth,node_accounting,node_analytics toneIndigo
```

## Components

### User interaction

- [Web workspace](https://github.com/rush86999/atom/tree/main/frontend-nextjs): `frontend-nextjs`
- [Interactive canvas](https://github.com/rush86999/atom/blob/main/archive/2026-07-consolidation/source/src/components/canvas/AppCanvas.tsx): `archive/2026-07-consolidation/source/src/components/canvas/AppCanvas.tsx`

### Agents and governance

- [Workflow automation](https://github.com/rush86999/atom/blob/main/backend/ai/automation_engine.py): `backend/ai/automation_engine.py`
- [Agent execution](https://github.com/rush86999/atom/blob/main/backend/core/agent_execution_service.py): `backend/core/agent_execution_service.py`
- [AI trigger coordinator](https://github.com/rush86999/atom/blob/main/backend/core/ai_trigger_coordinator.py): `backend/core/ai_trigger_coordinator.py`
- [Governance and safety](https://github.com/rush86999/atom/blob/main/backend/core/governance/policy_engine.py): `backend/core/governance/policy_engine.py`
- [Outcome verification](https://github.com/rush86999/atom/blob/main/backend/independent_ai_validator/core/validator_engine.py): `backend/independent_ai_validator/core/validator_engine.py`
- [Human approvals](https://github.com/rush86999/atom/blob/main/backend/api/approvals_routes.py): `backend/api/approvals_routes.py`

### Data and memory

- [Data ingestion API](https://github.com/rush86999/atom/blob/main/backend/api/data_ingestion_routes.py): `backend/api/data_ingestion_routes.py`
- [Document ingestion API](https://github.com/rush86999/atom/blob/main/backend/api/document_ingestion_routes.py): `backend/api/document_ingestion_routes.py`
- [Knowledge ingestion](https://github.com/rush86999/atom/blob/main/backend/core/ingestion_pipeline.py): `backend/core/ingestion_pipeline.py`
- [Hybrid data ingestion](https://github.com/rush86999/atom/blob/main/backend/core/hybrid_data_ingestion.py): `backend/core/hybrid_data_ingestion.py`
- [Communication ingestion](https://github.com/rush86999/atom/blob/main/backend/integrations/atom_communication_ingestion_pipeline.py): `backend/integrations/atom_communication_ingestion_pipeline.py`
- [Vector memory](https://github.com/rush86999/atom/blob/main/backend/core/lancedb_handler.py): `backend/core/lancedb_handler.py`

### Integrations

- [Gmail integration](https://github.com/rush86999/atom/blob/main/backend/integrations/gmail_service.py): `backend/integrations/gmail_service.py`
- [Ingestion webhooks](https://github.com/rush86999/atom/blob/main/backend/api/routes/webhooks/ingestion_webhooks.py): `backend/api/routes/webhooks/ingestion_webhooks.py`

### Platform services

- [Application database](https://github.com/rush86999/atom/blob/main/backend/core/database.py): `backend/core/database.py`
- [LLM provider credentials](https://github.com/rush86999/atom/blob/main/backend/core/llm_oauth_handler.py): `backend/core/llm_oauth_handler.py`
- [Finance operations](https://github.com/rush86999/atom/tree/main/backend/accounting): `backend/accounting`
- [Analytics](https://github.com/rush86999/atom/tree/main/backend/analytics): `backend/analytics`

### Other components

- **Business user**

## Connections

- Business user → Web workspace: delegates work
- Web workspace → Workflow automation: describes workflow
- Workflow automation → Agent execution: runs workflow
- Agent execution → Governance and safety: enforces boundaries
- Agent execution → Human approvals: requests approval
- Agent execution → Outcome verification: checks outcomes
- AI trigger coordinator → Agent execution: coordinates triggers (evidence: `backend/core/ai_trigger_coordinator.py`)
- Business user → Data ingestion API: configures sync (evidence: `backend/api/data_ingestion_routes.py`)
- Data ingestion API → Hybrid data ingestion: starts sync (evidence: `backend/api/data_ingestion_routes.py`)
- Document ingestion API → Knowledge ingestion: syncs documents
- Hybrid data ingestion → Vector memory: writes vectors (evidence: `backend/core/hybrid_data_ingestion.py`)
- Knowledge ingestion → Vector memory: stores knowledge (evidence: `backend/core/ingestion_pipeline.py`)
- Ingestion webhooks → Communication ingestion: triggers ingestion (evidence: `backend/api/routes/webhooks/ingestion_webhooks.py`)
- Gmail integration → Communication ingestion: feeds communications (evidence: `backend/integrations/gmail_service.py`)
- Communication ingestion → Vector memory: indexes messages (evidence: `backend/integrations/atom_communication_ingestion_pipeline.py`)
- Hybrid data ingestion → Application database: reads and writes (evidence: `backend/core/hybrid_data_ingestion.py`)
- LLM provider credentials → Application database: stores credentials (evidence: `backend/core/llm_oauth_handler.py`)
- Web workspace → Interactive canvas: presents workspace
- Business user → Finance operations: uses finance tools
- Business user → Analytics: reviews analytics
