# 23f2005217/project1-tds-t3-2025 architecture

> Architecture diagram of the GitHub repository 23f2005217/project1-tds-t3-2025, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/23f2005217/project1-tds-t3-2025
- Repository: https://github.com/23f2005217/project1-tds-t3-2025

## Overview

##### Project type and purpose
- This is a backend‐focused microservice (a specialized “LLM-powered deployment” service) rather than a full UI. It exposes a Flask HTTP API that receives build/revise requests, orchestrates LLM code generation, manages GitHub repos, and notifies an evaluation endpoint.

##### File structure
- Top-level scripts:
- `main.py` – starts the Flask server and routes requests
- `check_config.py` – validates environment variables and external credentials
- `test_api.py` / `test_api.sh` – automated tests for the HTTP endpoint
- `utils/` modules:
- `config.py` – loads and validates .env settings
- `validation.py` – request payload checks and secret verification
- `code_generator.py` – wraps the OpenAI calls to generate app code and README
- `github_manager.py` – encapsulates GitHub Repo creation, updates, and Pages setup
- `api_notifier.py` – implements evaluation API callback with retry logic

##### Key insights from the README
- Core workflow phases: Build (round 1) vs. Revise (round >1)
- External dependencies: OpenAI API, GitHub API, GitHub Pages, evaluation callback URL
- No persistent database—state is tracked via GitHub repos and round numbers

##### Main components
a. Client (HTTP consumer)
b. Flask API Server (single process)
- Request Handler (`handle_request`)
- Secret Verifier (`verify_secret`)
- LLM Code Generator (`generate_app_code`)
- GitHub Manager (`create_or_update_repo`)
- README Generator (`generate_readme`)
- Evaluation Notifier (`notify_evaluation_api`)
c. External Services
- OpenAI API
- GitHub API & GitHub Pages
- Evaluation Callback URL

##### Relationships & data flow
- The client sends an HTTP POST to `/api-endpoint`.
- The server validates the secret, then calls OpenAI to generate code.
- Next it creates (or updates) a GitHub repo and enables Pages.
- It auto-generates a README and pushes to GitHub.
- Finally, it notifies the evaluation endpoint, with retry/backoff on failure.

##### Architectural patterns & technologies
- Orchestration pattern: single service coordinating multiple external APIs.
- Retry pattern for evaluation callbacks.
- Module separation: API layer vs. business logic (utils) vs. external integrations.
- Key libs: Flask, python-dotenv, openai, PyGithub, requests.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Client
  subgraph Client["Consumer"]
    direction TB
    A["HTTP POST /api-endpoint"]:::client
  end

  %% Server internals
  subgraph Server["Flask API Server"]
    direction TB
    M["main.py: handle_request"]:::server
    C1["utils/config.py: load & validate env"]:::server
    C2["check_config.py: validate config"]:::server
    V["utils/validation.py: verify_secret & validate_payload"]:::server
    E["utils/code_generator.py: generate_app_code"]:::server
    G1["utils/github_manager.py: create_or_update_repo & setup Pages"]:::server
    R["utils/code_generator.py: generate_readme"]:::server
    N["utils/api_notifier.py: notify_evaluation_api"]:::server
  end

  %% External services
  subgraph External["External Systems"]
    direction TB
    H["OpenAI API"]:::external
    I["GitHub API"]:::external
    J["GitHub Pages"]:::external
    K["Evaluation Callback URL"]:::external
  end

  %% Project resources
  subgraph Resources["Project Resources"]
    direction TB
    T1["test_api.py"]:::resources
    T2["test_api.sh"]:::resources
    ENV[".env.example"]:::resources
    PKG["pyproject.toml"]:::resources
    REQ["requirements.txt"]:::resources
    GHAS[".github/assets"]:::resources
  end

  %% Data flow
  A -->|"POST request"| M
  M --> C1
  M --> C2
  M --> V
  V --> E
  E --> H
  E --> G1
  G1 --> I
  G1 --> J
  G1 --> R
  R --> I
  M --> N
  N -->|"POST repo details"| K
  N -.->|"retry/backoff"| K

  %% Click Events
  click M "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/main.py"
  click C1 "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/utils/config.py"
  click C2 "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/check_config.py"
  click V "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/utils/validation.py"
  click E "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/utils/code_generator.py"
  click R "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/utils/code_generator.py"
  click G1 "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/utils/github_manager.py"
  click N "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/utils/api_notifier.py"
  click T1 "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/test_api.py"
  click T2 "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/test_api.sh"
  click ENV "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/.env.example"
  click PKG "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/pyproject.toml"
  click REQ "https://github.com/23f2005217/project1-tds-t3-2025/blob/main/requirements.txt"
  click GHAS "https://github.com/23f2005217/project1-tds-t3-2025/tree/main/.github/assets"

  %% Styles
  classDef client fill:#EEFFEE,stroke:#339933,stroke-width:1px
  classDef server fill:#DDEEFF,stroke:#0066CC,stroke-width:1px
  classDef external fill:#FFEEDD,stroke:#CC6600,stroke-width:1px
  classDef resources fill:#F0F0F0,stroke:#888888,stroke-width:1px
```
