# ankitsingh-git2/ai-canvas architecture

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

- Interactive diagram: https://gitdiagram.com/ankitsingh-git2/ai-canvas
- Repository: https://github.com/ankitsingh-git2/ai-canvas

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-driven 2D-to-3D modeling web application called “Ai Canvas – Cursor for 3D Modeling.”
- Frontend: Next.js + React UI with TLDraw for 2D sketching, Three.js for 3D rendering, and Zustand for client state.
- Backend: FastAPI HTTP/SSE API, Celery workers for asynchronous AI tasks, Redis for pub/sub, plus connectors to external AI services (Claude, Gemini, Cerebras, PiAPI).

##### Top-Level File Structure Insights
- “frontend/” directory contains Next.js pages, React components, CSS, Three.js integrations, state store, and utility libraries.
- “backend/” directory holds a FastAPI app, Celery configuration, task definitions, Redis client, Dockerfiles, and docker-compose setup.
- Config files (.env.example, requirements.txt, package.json) and Docker orchestrations highlight containerized deployment.

##### Key Architectural Patterns
- Client-Server separation: Single-page React app communicates with a REST/SSE backend.
- Asynchronous Task Queue: Celery + Redis decouple AI computation from HTTP request lifecycle.
- Pub/Sub & SSE: Real-time feedback from backend task progress to frontend via Server-Sent Events.
- Micro-services style: API server and worker processes run in separate containers, defined in docker-compose.

##### Main Components
a. Frontend Layer
- React/Next.js App (pages, layout, routing)
- TLDraw Canvas (2D sketch UI)
- Three.js 3D Viewport (3D model rendering)
- Zustand Store (client state)
- Network Module (REST calls + SSE listener)
b. API Layer
- FastAPI Server (HTTP endpoints & SSE endpoint)
- API Routes: /improve-drawing, /make-3d, /export, etc.
- Config & Dependency Injection (config.py, redis.py)
c. Asynchronous Processing Layer
- Celery Broker & Backend (Redis)
- Worker Processes (cerebras_tasks, claude_tasks, gemini_tasks, generic tasks)
- Task Queue (task definitions and routing)
d. External AI Services
- Claude API
- Gemini API
- Cerebras API
- PiAPI (optional)
e. Data Store & Messaging
- Redis Instance (broker + pub/sub + result store)
- SSE Stream for real-time progress
f. Deployment & Orchestration
- Docker Containers: frontend, backend API, Celery worker
- Docker-Compose for local orchestration
- Environment Configuration (.env)

##### Relationships and Data Flows
- User interaction → React UI dispatches REST call to FastAPI.
- FastAPI enqueues a Celery task (via Redis broker).
- Worker picks up task, invokes external AI service, streams progress events back to Redis pub/sub.
- FastAPI SSE endpoint subscribes to Redis channel, pushes updates to client.
- On completion, FastAPI returns result (enhanced image or 3D model data) to frontend.
- Frontend caches/presents result in Zustand store and updates TLDraw/Three.js scenes.

##### Which Architectural Patterns to Highlight
- API-gateway + Worker pattern (FastAPI + Celery)
- Event-driven updates (Redis pub/sub → SSE)
- Component-based UI (2D vs 3D separation)
- Containerized services orchestrated via docker-compose

## Diagram (Mermaid)

