# codefox-repo/codefox architecture

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

- Interactive diagram: https://gitdiagram.com/codefox-repo/codefox
- Repository: https://github.com/codefox-repo/codefox

## Overview

- Frontend: Represented by the “frontend” folder. This Next.js-based client handles the user interface, routing, and API communications (using GraphQL) with the backend. Note related components such as pages, components, hooks, providers, and configuration.
- API Gateway/GraphQL endpoint (accessible at /graphql)
- Business logic layers (e.g., authentication, user management, chat, file download)
- The build system components (BuilderContext, HandlerManager, BuildHandlers, BuildMonitor, VirtualDirectory) that organize the process of generating a full-stack project.
- LLM Server: Indicated by the “llm-server” folder. This service manages interactions with AI models for code generation (using local models like Llama or cloud models) and prompt processing. Connect it to the backend via HTTP/WebSocket and label its role in updating AI model states and facilitating chat responses.

##### Build System Architecture
- Zoom in on the Build System that resides in the backend’s “src/build-system” directory. Break down the following components:
- BuilderContext: Coordinates build execution and dependency checks.
- HandlerManager: Manages individual build handlers (code-generation, file management, requirements documentation, UI/UX layout, database schema handling, etc.).
- BuildHandlers: Represent individual build tasks that process and update the virtual directory.
- BuildMonitor: Observes and reports the build status.
- VirtualDirectory: Acts as an in-memory file system during project generation.

##### Architectural Patterns & Technologies
- That the project uses microservice-like separation for concerns, distinguishing the frontend client, business logic (backend), and AI processing (LLM server).
- Mention the use of GraphQL for API communication in the front-to-back link.
- Specify frameworks and libraries like NestJS for backend, Next.js for frontend, and any related tooling (pnpm, turbo, Docker, tmuxinator).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend (Next.js Client)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer (NestJS)"
        BE["Backend (NestJS Service)"]:::backend
        BG["API Gateway (/graphql)"]:::backend
        BL["Business Logic (Auth,Chat,FileDownload)"]:::backend
        %% Build System Subgraph
        subgraph "Build System"
            BC["BuilderContext"]:::backend
            HM["HandlerManager"]:::backend
            BH["BuildHandlers"]:::backend
            VM["VirtualDirectory"]:::backend
            BM["BuildMonitor"]:::backend
        end
    end

    %% LLM Server Layer
    subgraph "LLM Server Layer"
        AI["LLM Server (AI/Model Service)"]:::llm
    end

    %% External Dependency
    DB["PostgreSQL DB"]:::backend

    %% Connections between layers
    FE -->|"GraphQL"| BG
    BE --> BG
    BE --> BL
    BL -->|"PersistentStorage"| DB

    %% Build System Process Flow within Backend
    BG -->|"TriggerBuild"| BC
    BC -->|"CallsManager"| HM
    HM -->|"ExecutesTasks"| BH
    BH -->|"UpdatesVDir"| VM
    VM -->|"MonitoredBy"| BM

    %% Communication to LLM Server
    BG -->|"AIModelCalls"| AI

    %% Click Events for Component Mapping
    click FE "https://github.com/codefox-repo/codefox/tree/main/frontend/"
    click BE "https://github.com/codefox-repo/codefox/tree/main/backend/"
    click BG "https://github.com/codefox-repo/codefox/blob/main/backend/src/app.resolver.ts"
    click BC "https://github.com/codefox-repo/codefox/blob/main/backend/src/build-system/context.ts"
    click HM "https://github.com/codefox-repo/codefox/blob/main/backend/src/build-system/hanlder-manager.ts"
    click BH "https://github.com/codefox-repo/codefox/tree/main/backend/src/build-system/handlers/"
    click BM "https://github.com/codefox-repo/codefox/blob/main/backend/src/build-system/monitor.ts"
    click VM "https://github.com/codefox-repo/codefox/blob/main/backend/src/build-system/virtual-dir/index.ts"
    click AI "https://github.com/codefox-repo/codefox/tree/main/llm-server/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef llm fill:#FFA500,stroke:#000,stroke-width:2px;
```
