# nharan/vibe-draw architecture

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

- Interactive diagram: https://gitdiagram.com/nharan/vibe-draw
- Repository: https://github.com/nharan/vibe-draw

## Overview

##### Project Type and Purpose
- The project combines advanced frontend interactivity (using Next.js, React, and Three.js) with a robust backend (built with Python, FastAPI, and Celery) that powers AI-driven sketch conversion and 3D model generation.
- Its purpose is to democratize digital creativity by making complex 3D model rendering accessible to users without specialized technical or artistic skills.

##### Analyzing the File Structure
- The project is split into distinct top-level directories:
– Frontend: Contains Next.js/React code, UI components (including 2D canvas handling and 3D preview components with Three.js), and supporting libraries for tasks like grid management and file exports.
– Backend: Hosts Python code using FastAPI for API endpoints, a clear structure under app/ for API routes, core configuration (including Celery for asynchronous task management and Redis integration), and several tasks modules for managing AI model interactions (e.g., claude_tasks, cerebras_tasks, gemini_tasks).
- Presence of container-related files (Dockerfile, docker-compose.yml) indicates containerization and orchestration practices.
- The file organization (separation between API, core, and tasks) suggests a clean separation of concerns and an asynchronous microservice-like approach for handling compute-heavy AI tasks.

##### Key Components and Their Relationships
a. Main Components:
- Frontend Component:
- Built using Next.js and React.
- Includes interactive UI components (drawing canvas, buttons for auto-drawing, improving drawings, etc.), state management (appStore), and integration with 3D rendering (via Three.js).
- Backend Component:
- API Server using FastAPI.
- Contains the main application entry points (main.py, run.py) and an organized API module for handling incoming requests.
- Config, Redis, and Celery integration for asynchronous operations.
- Multiple task modules dedicated to interfacing with the specialized AI models: Gemini Flash, Claude Sonnet, and Cerebras Llama.
- Asynchronous Task Processing:
- Utilizes Celery (with a defined celery_app) to manage background processing of AI-driven tasks.
- Tasks are divided into multiple categories to handle various aspects of sketch conversion and 3D model generation.
- External AI Models/Services:
- Although abstracted, the names (Claude, Gemini, Cerebras) in the code indicate interactions with external AI services that process sketches and generate corresponding 3D models.

b. Relationships & Interactions:
- The Frontend sends drawing data and user inputs to the Backend via REST API endpoints.
- The Backend processes these inputs – potentially offloading intensive conversion logic to asynchronous Celery tasks.
- The Celery workers execute specific tasks (e.g., converting sketches using gemini_tasks or claude_tasks), then update state or return results to the API.
- Processed 3D models are then relayed back to the Frontend for rendering and further interactivity.

##### Architectural Patterns and Technologies
- Separation of Concerns: The project clearly splits user interface (frontend) from API and data processing (backend with asynchronous task management).
- Asynchronous Processing: Use of Celery for task queuing and Redis integration for message brokering ensures that compute-heavy AI operations do not block the user experience.
- Containerization: Docker-related files hint at a microservice or container-based approach for deployment and scalability.
- Technology Stack: Next.js, React, and Three.js on the frontend; Python, FastAPI, Celery, and Redis on the backend; integration with external AI services (Gemini, Claude, Cerebras).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Subgraph
    subgraph "Frontend"
        FE_Core("Frontend UI & 3D Rendering"):::frontend
        FE_Components("React Components (Canvas,Buttons,Three.js)"):::frontend
        FE_State("State Management"):::frontend
        FE_Lib("Utility Libraries"):::frontend
    end

    %% Backend API Subgraph
    subgraph "Backend API"
        BE_Api("FastAPI API Endpoints & Routing"):::backend
        BE_Main("API Entry (main/run)"):::backend
    end

    %% Asynchronous Tasks Subgraph
    subgraph "Asynchronous Tasks"
        BE_Celery("Celery Application"):::async
        BE_Tasks("AI Task Modules"):::async
        BE_Redis("Redis Message Broker"):::async
    end

    %% External AI Services
    EX_AI("External AI Services (Gemini,Claude,Cerebras)"):::external

    %% Containerization Subgraph
    subgraph "Containerization"
        CON_Dockerfile("Dockerfile"):::container
        CON_DockerCompose("Docker Compose"):::container
    end

    %% Frontend Internal Relationships
    FE_Components -->|"render_into"| FE_Core
    FE_State -->|"provide_state_to"| FE_Core
    FE_Lib -->|"support_with"| FE_Core

    %% Communication Flow between Frontend and Backend
    FE_Core -->|"HTTP_request"| BE_Api

    %% Backend API to Async Tasks flow
    BE_Api -->|"enqueue_task"| BE_Celery
    BE_Celery -->|"execute_task"| BE_Tasks

    %% Async Tasks invoking External AI Services
    BE_Tasks -->|"invoke_AI"| EX_AI
    EX_AI -->|"return_result"| BE_Tasks

    %% Async Tasks delivering result back
    BE_Tasks -->|"deliver_result"| BE_Celery
    BE_Celery -->|"callback_result"| BE_Main
    BE_Main -->|"send_model"| FE_Core

    %% Integration between API components
    BE_Api ---|"integrated_with"| BE_Main

    %% Celery uses Redis for messaging
    BE_Celery ---|"uses"| BE_Redis

    %% Containerization orchestrates backend components
    CON_Dockerfile -->|"containerizes"| BE_Api
    CON_Dockerfile -->|"containerizes"| BE_Celery
    CON_DockerCompose -->|"orchestrates"| BE_Api
    CON_DockerCompose -->|"orchestrates"| BE_Celery
    CON_DockerCompose -->|"orchestrates"| BE_Redis

    %% Styles
    classDef frontend fill:#a2d9ce,stroke:#117a65,stroke-width:2px;
    classDef backend fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef async fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
    classDef external fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef container fill:#e8daef,stroke:#8e44ad,stroke-width:2px;

    %% Click Events for Frontend
    click FE_Core "https://github.com/nharan/vibe-draw/tree/main/frontend/app"
    click FE_Components "https://github.com/nharan/vibe-draw/tree/main/frontend/app/components"
    click FE_State "https://github.com/nharan/vibe-draw/tree/main/frontend/app/store"
    click FE_Lib "https://github.com/nharan/vibe-draw/tree/main/frontend/app/lib"

    %% Click Events for Backend
    click BE_Api "https://github.com/nharan/vibe-draw/tree/main/backend/app/api"
    click BE_Main "https://github.com/nharan/vibe-draw/blob/main/backend/app/main.py"

    %% Click Events for Asynchronous Tasks
    click BE_Celery "https://github.com/nharan/vibe-draw/blob/main/backend/app/core/celery_app.py"
    click BE_Tasks "https://github.com/nharan/vibe-draw/tree/main/backend/app/tasks"
    click BE_Redis "https://github.com/nharan/vibe-draw/blob/main/backend/app/core/redis.py"

    %% Click Events for Containerization
    click CON_Dockerfile "https://github.com/nharan/vibe-draw/tree/main/backend/Dockerfile"
    click CON_DockerCompose "https://github.com/nharan/vibe-draw/blob/main/backend/docker-compose.yml"
```
