# astroicers/athena architecture

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

- Interactive diagram: https://gitdiagram.com/astroicers/athena
- Repository: https://github.com/astroicers/athena

## Overview

#### 1. Repository Role
This is the public product-facing repository for Athena, an autonomous cyber-operations platform. The production Rust OODA core (`athena-core`) is private; this repo exposes architecture documentation, extension guidance, a sample tool manifest, and a CI contract checker. Primary onboarding starts at `README.md`, with operational/API details in `docs/http-api.md`.

#### 2. Autonomous OODA Control Plane
Athena’s intended core flow is Observe → Orient → Decide → Act, continuously using newly collected facts to select subsequent actions. Orient is LLM-driven with a deterministic fallback; Decide applies mandatory scope, OPSEC-budget, and Rules-of-Engagement gates before execution. This repository documents rather than implements that private control plane:
- `README.md`
- `docs/demo-walkthrough.md`
- `docs/http-api.md`

#### 3. External API and Operational State Boundary
The documented stable HTTP surface covers operations, OODA phases, scheduling, facts, knowledge base, vulnerabilities, campaigns, reports, and status. This is the principal integration boundary for operators or control systems; the README explicitly distinguishes planned inbound MCP-server control from current delivered functionality.
- `docs/http-api.md`
- `README.md`

#### 4. Extensibility and Decision Plugins
The open ecosystem separates public contracts from private decision implementations. External developers provide deterministic scoring/selection behavior through the SDK contract, enabling hot-swappable decision modules without core source access. The repository includes a Rust-based validation executable for scorer contracts.
- `docs/extending.md`
- `ci/scorer-check/Cargo.toml`
- `ci/scorer-check/src/main.rs`

#### 5. MCP Tool-Container Integration
Athena orchestrates security-tool containers through MCP. Tool capabilities are declared through manifests, then reviewed, deployed through operator opt-in, discovered during Orient, and scheduled by the core. The local sample defines a tool’s container, port, ATT&CK techniques, description, and intended OODA phase.
- `examples/my-tool/athena-tool.toml`
- `docs/extending.md`
- `README.md`

#### 6. Runtime, Deployment, and External Dependencies
The private v2 core is described as a modular Rust workspace; the public checker is also Rust/Cargo. Decision intelligence can use hosted, local, or mock LLM backends. Local LLM support and MCP container orchestration enable air-gapped deployment; tool containers represent the main execution-side infrastructure.
- `docs/llm-config.md`
- `ci/scorer-check/Cargo.toml`
- `README.md`

#### 7. Governance and Delivery Controls
Compliance is designed as an execution-path boundary rather than post-run auditing: target scope, OPSEC noise budget, RoE policy, and human review for high-risk/suspected-honeypot actions. CI enforces published contracts and documentation quality, including scorer validation, link checking, and leak gates.
- `.github/workflows/contracts.yml`
- `.github/scripts/leak-gate.sh`
- `.github/scripts/check-links.sh`

