# thirumalai-tech-developer/ai-agent architecture

> Architecture diagram of the GitHub repository thirumalai-tech-developer/ai-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/thirumalai-tech-developer/ai-agent
- Repository: https://github.com/thirumalai-tech-developer/ai-agent

## Overview

This repository is an AI front-end scaffolding pipeline: a user prompt is planned into an application blueprint, compiled into component tasks, written into a React project, checked, and—when runtime errors occur—repaired. Its principal orchestration is in main.py; memory, provider-key routing, and JSON parsing support that workflow. The README documents the main stages and the template stack, while several listed utility modules were not excerpted, so their internal connections are left unspecified.

Main entry points: [`main.py`](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/main.py) (Pipeline runner), [`utils/error_fixer.py`](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/error_fixer.py) (Runtime healer), [`utils/memory.py`](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/memory.py) (Agentic memory), [`utils/assigner.py`](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/assigner.py) (Code assigner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Pipeline orchestration"]
  node_main["Pipeline runner<br/>[main.py]"]
  node_memory[("Agentic memory<br/>[memory.py]")]
  node_keys["API key router<br/>[key_router.py]"]
  node_llmrouter["LLM router<br/>[llm_router.py]"]
end

subgraph group_generation["Planning and generation"]
  node_planner["Blueprint planner<br/>[planner.py]"]
  node_planner2["Planner v2<br/>[planner_v2.py]"]
  node_executor["Task executor<br/>[executor.py]"]
  node_executor2["Executor v2<br/>[executor_v2.py]"]
  node_extractor["Output extractor<br/>[extractor.py]"]
  node_json["JSON repair<br/>[json_utils.py]"]
  node_assigner["Code assigner<br/>[assigner.py]"]
end

subgraph group_reliability["Validation and healing"]
  node_validator["Static validator<br/>[validator.py]"]
  node_healer["Runtime healer<br/>[error_fixer.py]"]
  node_solver["Error solver<br/>[error_solver.py]"]
end

subgraph group_template["Frontend template"]
  node_web["React app shell<br/>[App.tsx]"]
  node_entry["React entry<br/>[main.tsx]"]
end

node_user(("User"))
node_browser(("Headless browser"))

node_user -->|"submits prompt"| node_main
node_main -->|"requests plan"| node_planner
node_main -->|"builds tasks"| node_executor
node_main -->|"writes code"| node_assigner
node_main -->|"checks project"| node_validator
node_main -->|"starts healing"| node_healer
node_main -->|"loads context"| node_memory
node_main -->|"uses routing"| node_keys
node_main -->|"uses parsing"| node_json
node_healer -->|"checks console"| node_browser
node_healer -->|"reads context"| node_memory
node_healer -->|"applies fixes"| node_assigner
node_entry -->|"renders app"| node_web

click node_main "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/main.py"
click node_memory "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/memory.py"
click node_keys "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/key_router.py"
click node_planner "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/planner.py"
click node_planner2 "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/planner_v2.py"
click node_executor "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/executor.py"
click node_executor2 "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/executor_v2.py"
click node_extractor "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/extractor.py"
click node_json "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/json_utils.py"
click node_assigner "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/assigner.py"
click node_validator "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/validator.py"
click node_healer "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/error_fixer.py"
click node_solver "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/error_solver.py"
click node_llmrouter "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/llm_router.py"
click node_web "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/template/web/src/App.tsx"
click node_entry "https://github.com/thirumalai-tech-developer/ai-agent/blob/master/template/web/src/main.tsx"

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_main,node_memory,node_keys,node_llmrouter,node_user,node_browser toneBlue
class node_planner,node_planner2,node_executor,node_executor2,node_extractor,node_json,node_assigner toneAmber
class node_validator,node_healer,node_solver toneMint
class node_web,node_entry toneRose
```

## Components

### Pipeline orchestration

- [Pipeline runner](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/main.py): `main.py`
- [Agentic memory](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/memory.py): `utils/memory.py`
- [API key router](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/key_router.py): `utils/key_router.py`
- [LLM router](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/llm_router.py): `utils/llm_router.py`

### Planning and generation

- [Blueprint planner](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/planner.py): `utils/planner.py`
- [Planner v2](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/planner_v2.py): `utils/planner_v2.py`
- [Task executor](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/executor.py): `utils/executor.py`
- [Executor v2](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/executor_v2.py): `utils/executor_v2.py`
- [Output extractor](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/extractor.py): `utils/extractor.py`
- [JSON repair](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/json_utils.py): `utils/json_utils.py`
- [Code assigner](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/assigner.py): `utils/assigner.py`

### Validation and healing

- [Static validator](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/validator.py): `utils/validator.py`
- [Runtime healer](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/error_fixer.py): `utils/error_fixer.py`
- [Error solver](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/utils/error_solver.py): `utils/error_solver.py`

### Frontend template

- [React app shell](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/template/web/src/App.tsx): `template/web/src/App.tsx`
- [React entry](https://github.com/thirumalai-tech-developer/ai-agent/blob/master/template/web/src/main.tsx): `template/web/src/main.tsx`

### Other components

- **User**
- **Headless browser**

## Connections

- User → Pipeline runner: submits prompt (evidence: `Readme.md`)
- Pipeline runner → Blueprint planner: requests plan (evidence: `Readme.md`)
- Pipeline runner → Task executor: builds tasks (evidence: `Readme.md`)
- Pipeline runner → Code assigner: writes code (evidence: `Readme.md`)
- Pipeline runner → Static validator: checks project (evidence: `Readme.md`)
- Pipeline runner → Runtime healer: starts healing (evidence: `Readme.md`)
- Pipeline runner → Agentic memory: loads context (evidence: `main.py`)
- Pipeline runner → API key router: uses routing (evidence: `main.py`)
- Pipeline runner → JSON repair: uses parsing (evidence: `main.py`)
- Runtime healer → Headless browser: checks console (evidence: `utils/error_fixer.py`)
- Runtime healer → Agentic memory: reads context (evidence: `utils/error_fixer.py`)
- Runtime healer → Code assigner: applies fixes (evidence: `utils/error_fixer.py`)
- React entry → React app shell: renders app (evidence: `template/web/src/main.tsx`)
