# harery/octalume architecture

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

- Interactive diagram: https://gitdiagram.com/harery/octalume
- Repository: https://github.com/harery/octalume

## Overview

OCTALUME is a gate-driven enterprise SDLC framework: a project can begin with the Phase 0 idea pipeline, then progress through eight lifecycle phases, producing traceable artifacts and advancing only when quality gates pass. Users operate it through the CLI, MCP tools, or a web dashboard. The phase engine coordinates state, gates, and agent orchestration; compliance scanning and persistent memory support governance. The graph reflects README-documented capabilities where implementation was not sampled; those links are omitted when wiring is uncertain.

Main entry points: [`web/backend/main.py`](https://github.com/harery/octalume/blob/main/web/backend/main.py) (FastAPI Backend), [`octalume/core/engine.py`](https://github.com/harery/octalume/blob/main/octalume/core/engine.py) (Phase Engine), [`octalume/cli.py`](https://github.com/harery/octalume/blob/main/octalume/cli.py) (CLI), [`octalume/mcp/server.py`](https://github.com/harery/octalume/blob/main/octalume/mcp/server.py) (MCP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_mcp_server["MCP Server<br/>[server.py]"]
end

subgraph group_lifecycle["Lifecycle Core"]
  node_engine["Phase Engine<br/>[engine.py]"]
  node_gates["Quality Gates<br/>[gates.py]"]
  node_state[("Project State<br/>[state.py]")]
  node_memory[("Memory Bank<br/>[memory.py]")]
end

subgraph group_agents["Agent System"]
  node_core_orchestrator["Agent Orchestrator<br/>[orchestrator.py]"]
  node_phase_agents["Phase Agents"]
  node_a2a["Agent Messaging<br/>[protocol.py]"]
  node_message_bus["Message Bus<br/>[messaging.py]"]
end

subgraph group_governance["Governance"]
  node_compliance_scanner["Compliance Scanner<br/>[scanner.py]"]
  node_compliance_standards["Compliance Catalogs"]
end

subgraph group_idea["Idea Pipeline"]
  node_idea_parser["Idea Parser<br/>[parser.py]"]
  node_idea_pipeline["12-Stage Pipeline<br/>[pipeline.py]"]
  node_idea_outputs["Plan Artifacts"]
end

subgraph group_dashboard["Web Dashboard"]
  node_web_frontend["Web Frontend<br/>[App.tsx]"]
  node_api_client["API Client<br/>[api.ts]"]
  node_backend["FastAPI Backend<br/>[main.py]"]
  node_phase_routes["Phase Routes<br/>[phases.py]"]
  node_agent_routes["Agent Routes<br/>[agents.py]"]
  node_artifact_routes["Artifact Routes<br/>[artifacts.py]"]
  node_compliance_routes["Compliance Routes<br/>[compliance.py]"]
  node_dashboard_routes["Dashboard Routes<br/>[dashboard.py]"]
end

node_user(("Project User"))
node_mcp_client(("MCP Client"))
node_browser(("Browser User"))

node_user -->|"runs commands"| node_cli
node_mcp_client -->|"invokes tools"| node_mcp_server
node_browser -->|"uses dashboard"| node_web_frontend
node_web_frontend -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_backend
node_backend -->|"routes requests"| node_phase_routes
node_backend -->|"routes requests"| node_agent_routes
node_backend -->|"routes requests"| node_artifact_routes
node_backend -->|"routes requests"| node_compliance_routes
node_backend -->|"routes requests"| node_dashboard_routes
node_cli -->|"manages phases"| node_engine
node_mcp_server -->|"manages phases"| node_engine
node_mcp_server -->|"runs scans"| node_compliance_scanner
node_mcp_server -->|"stores memory"| node_memory
node_engine -->|"validates transitions"| node_gates
node_engine -->|"loads and saves"| node_state
node_engine -->|"coordinates agents"| node_core_orchestrator
node_core_orchestrator -->|"saves agent state"| node_state
node_core_orchestrator -->|"sends messages"| node_a2a
node_a2a -->|"dispatches messages"| node_message_bus
node_core_orchestrator -->|"assigns phase work"| node_phase_agents
node_compliance_scanner -->|"checks controls"| node_compliance_standards
node_cli -->|"parses idea"| node_idea_parser
node_cli -->|"requests stages"| node_idea_pipeline
node_idea_pipeline -->|"defines outputs"| node_idea_outputs

click node_cli "https://github.com/harery/octalume/blob/main/octalume/cli.py"
click node_mcp_server "https://github.com/harery/octalume/blob/main/octalume/mcp/server.py"
click node_web_frontend "https://github.com/harery/octalume/blob/main/web/frontend/src/App.tsx"
click node_api_client "https://github.com/harery/octalume/blob/main/web/frontend/src/lib/api.ts"
click node_backend "https://github.com/harery/octalume/blob/main/web/backend/main.py"
click node_phase_routes "https://github.com/harery/octalume/blob/main/web/backend/routers/phases.py"
click node_agent_routes "https://github.com/harery/octalume/blob/main/web/backend/routers/agents.py"
click node_artifact_routes "https://github.com/harery/octalume/blob/main/web/backend/routers/artifacts.py"
click node_compliance_routes "https://github.com/harery/octalume/blob/main/web/backend/routers/compliance.py"
click node_dashboard_routes "https://github.com/harery/octalume/blob/main/web/backend/routers/dashboard.py"
click node_engine "https://github.com/harery/octalume/blob/main/octalume/core/engine.py"
click node_gates "https://github.com/harery/octalume/blob/main/octalume/core/gates.py"
click node_state "https://github.com/harery/octalume/blob/main/octalume/core/state.py"
click node_memory "https://github.com/harery/octalume/blob/main/octalume/core/memory.py"
click node_core_orchestrator "https://github.com/harery/octalume/blob/main/octalume/core/orchestrator.py"
click node_phase_agents "https://github.com/harery/octalume/tree/main/octalume/agents"
click node_a2a "https://github.com/harery/octalume/blob/main/octalume/a2a/protocol.py"
click node_message_bus "https://github.com/harery/octalume/blob/main/octalume/a2a/messaging.py"
click node_compliance_scanner "https://github.com/harery/octalume/blob/main/octalume/compliance/scanner.py"
click node_compliance_standards "https://github.com/harery/octalume/tree/main/octalume/compliance"
click node_idea_parser "https://github.com/harery/octalume/blob/main/octalume/idea/parser.py"
click node_idea_pipeline "https://github.com/harery/octalume/blob/main/octalume/idea/pipeline.py"
click node_idea_outputs "https://github.com/harery/octalume/tree/main/octalume/idea"

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_cli,node_mcp_server,node_user,node_mcp_client,node_browser toneBlue
class node_engine,node_gates,node_state,node_memory toneAmber
class node_core_orchestrator,node_phase_agents,node_a2a,node_message_bus toneMint
class node_compliance_scanner,node_compliance_standards toneRose
class node_idea_parser,node_idea_pipeline,node_idea_outputs toneIndigo
class node_web_frontend,node_api_client,node_backend,node_phase_routes,node_agent_routes,node_artifact_routes,node_compliance_routes,node_dashboard_routes toneTeal
```

## Components

### User Interfaces

- [CLI](https://github.com/harery/octalume/blob/main/octalume/cli.py): `octalume/cli.py`
- [MCP Server](https://github.com/harery/octalume/blob/main/octalume/mcp/server.py): `octalume/mcp/server.py`

### Lifecycle Core

- [Phase Engine](https://github.com/harery/octalume/blob/main/octalume/core/engine.py): `octalume/core/engine.py`
- [Quality Gates](https://github.com/harery/octalume/blob/main/octalume/core/gates.py): `octalume/core/gates.py`
- [Project State](https://github.com/harery/octalume/blob/main/octalume/core/state.py): `octalume/core/state.py`
- [Memory Bank](https://github.com/harery/octalume/blob/main/octalume/core/memory.py): `octalume/core/memory.py`

### Agent System

- [Agent Orchestrator](https://github.com/harery/octalume/blob/main/octalume/core/orchestrator.py): `octalume/core/orchestrator.py`
- [Phase Agents](https://github.com/harery/octalume/tree/main/octalume/agents): `octalume/agents`
- [Agent Messaging](https://github.com/harery/octalume/blob/main/octalume/a2a/protocol.py): `octalume/a2a/protocol.py`
- [Message Bus](https://github.com/harery/octalume/blob/main/octalume/a2a/messaging.py): `octalume/a2a/messaging.py`

### Governance

- [Compliance Scanner](https://github.com/harery/octalume/blob/main/octalume/compliance/scanner.py): `octalume/compliance/scanner.py`
- [Compliance Catalogs](https://github.com/harery/octalume/tree/main/octalume/compliance): `octalume/compliance`

### Idea Pipeline

- [Idea Parser](https://github.com/harery/octalume/blob/main/octalume/idea/parser.py): `octalume/idea/parser.py`
- [12-Stage Pipeline](https://github.com/harery/octalume/blob/main/octalume/idea/pipeline.py): `octalume/idea/pipeline.py`
- [Plan Artifacts](https://github.com/harery/octalume/tree/main/octalume/idea): `octalume/idea`

### Web Dashboard

- [Web Frontend](https://github.com/harery/octalume/blob/main/web/frontend/src/App.tsx): `web/frontend/src/App.tsx`
- [API Client](https://github.com/harery/octalume/blob/main/web/frontend/src/lib/api.ts): `web/frontend/src/lib/api.ts`
- [FastAPI Backend](https://github.com/harery/octalume/blob/main/web/backend/main.py): `web/backend/main.py`
- [Phase Routes](https://github.com/harery/octalume/blob/main/web/backend/routers/phases.py): `web/backend/routers/phases.py`
- [Agent Routes](https://github.com/harery/octalume/blob/main/web/backend/routers/agents.py): `web/backend/routers/agents.py`
- [Artifact Routes](https://github.com/harery/octalume/blob/main/web/backend/routers/artifacts.py): `web/backend/routers/artifacts.py`
- [Compliance Routes](https://github.com/harery/octalume/blob/main/web/backend/routers/compliance.py): `web/backend/routers/compliance.py`
- [Dashboard Routes](https://github.com/harery/octalume/blob/main/web/backend/routers/dashboard.py): `web/backend/routers/dashboard.py`

### Other components

- **Project User**
- **MCP Client**
- **Browser User**

## Connections

- Project User → CLI: runs commands
- MCP Client → MCP Server: invokes tools
- Browser User → Web Frontend: uses dashboard
- Web Frontend → API Client: requests data
- API Client → FastAPI Backend: calls API
- FastAPI Backend → Phase Routes: routes requests
- FastAPI Backend → Agent Routes: routes requests
- FastAPI Backend → Artifact Routes: routes requests
- FastAPI Backend → Compliance Routes: routes requests
- FastAPI Backend → Dashboard Routes: routes requests
- CLI → Phase Engine: manages phases
- MCP Server → Phase Engine: manages phases
- MCP Server → Compliance Scanner: runs scans
- MCP Server → Memory Bank: stores memory
- Phase Engine → Quality Gates: validates transitions
- Phase Engine → Project State: loads and saves
- Phase Engine → Agent Orchestrator: coordinates agents
- Agent Orchestrator → Project State: saves agent state
- Agent Orchestrator → Agent Messaging: sends messages
- Agent Messaging → Message Bus: dispatches messages
- Agent Orchestrator → Phase Agents: assigns phase work
- Compliance Scanner → Compliance Catalogs: checks controls
- CLI → Idea Parser: parses idea
- CLI → 12-Stage Pipeline: requests stages
- 12-Stage Pipeline → Plan Artifacts: defines outputs