# lithinpavansai/ai_builder_backend architecture

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

- Interactive diagram: https://gitdiagram.com/lithinpavansai/ai_builder_backend
- Repository: https://github.com/lithinpavansai/ai_builder_backend

## Overview

App Compiler is a FastAPI backend that turns a natural-language app request into a structured, validated app schema. The primary flow enters through the generation API, passes through intent extraction, system design, schema generation, refinement, and validation/repair, then returns the result; async jobs expose progress and completed results. The README also documents runtime executability checks and prompt evaluation. Pipeline-stage links are supported by the README’s architecture description; sampled source shows orchestration and selected component calls, but not every route or stage implementation in full.

Main entry points: [`app/validators/repair.py`](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/repair.py) (Pipeline Orchestrator), [`app/evaluation/runner.py`](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/evaluation/runner.py) (Prompt Evaluation), [`app/utils/gemini.py`](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/utils/gemini.py) (Groq LLM Client), [`app/validators/models.py`](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/models.py) (Schema Contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API &amp; Jobs"]
  node_generation_api["Generation API<br/>[generate.py]"]
  node_job_store[("Async Job Store<br/>[job_store.py]")]
  node_evaluation_api["Evaluation API<br/>[generate.py]"]
end

subgraph group_pipeline["Schema Pipeline"]
  node_orchestrator["Pipeline Orchestrator<br/>[repair.py]"]
  node_intent["Intent Extraction<br/>[intent.py]"]
  node_system_design["System Design<br/>[system_design.py]"]
  node_schema_generation["Schema Generation<br/>[schema_gen.py]"]
  node_refinement["Schema Refinement<br/>[refinement.py]"]
end

subgraph group_quality["Validation &amp; Quality"]
  node_schema_models["Schema Contracts<br/>[models.py]"]
  node_validation["Schema Validation<br/>[validator.py]"]
  node_repair["Validation Repair<br/>[repair.py]"]
  node_retry_orchestrator["Retry Orchestrator<br/>[orchestrator.py]"]
  node_runtime_validator["Runtime Validator"]
end

subgraph group_support["LLM &amp; Evaluation"]
  node_llm_client["Groq LLM Client<br/>[gemini.py]"]
  node_configuration["LLM Configuration<br/>[config.py]"]
  node_eval_runner["Prompt Evaluation<br/>[runner.py]"]
  node_eval_dataset["Evaluation Prompts<br/>[test_prompts.py]"]
  node_eval_results[("Evaluation Results<br/>[results.json]")]
end

node_user(("API Client"))

node_user -->|"submits prompt"| node_generation_api
node_generation_api -->|"runs pipeline"| node_retry_orchestrator
node_retry_orchestrator -->|"runs with repair"| node_orchestrator
node_orchestrator -->|"extracts intent"| node_intent
node_orchestrator -->|"designs system"| node_system_design
node_orchestrator -->|"generates schema"| node_schema_generation
node_orchestrator -->|"refines schema"| node_refinement
node_intent -->|"requests completion"| node_llm_client
node_system_design -->|"requests completion"| node_llm_client
node_schema_generation -->|"requests completion"| node_llm_client
node_refinement -->|"requests completion"| node_llm_client
node_llm_client -->|"reads settings"| node_configuration
node_intent -->|"validates output"| node_schema_models
node_system_design -->|"validates output"| node_schema_models
node_schema_generation -->|"builds schema"| node_schema_models
node_refinement -->|"checks schema"| node_schema_models
node_orchestrator -->|"validates stages"| node_validation
node_orchestrator -->|"repairs invalid output"| node_repair
node_repair -->|"requests correction"| node_llm_client
node_retry_orchestrator -->|"serializes result"| node_schema_models
node_generation_api -->|"tracks async jobs"| node_job_store
node_generation_api -->|"checks executability"| node_runtime_validator
node_user -->|"submits eval request"| node_evaluation_api
node_evaluation_api -->|"runs evaluation"| node_eval_runner
node_eval_runner -->|"loads prompts"| node_eval_dataset
node_eval_runner -->|"writes report"| node_eval_results
node_eval_runner -->|"runs pipeline stage"| node_intent
node_eval_runner -->|"runs pipeline stage"| node_system_design
node_eval_runner -->|"scores runtime"| node_runtime_validator

click node_generation_api "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/routes/generate.py"
click node_job_store "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/utils/job_store.py"
click node_evaluation_api "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/routes/generate.py"
click node_orchestrator "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/repair.py"
click node_intent "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/pipeline/intent.py"
click node_system_design "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/pipeline/system_design.py"
click node_schema_generation "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/pipeline/schema_gen.py"
click node_refinement "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/pipeline/refinement.py"
click node_schema_models "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/models.py"
click node_validation "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/validator.py"
click node_repair "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/repair.py"
click node_retry_orchestrator "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/orchestrator.py"
click node_runtime_validator "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/runtime_validator.py"
click node_llm_client "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/utils/gemini.py"
click node_configuration "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/utils/config.py"
click node_eval_runner "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/evaluation/runner.py"
click node_eval_dataset "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/evaluation/test_prompts.py"
click node_eval_results "https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/evaluation/results.json"

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_generation_api,node_job_store,node_evaluation_api,node_user toneBlue
class node_orchestrator,node_intent,node_system_design,node_schema_generation,node_refinement toneAmber
class node_schema_models,node_validation,node_repair,node_retry_orchestrator,node_runtime_validator toneMint
class node_llm_client,node_configuration,node_eval_runner,node_eval_dataset,node_eval_results toneRose
```

## Components

### API & Jobs

- [Generation API](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/routes/generate.py): `app/routes/generate.py`
- [Async Job Store](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/utils/job_store.py): `app/utils/job_store.py`
- [Evaluation API](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/routes/generate.py): `app/routes/generate.py`

### Schema Pipeline

- [Pipeline Orchestrator](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/repair.py): `app/validators/repair.py`
- [Intent Extraction](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/pipeline/intent.py): `app/pipeline/intent.py`
- [System Design](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/pipeline/system_design.py): `app/pipeline/system_design.py`
- [Schema Generation](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/pipeline/schema_gen.py): `app/pipeline/schema_gen.py`
- [Schema Refinement](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/pipeline/refinement.py): `app/pipeline/refinement.py`

### Validation & Quality

- [Schema Contracts](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/models.py): `app/validators/models.py`
- [Schema Validation](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/validator.py): `app/validators/validator.py`
- [Validation Repair](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/repair.py): `app/validators/repair.py`
- [Retry Orchestrator](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/orchestrator.py): `app/validators/orchestrator.py`
- [Runtime Validator](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/validators/runtime_validator.py): `app/validators/runtime_validator.py`

### LLM & Evaluation

- [Groq LLM Client](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/utils/gemini.py): `app/utils/gemini.py`
- [LLM Configuration](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/utils/config.py): `app/utils/config.py`
- [Prompt Evaluation](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/evaluation/runner.py): `app/evaluation/runner.py`
- [Evaluation Prompts](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/evaluation/test_prompts.py): `app/evaluation/test_prompts.py`
- [Evaluation Results](https://github.com/lithinpavansai/ai_builder_backend/blob/main/app/evaluation/results.json): `app/evaluation/results.json`

### Other components

- **API Client**

## Connections

- API Client → Generation API: submits prompt (evidence: `README.md`)
- Generation API → Retry Orchestrator: runs pipeline (evidence: `app/routes/generate.py`)
- Retry Orchestrator → Pipeline Orchestrator: runs with repair (evidence: `app/validators/orchestrator.py`)
- Pipeline Orchestrator → Intent Extraction: extracts intent (evidence: `app/validators/repair.py`)
- Pipeline Orchestrator → System Design: designs system (evidence: `app/validators/repair.py`)
- Pipeline Orchestrator → Schema Generation: generates schema (evidence: `README.md`)
- Pipeline Orchestrator → Schema Refinement: refines schema (evidence: `README.md`)
- Intent Extraction → Groq LLM Client: requests completion (evidence: `app/pipeline/intent.py`)
- System Design → Groq LLM Client: requests completion (evidence: `app/pipeline/system_design.py`)
- Schema Generation → Groq LLM Client: requests completion (evidence: `app/pipeline/schema_gen.py`)
- Schema Refinement → Groq LLM Client: requests completion (evidence: `app/pipeline/refinement.py`)
- Groq LLM Client → LLM Configuration: reads settings (evidence: `app/utils/gemini.py`)
- Intent Extraction → Schema Contracts: validates output (evidence: `app/pipeline/intent.py`)
- System Design → Schema Contracts: validates output (evidence: `app/pipeline/system_design.py`)
- Schema Generation → Schema Contracts: builds schema (evidence: `app/pipeline/schema_gen.py`)
- Schema Refinement → Schema Contracts: checks schema (evidence: `app/pipeline/refinement.py`)
- Pipeline Orchestrator → Schema Validation: validates stages (evidence: `app/validators/repair.py`)
- Pipeline Orchestrator → Validation Repair: repairs invalid output (evidence: `app/validators/repair.py`)
- Validation Repair → Groq LLM Client: requests correction (evidence: `app/validators/repair.py`)
- Retry Orchestrator → Schema Contracts: serializes result (evidence: `app/validators/orchestrator.py`)
- Generation API → Async Job Store: tracks async jobs (evidence: `app/routes/generate.py`)
- Generation API → Runtime Validator: checks executability (evidence: `app/routes/generate.py`)
- API Client → Evaluation API: submits eval request (evidence: `README.md`)
- Evaluation API → Prompt Evaluation: runs evaluation (evidence: `app/routes/generate.py`)
- Prompt Evaluation → Evaluation Prompts: loads prompts (evidence: `app/evaluation/runner.py`)
- Prompt Evaluation → Evaluation Results: writes report (evidence: `app/evaluation/runner.py`)
- Prompt Evaluation → Intent Extraction: runs pipeline stage (evidence: `app/evaluation/runner.py`)
- Prompt Evaluation → System Design: runs pipeline stage (evidence: `app/evaluation/runner.py`)
- Prompt Evaluation → Runtime Validator: scores runtime (evidence: `app/evaluation/runner.py`)