Main entry points: [`README.md`](https://github.com/astroicers/athena/blob/main/README.md) (Product onboarding), [`.github/workflows/contracts.yml`](https://github.com/astroicers/athena/blob/main/.github/workflows/contracts.yml) (Contracts workflow), [`docs/extending.md`](https://github.com/astroicers/athena/blob/main/docs/extending.md) (Extension guide), [`docs/http-api.md`](https://github.com/astroicers/athena/blob/main/docs/http-api.md) (Stable HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public contracts"]
  node_readme["Product onboarding<br/>documentation<br/>[README.md]"]
  node_http_api["Stable HTTP API<br/>API contract<br/>[http-api.md]"]
  node_walkthrough["OODA walkthrough<br/>documentation"]
  node_extension_guide["Extension guide<br/>documentation<br/>[extending.md]"]
  node_llm_config["LLM deployment options<br/>documentation<br/>[llm-config.md]"]
  node_tool_manifest["Sample tool manifest<br/>MCP manifest<br/>[athena-tool.toml]"]
  node_decision_plugins["Decision plugins<br/>SDK contract<br/>[extending.md]"]
end

subgraph group_control["Private control plane"]
  node_private_core{{"athena-core<br/>private Rust workspace"}}
  node_observe["Observe<br/>OODA phase"]
  node_orient["Orient<br/>OODA phase"]
  node_decide["Decide<br/>OODA phase"]
  node_act["Act<br/>OODA phase"]
  node_governance{{"Execution governance<br/>policy gates"}}
  node_mcp_containers["MCP tool containers<br/>execution infrastructure"]
end

subgraph group_delivery["Delivery controls"]
  node_scorer_checker["Scorer contract checker<br/>Rust CI executable<br/>[main.rs]"]
  node_checker_cargo["Checker package<br/>Cargo manifest<br/>[Cargo.toml]"]
  node_contracts_ci["Contracts workflow<br/>GitHub Actions workflow<br/>[contracts.yml]"]
  node_leak_gate["Leak gate<br/>CI script<br/>[leak-gate.sh]"]
  node_link_check["Link checker<br/>CI script<br/>[check-links.sh]"]
end

node_readme -->|"links to"| node_http_api
node_readme -->|"introduces"| node_walkthrough
node_readme -->|"directs extensions to"| node_extension_guide
node_http_api -.->|"documents boundary for"| node_private_core
node_walkthrough -.->|"documents behavior of"| node_private_core
node_private_core -->|"runs"| node_observe
node_observe -->|"facts"| node_orient
node_orient -->|"candidate actions"| node_decide
node_decide -->|"must pass"| node_governance
node_governance -->|"approves"| node_act
node_act -->|"new facts"| node_observe
node_decision_plugins -.->|"provides scoring"| node_orient
node_extension_guide -->|"defines"| node_decision_plugins
node_tool_manifest -->|"declares"| node_mcp_containers
node_extension_guide -->|"guides authoring"| node_tool_manifest
node_orient -->|"discovers capabilities"| node_mcp_containers
node_act -->|"orchestrates"| node_mcp_containers
node_llm_config -.->|"configures backends"| node_orient
node_checker_cargo -->|"builds"| node_scorer_checker
node_contracts_ci -->|"runs"| node_scorer_checker
node_contracts_ci -->|"runs"| node_leak_gate
node_contracts_ci -->|"runs"| node_link_check

click node_readme "https://github.com/astroicers/athena/blob/main/README.md"
click node_http_api "https://github.com/astroicers/athena/blob/main/docs/http-api.md"
click node_walkthrough "https://github.com/astroicers/athena/blob/main/docs/demo-walkthrough.md"
click node_extension_guide "https://github.com/astroicers/athena/blob/main/docs/extending.md"
click node_llm_config "https://github.com/astroicers/athena/blob/main/docs/llm-config.md"
click node_tool_manifest "https://github.com/astroicers/athena/blob/main/examples/my-tool/athena-tool.toml"
click node_decision_plugins "https://github.com/astroicers/athena/blob/main/docs/extending.md"
click node_scorer_checker "https://github.com/astroicers/athena/blob/main/ci/scorer-check/src/main.rs"
click node_checker_cargo "https://github.com/astroicers/athena/blob/main/ci/scorer-check/Cargo.toml"
click node_contracts_ci "https://github.com/astroicers/athena/blob/main/.github/workflows/contracts.yml"
click node_leak_gate "https://github.com/astroicers/athena/blob/main/.github/scripts/leak-gate.sh"
click node_link_check "https://github.com/astroicers/athena/blob/main/.github/scripts/check-links.sh"

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_readme,node_http_api,node_walkthrough,node_extension_guide,node_llm_config,node_tool_manifest,node_decision_plugins toneBlue
class node_private_core,node_observe,node_orient,node_decide,node_act,node_governance,node_mcp_containers toneAmber
class node_scorer_checker,node_checker_cargo,node_contracts_ci,node_leak_gate,node_link_check toneMint
```

## Components

### Public contracts

Documentation and extension artifacts published in this repository.

- [Product onboarding](https://github.com/astroicers/athena/blob/main/README.md): documentation · Entry point for platform capabilities and current boundaries. · `README.md`
- [Stable HTTP API](https://github.com/astroicers/athena/blob/main/docs/http-api.md): API contract · Operator integration surface for operations, state, campaigns, and reports. · `docs/http-api.md`
- [OODA walkthrough](https://github.com/astroicers/athena/blob/main/docs/demo-walkthrough.md): documentation · `docs/demo-walkthrough.md`
- [Extension guide](https://github.com/astroicers/athena/blob/main/docs/extending.md): documentation · Defines decision-plugin and MCP tool extension workflows. · `docs/extending.md`
- [LLM deployment options](https://github.com/astroicers/athena/blob/main/docs/llm-config.md): documentation · Hosted, local, and mock backend guidance. · `docs/llm-config.md`
- [Sample tool manifest](https://github.com/astroicers/athena/blob/main/examples/my-tool/athena-tool.toml): MCP manifest · Declares container, port, ATT&CK techniques, and OODA phase. · `examples/my-tool/athena-tool.toml`
- [Decision plugins](https://github.com/astroicers/athena/blob/main/docs/extending.md): SDK contract · Hot-swappable deterministic scoring and selection modules. · `docs/extending.md`

### Private control plane

Documented behavior implemented by the private athena-core.

- **athena-core**: private Rust workspace · Production autonomous cyber-operations runtime.
- **Observe**: OODA phase · Collects operational facts.
- **Orient**: OODA phase · Uses LLM reasoning with deterministic fallback.
- **Decide**: OODA phase · Applies mandatory execution gates.
- **Act**: OODA phase · Schedules approved tool execution.
- **Execution governance**: policy gates · Scope, OPSEC budget, RoE, and human review constrain actions.
- **MCP tool containers**: execution infrastructure · Operator-opt-in security tools orchestrated by the core.

### Delivery controls

Automated checks protecting published contracts.

- [Scorer contract checker](https://github.com/astroicers/athena/blob/main/ci/scorer-check/src/main.rs): Rust CI executable · Validates published scorer contracts. · `ci/scorer-check/src/main.rs`
- [Checker package](https://github.com/astroicers/athena/blob/main/ci/scorer-check/Cargo.toml): Cargo manifest · `ci/scorer-check/Cargo.toml`
- [Contracts workflow](https://github.com/astroicers/athena/blob/main/.github/workflows/contracts.yml): GitHub Actions workflow · Runs contract and documentation quality checks. · `.github/workflows/contracts.yml`
- [Leak gate](https://github.com/astroicers/athena/blob/main/.github/scripts/leak-gate.sh): CI script · `.github/scripts/leak-gate.sh`
- [Link checker](https://github.com/astroicers/athena/blob/main/.github/scripts/check-links.sh): CI script · `.github/scripts/check-links.sh`

## Connections

- Product onboarding → Stable HTTP API: links to
- Product onboarding → OODA walkthrough: introduces
- Product onboarding → Extension guide: directs extensions to
- Stable HTTP API → athena-core: documents boundary for
- OODA walkthrough → athena-core: documents behavior of
- athena-core → Observe: runs
- Observe → Orient: facts
- Orient → Decide: candidate actions
- Decide → Execution governance: must pass
- Execution governance → Act: approves
- Act → Observe: new facts
- Decision plugins → Orient: provides scoring
- Extension guide → Decision plugins: defines
- Sample tool manifest → MCP tool containers: declares
- Extension guide → Sample tool manifest: guides authoring
- Orient → MCP tool containers: discovers capabilities
- Act → MCP tool containers: orchestrates
- LLM deployment options → Orient: configures backends
- Checker package → Scorer contract checker: builds
- Contracts workflow → Scorer contract checker: runs
- Contracts workflow → Leak gate: runs
- Contracts workflow → Link checker: runs