```mermaid
flowchart TB

  subgraph "Frontend Layer"
    React["Next.js + React App"]:::frontend
    TLDraw["TLDraw Canvas (2D Sketch UI)"]:::frontend
    ThreeJS["Three.js 3D Viewport"]:::frontend
    Zustand["Zustand Store"]:::frontend
    Network["Network Module (REST + SSE)"]:::frontend
  end

  subgraph "API Layer"
    FastAPI["FastAPI Server"]:::api
    Routes["API Routes (/improve-drawing, /make-3d, /export)"]:::api
    Config["Config & Dependency Injection"]:::api
  end

  subgraph "Asynchronous Processing Layer"
    CeleryApp["Celery Broker & Backend (Redis)"]:::worker
    Tasks["Worker Processes (AI Task Definitions)"]:::worker
  end

  subgraph "Messaging Bus"
    Redis["Redis Instance (Broker + Pub/Sub)"]:::messaging
  end

  subgraph "External AI Services"
    Claude["Claude API"]:::external
    Gemini["Gemini API"]:::external
    Cerebras["Cerebras API"]:::external
    PiAPI["PiAPI"]:::external
  end

  %% Data Flows
  React -->|"REST Call"| FastAPI
  Network --> FastAPI
  FastAPI -->|"Enqueue Task"| CeleryApp
  CeleryApp --> Tasks
  Tasks -->|..invoke..| Claude
  Tasks -->|..invoke..| Gemini
  Tasks -->|..invoke..| Cerebras
  Tasks -->|..invoke..| PiAPI
  Tasks -->|-- Pub/Sub --| Redis
  FastAPI -->|-- SSE Subscribe --| Redis
  Redis -->|-- SSE Stream --| Network
  FastAPI -->|"HTTP Response"| Network
  Network --> React

  %% UI State Flows
  React --> Zustand
  Zustand --> TLDraw
  Zustand --> ThreeJS

  %% Click Events
  click React "https://github.com/ankitsingh-git2/ai-canvas/blob/main/frontend/app/page.tsx"
  click React "https://github.com/ankitsingh-git2/ai-canvas/blob/main/frontend/app/layout.tsx"
  click TLDraw "https://github.com/ankitsingh-git2/ai-canvas/blob/main/frontend/app/tldraw.css"
  click TLDraw "https://github.com/ankitsingh-git2/ai-canvas/blob/main/frontend/app/components/TldrawLogo.tsx"
  click ThreeJS "https://github.com/ankitsingh-git2/ai-canvas/tree/main/frontend/app/components/three/"
  click Zustand "https://github.com/ankitsingh-git2/ai-canvas/blob/main/frontend/app/store/appStore.ts"
  click Network "https://github.com/ankitsingh-git2/ai-canvas/blob/main/frontend/app/lib/improveDrawing.tsx"
  click Network "https://github.com/ankitsingh-git2/ai-canvas/blob/main/frontend/app/lib/vibe3DCode.tsx"
  click Network "https://github.com/ankitsingh-git2/ai-canvas/blob/main/frontend/app/lib/blobToBase64.ts"
  click Network "https://github.com/ankitsingh-git2/ai-canvas/blob/main/frontend/app/lib/downloadDataUrlAsFile.ts"
  click FastAPI "https://github.com/ankitsingh-git2/ai-canvas/blob/main/backend/app/main.py"
  click FastAPI "https://github.com/ankitsingh-git2/ai-canvas/blob/main/backend/run.py"
  click Routes "https://github.com/ankitsingh-git2/ai-canvas/blob/main/backend/app/api/routes.py"
  click Routes "https://github.com/ankitsingh-git2/ai-canvas/blob/main/backend/app/api/models.py"
  click Config "https://github.com/ankitsingh-git2/ai-canvas/blob/main/backend/app/core/config.py"
  click Config "https://github.com/ankitsingh-git2/ai-canvas/blob/main/backend/app/core/redis.py"
  click CeleryApp "https://github.com/ankitsingh-git2/ai-canvas/blob/main/backend/app/core/celery_app.py"
  click Tasks "https://github.com/ankitsingh-git2/ai-canvas/blob/main/backend/app/tasks/cerebras_tasks.py"
  click Tasks "https://github.com/ankitsingh-git2/ai-canvas/blob/main/backend/app/tasks/claude_tasks.py"
  click Tasks "https://github.com/ankitsingh-git2/ai-canvas/blob/main/backend/app/tasks/gemini_tasks.py"
  click Tasks "https://github.com/ankitsingh-git2/ai-canvas/blob/main/backend/app/tasks/tasks.py"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
  classDef api fill:#D5F5E3,stroke:#333,stroke-width:1px
  classDef worker fill:#FFE5B4,stroke:#333,stroke-width:1px
  classDef messaging fill:#FFF3A3,stroke:#333,stroke-width:1px
  classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
