# duckz289/maf architecture

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

- Interactive diagram: https://gitdiagram.com/duckz289/maf
- Repository: https://github.com/duckz289/maf

## Overview

Adaptive Agent Harness is a local-first control plane for running coding tasks through native agents, while preserving their own planning and context loops. A user submits a repository task through the dashboard or API; the run service compiles its mission, executes it in an isolated worktree, gathers runtime evidence, and applies verification and bounded recovery policy. Results and operational state feed the dashboard. The README also documents repository knowledge, provider and agent connections, telemetry, health/evolution views, and benchmarking. Several links reflect documented capabilities rather than inspected wiring; those are left unconnected where ownership is uncertain.

Main entry points: [`src/application/run-service.ts`](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/run-service.ts) (Run Service), [`src/server/app.ts`](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/server/app.ts) (HTTP API), [`src/web/App.tsx`](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/web/App.tsx) (Operations Dashboard), [`src/infrastructure/model-gateway.ts`](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/model-gateway.ts) (Native Agent Gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_dashboard["Operations Dashboard<br/>[App.tsx]"]
  node_server["HTTP API<br/>[app.ts]"]
end

subgraph group_execution["Run Execution"]
  node_runservice["Run Service<br/>[run-service.ts]"]
  node_mission["Mission Compiler"]
  node_worktree["Isolated Worktree<br/>[local-worktree.ts]"]
  node_verification["Verification<br/>[verifier.ts]"]
  node_capabilities["Capability Execution"]
end

subgraph group_intelligence["Runtime Intelligence"]
  node_mode["Adaptive Mode Policy<br/>[mode-controller.ts]"]
  node_signals["Runtime Signal Collector"]
  node_knowledge["Repository Knowledge"]
  node_brain[("Project Brain<br/>[project-brain.ts]")]
end

subgraph group_integrations["Integrations"]
  node_agentgateway["Native Agent Gateway<br/>[model-gateway.ts]"]
  node_agentadapters["Agent Adapters"]
  node_providerconnections["Provider Connections"]
end

subgraph group_operations["Operations"]
  node_store[("Run State Store<br/>[memory-store.ts]")]
  node_postgres[("PostgreSQL Store<br/>[store.ts]")]
  node_telemetry["Telemetry<br/>[telemetry.ts]"]
  node_evaluation["Benchmark Evaluation"]
  node_controlcenter["Control Center<br/>[control-center.ts]"]
end

node_user(("User"))
node_nativecli["Installed Agent CLI"]

node_user -->|"submits task"| node_dashboard
node_dashboard -->|"calls API"| node_server
node_server -->|"creates run"| node_runservice
node_runservice -->|"compiles mission"| node_mission
node_runservice -->|"isolates changes"| node_worktree
node_runservice -->|"executes capabilities"| node_capabilities
node_runservice -->|"persists knowledge"| node_knowledge
node_runservice -->|"collects evidence"| node_signals
node_runservice -->|"decides mode"| node_mode
node_runservice -->|"verifies candidate"| node_verification
node_runservice -->|"runs agent"| node_agentgateway
node_agentgateway -->|"dispatches"| node_agentadapters
node_agentadapters -->|"invokes"| node_nativecli
node_server -->|"manages connections"| node_providerconnections
node_runservice -->|"stores project knowledge"| node_brain
node_server -->|"reads and writes runs"| node_store
node_server -.->|"uses durable state"| node_postgres
node_server -->|"serves cost metrics"| node_telemetry
node_user -->|"requests benchmark"| node_evaluation
node_server -->|"serves operations views"| node_controlcenter
node_dashboard -->|"displays operations"| node_controlcenter

click node_dashboard "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/web/App.tsx"
click node_server "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/server/app.ts"
click node_runservice "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/run-service.ts"
click node_mission "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/mission-compiler.ts"
click node_worktree "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/local-worktree.ts"
click node_mode "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/domain/mode-controller.ts"
click node_signals "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/runtime-signal-collector.ts"
click node_knowledge "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/project-knowledge.ts"
click node_verification "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/verifier.ts"
click node_capabilities "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/capability-execution.ts"
click node_agentgateway "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/model-gateway.ts"
click node_agentadapters "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/native-cli-adapter.ts"
click node_providerconnections "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/provider-connections.ts"
click node_brain "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/project-brain.ts"
click node_store "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/memory-store.ts"
click node_postgres "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/postgres/store.ts"
click node_telemetry "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/telemetry.ts"
click node_evaluation "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/evaluation/benchmark-bridge.ts"
click node_controlcenter "https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/control-center.ts"

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_dashboard,node_server,node_user toneBlue
class node_runservice,node_mission,node_worktree,node_verification,node_capabilities toneAmber
class node_mode,node_signals,node_knowledge,node_brain toneMint
class node_agentgateway,node_agentadapters,node_providerconnections toneRose
class node_store,node_postgres,node_telemetry,node_evaluation,node_controlcenter,node_nativecli toneIndigo
```

## Components

### User Interfaces

- [Operations Dashboard](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/web/App.tsx): `src/web/App.tsx`
- [HTTP API](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/server/app.ts): `src/server/app.ts`

### Run Execution

- [Run Service](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/run-service.ts): `src/application/run-service.ts`
- [Mission Compiler](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/mission-compiler.ts): `src/application/mission-compiler.ts`
- [Isolated Worktree](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/local-worktree.ts): `src/infrastructure/local-worktree.ts`
- [Verification](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/verifier.ts): `src/infrastructure/verifier.ts`
- [Capability Execution](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/capability-execution.ts): `src/application/capability-execution.ts`

### Runtime Intelligence

- [Adaptive Mode Policy](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/domain/mode-controller.ts): `src/domain/mode-controller.ts`
- [Runtime Signal Collector](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/runtime-signal-collector.ts): `src/application/runtime-signal-collector.ts`
- [Repository Knowledge](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/project-knowledge.ts): `src/application/project-knowledge.ts`
- [Project Brain](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/project-brain.ts): `src/infrastructure/project-brain.ts`

### Integrations

- [Native Agent Gateway](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/model-gateway.ts): `src/infrastructure/model-gateway.ts`
- [Agent Adapters](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/native-cli-adapter.ts): `src/infrastructure/native-cli-adapter.ts`
- [Provider Connections](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/provider-connections.ts): `src/infrastructure/provider-connections.ts`

### Operations

- [Run State Store](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/memory-store.ts): `src/infrastructure/memory-store.ts`
- [PostgreSQL Store](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/postgres/store.ts): `src/infrastructure/postgres/store.ts`
- [Telemetry](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/infrastructure/telemetry.ts): `src/infrastructure/telemetry.ts`
- [Benchmark Evaluation](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/evaluation/benchmark-bridge.ts): `src/evaluation/benchmark-bridge.ts`
- [Control Center](https://github.com/duckz289/maf/blob/adaptive-harness/bootstrap/src/application/control-center.ts): `src/application/control-center.ts`

### Other components

- **User**
- **Installed Agent CLI**

## Connections

- User → Operations Dashboard: submits task
- Operations Dashboard → HTTP API: calls API
- HTTP API → Run Service: creates run
- Run Service → Mission Compiler: compiles mission
- Run Service → Isolated Worktree: isolates changes
- Run Service → Capability Execution: executes capabilities
- Run Service → Repository Knowledge: persists knowledge
- Run Service → Runtime Signal Collector: collects evidence
- Run Service → Adaptive Mode Policy: decides mode
- Run Service → Verification: verifies candidate
- Run Service → Native Agent Gateway: runs agent
- Native Agent Gateway → Agent Adapters: dispatches
- Agent Adapters → Installed Agent CLI: invokes
- HTTP API → Provider Connections: manages connections
- Run Service → Project Brain: stores project knowledge
- HTTP API → Run State Store: reads and writes runs
- HTTP API → PostgreSQL Store: uses durable state
- HTTP API → Telemetry: serves cost metrics
- User → Benchmark Evaluation: requests benchmark
- HTTP API → Control Center: serves operations views
- Operations Dashboard → Control Center: displays operations