# agenticubed/a3 architecture

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

- Interactive diagram: https://gitdiagram.com/agenticubed/a3
- Repository: https://github.com/agenticubed/a3

## Overview

AgentiCubed is a governed project-orchestration platform: users define projects, plans are decomposed and assigned, tasks execute and are evaluated, and gaps can trigger remediation and re-execution until acceptance. The backend exposes versioned APIs, with a Next.js interface and a durable Celery worker option. The README documents the domain loop; sampled source confirms selected API, audit, execution, and browser-extension behavior. Most feature routers and several services were not sampled, so their internal call relationships are not inferred.

Main entry points: [`backend/app/services/execution_service.py`](https://github.com/agenticubed/a3/blob/main/backend/app/services/execution_service.py) (Task execution), [`bananers/src/content/main.js`](https://github.com/agenticubed/a3/blob/main/bananers/src/content/main.js) (Content detector), [`backend/app/api/v1/router.py`](https://github.com/agenticubed/a3/blob/main/backend/app/api/v1/router.py) (Versioned API), [`frontend/src/app`](https://github.com/agenticubed/a3/tree/main/frontend/src/app) (Project UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_webui["Project UI"]
  node_api["Versioned API<br/>[router.py]"]
end

subgraph group_planning["Planning and assignment"]
  node_project_intake["Project intake<br/>[project_service.py]"]
  node_methodology["Methodology<br/>[methodology.py]"]
  node_decomposition["Work decomposition"]
  node_capabilities["Capability analysis<br/>[capabilities.py]"]
  node_matching["Agent matching<br/>[matching.py]"]
  node_agent_registry["Agent registry<br/>[agent_service.py]"]
end

subgraph group_execution["Execution and evaluation"]
  node_execution["Task execution"]
  node_lifecycle["Execution lifecycle<br/>[states.py]"]
  node_providers["Provider adapters<br/>[registry.py]"]
  node_workflow_engine["Workflow engine<br/>[engines.py]"]
  node_worker["Celery worker<br/>[tasks.py]"]
  node_evaluation["Output evaluation<br/>[specs.py]"]
  node_remediation["Remediation policy<br/>[policy.py]"]
end

subgraph group_governance["Governance and reporting"]
  node_approval["Human approval"]
  node_audit["Audit and events<br/>[audit.py]"]
  node_analytics["Analytics<br/>[compute.py]"]
  node_closeout["Project closeout"]
end

subgraph group_extension["Banner extension"]
  node_content_entry["Content detector<br/>[main.js]"]
  node_banner_detection["Banner detection<br/>[detect.js]"]
  node_dismissal["Dismissal planner<br/>[dismiss.js]"]
  node_extension_store[("Extension storage<br/>[store.js]")]
end

node_user(("Project user"))

node_user -.->|"uses"| node_webui
node_webui -.->|"requests"| node_api
node_api -.->|"handles intake"| node_project_intake
node_project_intake -->|"recommends"| node_methodology
node_methodology -->|"plans work"| node_decomposition
node_decomposition -->|"identifies needs"| node_capabilities
node_capabilities -->|"informs assignment"| node_matching
node_matching -->|"selects agents"| node_agent_registry
node_agent_registry -->|"assigned work"| node_execution
node_execution -->|"evaluates outputs"| node_evaluation
node_evaluation -->|"identifies gaps"| node_remediation
node_remediation -->|"re-executes"| node_execution
node_execution -->|"uses states"| node_lifecycle
node_execution -->|"selects adapter"| node_providers
node_execution -->|"dispatches work"| node_workflow_engine
node_workflow_engine -->|"queues execution"| node_worker
node_worker -->|"runs task"| node_execution
node_execution -.->|"requests approval"| node_approval
node_execution -->|"records changes"| node_audit
node_audit -.->|"publishes events"| node_extension_store
node_api -.->|"serves reporting"| node_analytics
node_approval -->|"supports acceptance"| node_closeout
node_content_entry -->|"finds banners"| node_banner_detection
node_content_entry -->|"plans dismissal"| node_dismissal
node_content_entry -->|"stores learning"| node_extension_store

click node_webui "https://github.com/agenticubed/a3/tree/main/frontend/src/app"
click node_api "https://github.com/agenticubed/a3/blob/main/backend/app/api/v1/router.py"
click node_project_intake "https://github.com/agenticubed/a3/blob/main/backend/app/services/project_service.py"
click node_methodology "https://github.com/agenticubed/a3/blob/main/backend/app/services/methodology.py"
click node_decomposition "https://github.com/agenticubed/a3/blob/main/backend/app/services/decomposition_service.py"
click node_capabilities "https://github.com/agenticubed/a3/blob/main/backend/app/core/capabilities.py"
click node_matching "https://github.com/agenticubed/a3/blob/main/backend/app/services/matching.py"
click node_agent_registry "https://github.com/agenticubed/a3/blob/main/backend/app/services/agent_service.py"
click node_execution "https://github.com/agenticubed/a3/blob/main/backend/app/services/execution_service.py"
click node_lifecycle "https://github.com/agenticubed/a3/blob/main/backend/app/orchestration/state_machine/states.py"
click node_providers "https://github.com/agenticubed/a3/blob/main/backend/app/orchestration/adapters/registry.py"
click node_workflow_engine "https://github.com/agenticubed/a3/blob/main/backend/app/orchestration/engines.py"
click node_worker "https://github.com/agenticubed/a3/blob/main/backend/app/workers/tasks.py"
click node_evaluation "https://github.com/agenticubed/a3/blob/main/backend/app/evaluation/specs.py"
click node_remediation "https://github.com/agenticubed/a3/blob/main/backend/app/remediation/policy.py"
click node_approval "https://github.com/agenticubed/a3/blob/main/backend/app/services/approval_service.py"
click node_audit "https://github.com/agenticubed/a3/blob/main/backend/app/core/audit.py"
click node_analytics "https://github.com/agenticubed/a3/blob/main/backend/app/analytics/compute.py"
click node_closeout "https://github.com/agenticubed/a3/blob/main/backend/app/services/closeout_service.py"
click node_content_entry "https://github.com/agenticubed/a3/blob/main/bananers/src/content/main.js"
click node_banner_detection "https://github.com/agenticubed/a3/blob/main/bananers/src/core/detect.js"
click node_dismissal "https://github.com/agenticubed/a3/blob/main/bananers/src/core/dismiss.js"
click node_extension_store "https://github.com/agenticubed/a3/blob/main/bananers/src/shared/store.js"

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_webui,node_api,node_user toneBlue
class node_project_intake,node_methodology,node_decomposition,node_capabilities,node_matching,node_agent_registry toneAmber
class node_execution,node_lifecycle,node_providers,node_workflow_engine,node_worker,node_evaluation,node_remediation toneMint
class node_approval,node_audit,node_analytics,node_closeout toneRose
class node_content_entry,node_banner_detection,node_dismissal,node_extension_store toneIndigo
```

## Components

### User experience

- [Project UI](https://github.com/agenticubed/a3/tree/main/frontend/src/app): `frontend/src/app`
- [Versioned API](https://github.com/agenticubed/a3/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`

### Planning and assignment

- [Project intake](https://github.com/agenticubed/a3/blob/main/backend/app/services/project_service.py): `backend/app/services/project_service.py`
- [Methodology](https://github.com/agenticubed/a3/blob/main/backend/app/services/methodology.py): `backend/app/services/methodology.py`
- [Work decomposition](https://github.com/agenticubed/a3/blob/main/backend/app/services/decomposition_service.py): `backend/app/services/decomposition_service.py`
- [Capability analysis](https://github.com/agenticubed/a3/blob/main/backend/app/core/capabilities.py): `backend/app/core/capabilities.py`
- [Agent matching](https://github.com/agenticubed/a3/blob/main/backend/app/services/matching.py): `backend/app/services/matching.py`
- [Agent registry](https://github.com/agenticubed/a3/blob/main/backend/app/services/agent_service.py): `backend/app/services/agent_service.py`

### Execution and evaluation

- [Task execution](https://github.com/agenticubed/a3/blob/main/backend/app/services/execution_service.py): `backend/app/services/execution_service.py`
- [Execution lifecycle](https://github.com/agenticubed/a3/blob/main/backend/app/orchestration/state_machine/states.py): `backend/app/orchestration/state_machine/states.py`
- [Provider adapters](https://github.com/agenticubed/a3/blob/main/backend/app/orchestration/adapters/registry.py): `backend/app/orchestration/adapters/registry.py`
- [Workflow engine](https://github.com/agenticubed/a3/blob/main/backend/app/orchestration/engines.py): `backend/app/orchestration/engines.py`
- [Celery worker](https://github.com/agenticubed/a3/blob/main/backend/app/workers/tasks.py): `backend/app/workers/tasks.py`
- [Output evaluation](https://github.com/agenticubed/a3/blob/main/backend/app/evaluation/specs.py): `backend/app/evaluation/specs.py`
- [Remediation policy](https://github.com/agenticubed/a3/blob/main/backend/app/remediation/policy.py): `backend/app/remediation/policy.py`

### Governance and reporting

- [Human approval](https://github.com/agenticubed/a3/blob/main/backend/app/services/approval_service.py): `backend/app/services/approval_service.py`
- [Audit and events](https://github.com/agenticubed/a3/blob/main/backend/app/core/audit.py): `backend/app/core/audit.py`
- [Analytics](https://github.com/agenticubed/a3/blob/main/backend/app/analytics/compute.py): `backend/app/analytics/compute.py`
- [Project closeout](https://github.com/agenticubed/a3/blob/main/backend/app/services/closeout_service.py): `backend/app/services/closeout_service.py`

### Banner extension

- [Content detector](https://github.com/agenticubed/a3/blob/main/bananers/src/content/main.js): `bananers/src/content/main.js`
- [Banner detection](https://github.com/agenticubed/a3/blob/main/bananers/src/core/detect.js): `bananers/src/core/detect.js`
- [Dismissal planner](https://github.com/agenticubed/a3/blob/main/bananers/src/core/dismiss.js): `bananers/src/core/dismiss.js`
- [Extension storage](https://github.com/agenticubed/a3/blob/main/bananers/src/shared/store.js): `bananers/src/shared/store.js`

### Other components

- **Project user**

## Connections

- Project user → Project UI: uses
- Project UI → Versioned API: requests
- Versioned API → Project intake: handles intake
- Project intake → Methodology: recommends (evidence: `README.md`)
- Methodology → Work decomposition: plans work (evidence: `README.md`)
- Work decomposition → Capability analysis: identifies needs (evidence: `README.md`)
- Capability analysis → Agent matching: informs assignment (evidence: `README.md`)
- Agent matching → Agent registry: selects agents (evidence: `README.md`)
- Agent registry → Task execution: assigned work (evidence: `README.md`)
- Task execution → Output evaluation: evaluates outputs (evidence: `README.md`)
- Output evaluation → Remediation policy: identifies gaps (evidence: `README.md`)
- Remediation policy → Task execution: re-executes (evidence: `README.md`)
- Task execution → Execution lifecycle: uses states (evidence: `backend/app/services/execution_service.py`)
- Task execution → Provider adapters: selects adapter (evidence: `backend/app/services/execution_service.py`)
- Task execution → Workflow engine: dispatches work (evidence: `backend/app/services/execution_service.py`)
- Workflow engine → Celery worker: queues execution (evidence: `backend/app/orchestration/engines.py`)
- Celery worker → Task execution: runs task (evidence: `backend/app/workers/tasks.py`)
- Task execution → Human approval: requests approval
- Task execution → Audit and events: records changes (evidence: `backend/app/services/execution_service.py`)
- Audit and events → Extension storage: publishes events
- Versioned API → Analytics: serves reporting
- Human approval → Project closeout: supports acceptance (evidence: `README.md`)
- Content detector → Banner detection: finds banners (evidence: `bananers/src/content/main.js`)
- Content detector → Dismissal planner: plans dismissal (evidence: `bananers/src/content/main.js`)
- Content detector → Extension storage: stores learning (evidence: `bananers/src/content/main.js`)