# ishan9678/codecraft architecture

> Architecture diagram of the GitHub repository ishan9678/codecraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ishan9678/codecraft
- Repository: https://github.com/ishan9678/codecraft

## Overview

##### Project type and purpose
- This is a full-stack web application named CodeCraft.
- Purpose: AI-powered code generation and iterative refinement using LLMs and a compiler API.

##### File structure
- Top-level “frontend” and “backend” folders, plus a docker-compose.yml at root.
- backend/src contains:
- llama_agent.py – FastAPI app entrypoint
- executor.py – runs code via Judge0 API
- generator.py – orchestrates code generation calls
- pipeline.py – implements the feedback loop
- db.py / db_models.py – ORM setup for PostgreSQL via Alembic migrations
- frontend/ contains a Next.js app (app/, components/, hooks/, lib/) with Tailwind CSS and custom UI components.
- .github/workflows/deploy.yml – CI/CD pipeline
- docker-compose.yml – service definitions for backend, frontend, and Postgres

##### Extract architecture from the README
- Frontend: Next.js, talking to backend via REST (CORS_ORIGINS).
- Backend: FastAPI, PostgreSQL, Judge0 API (COMPILER_API_ENDPOINT), Groq API (LLM).
- Workflow steps: user input → test case generation → code gen → compile/execute → verification → feedback loop.

##### Main components and their interactions
a. Frontend (Next.js)
- Hosts UI for inputs (question, language, iterations)
- Sends REST requests to backend (e.g., POST /generate)
b. Backend (FastAPI service)
- llama_agent: HTTP endpoints
- pipeline: orchestrates test generation, code generation, compilation/execution, verification, and refinement
- executor: HTTP client to Judge0 API for compile & run
- generator: calls LLM API (Groq/OpenAI) for code and test cases
- database (PostgreSQL via SQLAlchemy/Alembic): stores questions, iterations, code versions, results
c. External services
- Judge0 CE (compiler API)
- LLM provider (Groq API)
d. Infrastructure
- Docker Compose orchestrates three containers: frontend, backend, database
- CI/CD via GitHub Actions deploys to production (docker-compose in cloud or similar)

##### Architectural patterns and design principles
- Layered separation: UI layer, application layer (FastAPI), data layer (Postgres)
- Single-responsibility per module: pipeline vs. executor vs. generator vs. db
- Stateless API server, state persisted in DB
- Externalized dependencies (Judge0, LLM) treated as “cloud services”

## Diagram (Mermaid)

```mermaid
graph TB
    %% Layers
    subgraph "User"
        Browser["User Browser"]:::external
    end

    subgraph "Frontend Layer"
        direction TB
        NextApp["Next.js App"]:::frontend
        UIComp["UI Components"]:::frontend
        ThemeProv["Theme & Layout Providers"]:::frontend
        Hooks["Hooks"]:::frontend
        Utils["Utility Functions"]:::frontend
        Config["Tailwind & Next Config"]:::frontend
        FWDocker["Dockerfile"]:::frontend
    end

    subgraph "Backend Layer"
        direction TB
        API["FastAPI llama_agent"]:::backend
        Pipeline["pipeline"]:::backend
        Generator["generator"]:::backend
        Executor["executor"]:::backend
        Prompts["prompts"]:::backend
        DBSetup["db + db_models"]:::backend
        Migrations["Alembic Migrations"]:::backend
        BEDeps["requirements.txt"]:::backend
        BEEntrypoint["start.sh"]:::backend
        BEDocker["Dockerfile"]:::backend
    end

    subgraph "Data & Infra"
        direction TB
        Postgres["PostgreSQL"]:::db
        Judge0["Judge0 API"]:::external
        LLMAPI["LLM API (Groq)"]:::external
        Compose["docker-compose.yml"]:::infra
        CICD["GitHub Actions CI/CD"]:::infra
    end

    %% Connections
    Browser -->|"HTTP Request"| NextApp
    NextApp -->|"POST /generate"| API
    API -->|"invoke"| Pipeline
    Pipeline -->|"generate code/tests"| Generator
    Generator -->|"LLM prompt/response"| LLMAPI
    Pipeline -->|"execute code"| Executor
    Executor -->|"POST compile/run"| Judge0
    Executor -->|"results"| Pipeline
    Pipeline -->|"save/read"| Postgres
    API -->|"DB setup"| DBSetup
    DBSetup -->|"migrations"| Migrations

    %% Docker Compose grouping
    Compose --> NextApp
    Compose --> API
    Compose --> Postgres

    %% CI/CD
    CICD --> Compose

    %% Click Events
    click NextApp "https://github.com/ishan9678/codecraft/tree/master/frontend/"
    click UIComp "https://github.com/ishan9678/codecraft/blob/master/frontend/components/code-generator.tsx"
    click UIComp "https://github.com/ishan9678/codecraft/blob/master/frontend/components/results-display.tsx"
    click ThemeProv "https://github.com/ishan9678/codecraft/blob/master/frontend/components/theme-provider.tsx"
    click ThemeProv "https://github.com/ishan9678/codecraft/blob/master/frontend/components/theme-toggle.tsx"
    click ThemeProv "https://github.com/ishan9678/codecraft/blob/master/frontend/app/layout.tsx"
    click Hooks "https://github.com/ishan9678/codecraft/blob/master/frontend/hooks/use-mobile.tsx"
    click Hooks "https://github.com/ishan9678/codecraft/blob/master/frontend/hooks/use-toast.ts"
    click Utils "https://github.com/ishan9678/codecraft/blob/master/frontend/lib/utils.ts"
    click Config "https://github.com/ishan9678/codecraft/blob/master/frontend/tailwind.config.ts"
    click Config "https://github.com/ishan9678/codecraft/blob/master/frontend/next.config.mjs"
    click FWDocker "https://github.com/ishan9678/codecraft/tree/master/frontend/Dockerfile"

    click API "https://github.com/ishan9678/codecraft/blob/master/backend/src/llama_agent.py"
    click Pipeline "https://github.com/ishan9678/codecraft/blob/master/backend/src/pipeline.py"
    click Executor "https://github.com/ishan9678/codecraft/blob/master/backend/src/executor.py"
    click Generator "https://github.com/ishan9678/codecraft/blob/master/backend/src/generator.py"
    click Prompts "https://github.com/ishan9678/codecraft/blob/master/backend/src/prompts.py"
    click DBSetup "https://github.com/ishan9678/codecraft/blob/master/backend/src/db.py"
    click DBSetup "https://github.com/ishan9678/codecraft/blob/master/backend/src/db_models.py"
    click Migrations "https://github.com/ishan9678/codecraft/tree/master/backend/src/migrations/"
    click BEDocker "https://github.com/ishan9678/codecraft/tree/master/backend/Dockerfile"
    click BEDeps "https://github.com/ishan9678/codecraft/blob/master/backend/requirements.txt"
    click BEEntrypoint "https://github.com/ishan9678/codecraft/blob/master/backend/start.sh"
    click Compose "https://github.com/ishan9678/codecraft/blob/master/docker-compose.yml"
    click CICD "https://github.com/ishan9678/codecraft/blob/master/.github/workflows/deploy.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef db fill:#fff3cd,stroke:#ffcc00,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#adb5bd,stroke-width:1px,stroke-dasharray: 5 5
    classDef infra fill:#f8d7da,stroke:#dc3545,stroke-width:1px
```
