# bharathraajnagarajan/governed-agent-exec architecture

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

- Interactive diagram: https://gitdiagram.com/bharathraajnagarajan/governed-agent-exec
- Repository: https://github.com/bharathraajnagarajan/governed-agent-exec

## Overview

GAX is a governed, durable incident-remediation system for a simulated streaming platform. An incident enters through the CLI and a Temporal workflow: runbook retrieval informs a Claude proposal, deterministic policy allows, denies, or requests approval, and approved actions are snapshotted, executed against fleet-api, verified, and audited. A separate durable ingestion workflow indexes runbooks for retrieval. The graph preserves the documented Keycard and LOCAL-ONLY credential modes and Voyage/MongoDB retrieval capabilities. Workflow relationships follow the README; source excerpts and the SOURCE INDEX support implementation-level links, while unsampled internals are not inferred.

Main entry points: [`src/gax/remediation/activities.py`](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/remediation/activities.py) (Remediation activities), [`src/gax/workflows.py`](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/workflows.py) (Temporal workflows), [`src/gax/retrieval/ingest.py`](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/retrieval/ingest.py) (Ingest activities), [`src/gax/retrieval/search.py`](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/retrieval/search.py) (Context search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Workflow orchestration"]
  node_cli["CLI<br/>[cli.py]"]
  node_workflow["Temporal workflows<br/>[workflows.py]"]
  node_worker["Worker runtime<br/>[worker.py]"]
end

subgraph group_remediation["Remediation domain"]
  node_types["Workflow types<br/>[types.py]"]
  node_activities["Remediation activities<br/>[activities.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_policy["Deterministic policy<br/>[rules.py]"]
  node_broker["Credential brokers"]
end

subgraph group_knowledge["Runbook retrieval"]
  node_ingest["Ingest activities<br/>[ingest.py]"]
  node_chunking["Corpus chunking<br/>[chunking.py]"]
  node_search["Context search<br/>[search.py]"]
  node_store["Retrieval store<br/>[store.py]"]
end

subgraph group_integrations["External systems"]
  node_fleet["Fleet API<br/>[app.py]"]
  node_mongo[("MongoDB")]
  node_voyage["Voyage AI"]
  node_claude["Claude"]
  node_temporal["Temporal"]
  node_keycard["Keycard"]
end

node_operator(("Operator"))

node_operator -->|"starts incident"| node_cli
node_cli -->|"starts workflow"| node_workflow
node_workflow -->|"runs durably"| node_temporal
node_worker -->|"registers workflows"| node_temporal
node_worker -->|"registers activities"| node_activities
node_workflow -->|"dispatches steps"| node_activities
node_workflow -->|"uses inputs"| node_types
node_activities -->|"validates proposals"| node_models
node_activities -->|"evaluates proposal"| node_policy
node_activities -->|"mints credentials"| node_broker
node_activities -->|"reads and mutates"| node_fleet
node_fleet -->|"stores fleet state"| node_mongo
node_activities -->|"records ledger"| node_mongo
node_activities -->|"writes audit"| node_mongo
node_workflow -->|"requests context"| node_search
node_activities -->|"calls search"| node_search
node_search -->|"queries vectors"| node_store
node_store -->|"reads and writes"| node_mongo
node_search -->|"embeds and reranks"| node_voyage
node_activities -->|"requests proposal"| node_claude
node_worker -->|"registers ingestion"| node_ingest
node_workflow -->|"dispatches ingestion"| node_ingest
node_ingest -->|"loads and batches"| node_chunking
node_ingest -->|"indexes chunks"| node_store
node_ingest -->|"embeds batches"| node_voyage
node_broker -.->|"mints tokens"| node_keycard
node_fleet -.->|"verifies JWKS"| node_keycard

click node_cli "https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/cli.py"
click node_workflow "https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/workflows.py"
click node_worker "https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/worker.py"
click node_types "https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/remediation/types.py"
click node_activities "https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/remediation/activities.py"
click node_models "https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/models.py"
click node_policy "https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/policy/rules.py"
click node_broker "https://github.com/bharathraajnagarajan/governed-agent-exec/tree/main/src/gax/credentials"
click node_fleet "https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/fleet_api/app.py"
click node_ingest "https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/retrieval/ingest.py"
click node_chunking "https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/retrieval/chunking.py"
click node_search "https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/retrieval/search.py"
click node_store "https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/retrieval/store.py"

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_workflow,node_worker toneBlue
class node_types,node_activities,node_models,node_policy,node_broker toneAmber
class node_ingest,node_chunking,node_search,node_store toneMint
class node_fleet,node_mongo,node_voyage,node_claude,node_temporal,node_keycard toneRose
class node_operator toneIndigo
```

## Components

### Workflow orchestration

- [CLI](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/cli.py): `src/gax/cli.py`
- [Temporal workflows](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/workflows.py): `src/gax/workflows.py`
- [Worker runtime](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/worker.py): `src/gax/worker.py`

### Remediation domain

- [Workflow types](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/remediation/types.py): `src/gax/remediation/types.py`
- [Remediation activities](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/remediation/activities.py): `src/gax/remediation/activities.py`
- [Domain models](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/models.py): `src/gax/models.py`
- [Deterministic policy](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/policy/rules.py): `src/gax/policy/rules.py`
- [Credential brokers](https://github.com/bharathraajnagarajan/governed-agent-exec/tree/main/src/gax/credentials): `src/gax/credentials`

### Runbook retrieval

- [Ingest activities](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/retrieval/ingest.py): `src/gax/retrieval/ingest.py`
- [Corpus chunking](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/retrieval/chunking.py): `src/gax/retrieval/chunking.py`
- [Context search](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/retrieval/search.py): `src/gax/retrieval/search.py`
- [Retrieval store](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/src/gax/retrieval/store.py): `src/gax/retrieval/store.py`

### External systems

- [Fleet API](https://github.com/bharathraajnagarajan/governed-agent-exec/blob/main/fleet_api/app.py): `fleet_api/app.py`
- **MongoDB**
- **Voyage AI**
- **Claude**
- **Temporal**
- **Keycard**

### Other components

- **Operator**

## Connections

- Operator → CLI: starts incident (evidence: `README.md`)
- CLI → Temporal workflows: starts workflow (evidence: `README.md`)
- Temporal workflows → Temporal: runs durably (evidence: `README.md`)
- Worker runtime → Temporal: registers workflows (evidence: `src/gax/worker.py`)
- Worker runtime → Remediation activities: registers activities (evidence: `src/gax/worker.py`)
- Temporal workflows → Remediation activities: dispatches steps (evidence: `README.md`)
- Temporal workflows → Workflow types: uses inputs (evidence: `src/gax/workflows.py`)
- Remediation activities → Domain models: validates proposals (evidence: `src/gax/remediation/activities.py`)
- Remediation activities → Deterministic policy: evaluates proposal (evidence: `src/gax/remediation/activities.py`)
- Remediation activities → Credential brokers: mints credentials (evidence: `README.md`)
- Remediation activities → Fleet API: reads and mutates (evidence: `src/gax/remediation/activities.py`)
- Fleet API → MongoDB: stores fleet state (evidence: `README.md`)
- Remediation activities → MongoDB: records ledger (evidence: `README.md`)
- Remediation activities → MongoDB: writes audit (evidence: `src/gax/remediation/activities.py`)
- Temporal workflows → Context search: requests context (evidence: `README.md`)
- Remediation activities → Context search: calls search (evidence: `src/gax/worker.py`)
- Context search → Retrieval store: queries vectors (evidence: `src/gax/retrieval/search.py`)
- Retrieval store → MongoDB: reads and writes (evidence: `src/gax/retrieval/store.py`)
- Context search → Voyage AI: embeds and reranks (evidence: `README.md`)
- Remediation activities → Claude: requests proposal (evidence: `README.md`)
- Worker runtime → Ingest activities: registers ingestion (evidence: `src/gax/worker.py`)
- Temporal workflows → Ingest activities: dispatches ingestion (evidence: `src/gax/workflows.py`)
- Ingest activities → Corpus chunking: loads and batches (evidence: `src/gax/retrieval/ingest.py`)
- Ingest activities → Retrieval store: indexes chunks (evidence: `src/gax/retrieval/ingest.py`)
- Ingest activities → Voyage AI: embeds batches (evidence: `README.md`)
- Credential brokers → Keycard: mints tokens (evidence: `README.md`)
- Fleet API → Keycard: verifies JWKS (evidence: `README.md`)
