# codecrafter001/terraform_agent architecture

> Architecture diagram of the GitHub repository codecrafter001/terraform_agent, 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/codecrafter001/terraform_agent
- Repository: https://github.com/codecrafter001/terraform_agent

## Overview

TerraAgent turns a user’s AWS migration or infrastructure request into discovered inventory, dependency and adoption plans, generated Terraform/OpenTofu, validation and security results, and downloadable artifacts. The frontend initiates scans and presents progress, approvals, and results; the API and job pipeline invoke the stateful agent graph, which can pause for human approval and resume. README-documented agent stages are included, but several agent implementations were not sampled, so those stage links cite the README rather than implying source inspection.

Main entry points: [`backend/agents/graph.py`](https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/graph.py) (Agent graph), [`backend/services/pipeline.py`](https://github.com/codecrafter001/terraform_agent/blob/main/backend/services/pipeline.py) (Pipeline coordinator), [`backend/routers/scan.py`](https://github.com/codecrafter001/terraform_agent/blob/main/backend/routers/scan.py) (Scan API), [`frontend/lib/api.ts`](https://github.com/codecrafter001/terraform_agent/blob/main/frontend/lib/api.ts) (Frontend API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["TerraAgent dashboard<br/>[page.tsx]"]
  node_results["Results and approval UI<br/>[ScanProgress.tsx]"]
  node_api_client["Frontend API client<br/>[api.ts]"]
end

subgraph group_api["API and jobs"]
  node_scan_api["Scan API<br/>[scan.py]"]
  node_job_worker["Background job runner<br/>[celery_app.py]"]
  node_pipeline["Pipeline coordinator<br/>[pipeline.py]"]
end

subgraph group_migration["Migration intelligence"]
  node_agent_graph{{"Agent graph<br/>[graph.py]"}}
  node_intent["Request intent<br/>[intent_router.py]"]
  node_discovery["AWS discovery<br/>[cloud_discovery.py]"]
  node_topology["Dependency topology<br/>[graph_agent.py]"]
  node_classification["Resource classification"]
  node_adoption["Adoption planning"]
  node_composer["IaC composition"]
end

subgraph group_delivery["Verification and delivery"]
  node_validation["Sandbox validation"]
  node_engine["Terraform and OpenTofu<br/>[iac_engine.py]"]
  node_policy["Policy and security<br/>[policy_agent.py]"]
  node_repair["Validation repair"]
  node_documentation["Reports and artifacts"]
  node_github_pr["GitHub adoption PR<br/>[github_client.py]"]
end

subgraph group_state["Persistence"]
  node_redis[("Live job state and logs<br/>[redis_client.py]")]
  node_database[("Job audit records<br/>[database.py]")]
end

node_user(("Engineer"))
node_approval(("Human reviewer"))
node_aws[("AWS estate")]

node_user -->|"submits request"| node_frontend
node_frontend -.->|"uses API"| node_api_client
node_api_client -.->|"requests scan"| node_scan_api
node_scan_api -->|"queues job"| node_job_worker
node_job_worker -->|"runs pipeline"| node_pipeline
node_pipeline -->|"runs graph"| node_agent_graph
node_agent_graph -->|"routes intent"| node_intent
node_agent_graph -->|"dispatches discovery"| node_discovery
node_discovery -->|"reads inventory"| node_aws
node_agent_graph -->|"dispatches graphing"| node_topology
node_agent_graph -->|"dispatches classification"| node_classification
node_agent_graph -->|"plans adoption"| node_adoption
node_agent_graph -->|"dispatches composition"| node_composer
node_agent_graph -->|"dispatches validation"| node_validation
node_validation -->|"executes checks"| node_engine
node_agent_graph -->|"dispatches policy checks"| node_policy
node_agent_graph -->|"retries repair"| node_repair
node_agent_graph -->|"produces artifacts"| node_documentation
node_pipeline -->|"publishes job state"| node_redis
node_pipeline -.->|"records job"| node_database
node_pipeline -->|"pauses for decision"| node_approval
node_approval -.->|"submits decision"| node_scan_api
node_scan_api -->|"reads status"| node_redis
node_results -.->|"loads results"| node_api_client
node_documentation -.->|"enables PR delivery"| node_github_pr

click node_frontend "https://github.com/codecrafter001/terraform_agent/blob/main/frontend/app/page.tsx"
click node_results "https://github.com/codecrafter001/terraform_agent/blob/main/frontend/components/ScanProgress.tsx"
click node_api_client "https://github.com/codecrafter001/terraform_agent/blob/main/frontend/lib/api.ts"
click node_scan_api "https://github.com/codecrafter001/terraform_agent/blob/main/backend/routers/scan.py"
click node_job_worker "https://github.com/codecrafter001/terraform_agent/blob/main/backend/services/celery_app.py"
click node_pipeline "https://github.com/codecrafter001/terraform_agent/blob/main/backend/services/pipeline.py"
click node_agent_graph "https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/graph.py"
click node_intent "https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/intent_router.py"
click node_discovery "https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/cloud_discovery.py"
click node_topology "https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/graph_agent.py"
click node_classification "https://github.com/codecrafter001/terraform_agent/blob/main/backend/tools/resource_classifier.py"
click node_adoption "https://github.com/codecrafter001/terraform_agent/blob/main/backend/tools/adoption_planner.py"
click node_composer "https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/terraform_composer.py"
click node_validation "https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/validation_agent.py"
click node_engine "https://github.com/codecrafter001/terraform_agent/blob/main/backend/tools/iac_engine.py"
click node_policy "https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/policy_agent.py"
click node_repair "https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/validation_repair.py"
click node_documentation "https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/documentation_agent.py"
click node_github_pr "https://github.com/codecrafter001/terraform_agent/blob/main/backend/services/github_client.py"
click node_redis "https://github.com/codecrafter001/terraform_agent/blob/main/backend/services/redis_client.py"
click node_database "https://github.com/codecrafter001/terraform_agent/blob/main/backend/services/database.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_frontend,node_results,node_api_client,node_approval toneBlue
class node_scan_api,node_job_worker,node_pipeline,node_aws toneAmber
class node_agent_graph,node_intent,node_discovery,node_topology,node_classification,node_adoption,node_composer toneMint
class node_validation,node_engine,node_policy,node_repair,node_documentation,node_github_pr toneRose
class node_redis,node_database,node_user toneIndigo
```

## Components

### User experience

- [TerraAgent dashboard](https://github.com/codecrafter001/terraform_agent/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Results and approval UI](https://github.com/codecrafter001/terraform_agent/blob/main/frontend/components/ScanProgress.tsx): `frontend/components/ScanProgress.tsx`
- [Frontend API client](https://github.com/codecrafter001/terraform_agent/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### API and jobs

- [Scan API](https://github.com/codecrafter001/terraform_agent/blob/main/backend/routers/scan.py): `backend/routers/scan.py`
- [Background job runner](https://github.com/codecrafter001/terraform_agent/blob/main/backend/services/celery_app.py): `backend/services/celery_app.py`
- [Pipeline coordinator](https://github.com/codecrafter001/terraform_agent/blob/main/backend/services/pipeline.py): `backend/services/pipeline.py`

### Migration intelligence

- [Agent graph](https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/graph.py): `backend/agents/graph.py`
- [Request intent](https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/intent_router.py): `backend/agents/intent_router.py`
- [AWS discovery](https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/cloud_discovery.py): `backend/agents/cloud_discovery.py`
- [Dependency topology](https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/graph_agent.py): `backend/agents/graph_agent.py`
- [Resource classification](https://github.com/codecrafter001/terraform_agent/blob/main/backend/tools/resource_classifier.py): `backend/tools/resource_classifier.py`
- [Adoption planning](https://github.com/codecrafter001/terraform_agent/blob/main/backend/tools/adoption_planner.py): `backend/tools/adoption_planner.py`
- [IaC composition](https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/terraform_composer.py): `backend/agents/terraform_composer.py`

### Verification and delivery

- [Sandbox validation](https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/validation_agent.py): `backend/agents/validation_agent.py`
- [Terraform and OpenTofu](https://github.com/codecrafter001/terraform_agent/blob/main/backend/tools/iac_engine.py): `backend/tools/iac_engine.py`
- [Policy and security](https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/policy_agent.py): `backend/agents/policy_agent.py`
- [Validation repair](https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/validation_repair.py): `backend/agents/validation_repair.py`
- [Reports and artifacts](https://github.com/codecrafter001/terraform_agent/blob/main/backend/agents/documentation_agent.py): `backend/agents/documentation_agent.py`
- [GitHub adoption PR](https://github.com/codecrafter001/terraform_agent/blob/main/backend/services/github_client.py): `backend/services/github_client.py`

### Persistence

- [Live job state and logs](https://github.com/codecrafter001/terraform_agent/blob/main/backend/services/redis_client.py): `backend/services/redis_client.py`
- [Job audit records](https://github.com/codecrafter001/terraform_agent/blob/main/backend/services/database.py): `backend/services/database.py`

### Other components

- **Engineer**
- **Human reviewer**
- **AWS estate**

## Connections

- Engineer → TerraAgent dashboard: submits request (evidence: `README.md`)
- TerraAgent dashboard → Frontend API client: uses API
- Frontend API client → Scan API: requests scan
- Scan API → Background job runner: queues job (evidence: `backend/routers/scan.py`)
- Background job runner → Pipeline coordinator: runs pipeline (evidence: `backend/services/celery_app.py`)
- Pipeline coordinator → Agent graph: runs graph (evidence: `backend/services/pipeline.py`)
- Agent graph → Request intent: routes intent (evidence: `backend/agents/graph.py`)
- Agent graph → AWS discovery: dispatches discovery (evidence: `README.md`)
- AWS discovery → AWS estate: reads inventory (evidence: `README.md`)
- Agent graph → Dependency topology: dispatches graphing (evidence: `README.md`)
- Agent graph → Resource classification: dispatches classification (evidence: `README.md`)
- Agent graph → Adoption planning: plans adoption (evidence: `README.md`)
- Agent graph → IaC composition: dispatches composition (evidence: `README.md`)
- Agent graph → Sandbox validation: dispatches validation (evidence: `README.md`)
- Sandbox validation → Terraform and OpenTofu: executes checks (evidence: `backend/tools/iac_engine.py`)
- Agent graph → Policy and security: dispatches policy checks (evidence: `README.md`)
- Agent graph → Validation repair: retries repair (evidence: `README.md`)
- Agent graph → Reports and artifacts: produces artifacts (evidence: `README.md`)
- Pipeline coordinator → Live job state and logs: publishes job state (evidence: `backend/services/pipeline.py`)
- Pipeline coordinator → Job audit records: records job (evidence: `backend/services/pipeline.py`)
- Pipeline coordinator → Human reviewer: pauses for decision (evidence: `backend/services/pipeline.py`)
- Human reviewer → Scan API: submits decision
- Scan API → Live job state and logs: reads status (evidence: `backend/routers/scan.py`)
- Results and approval UI → Frontend API client: loads results
- Reports and artifacts → GitHub adoption PR: enables PR delivery
