# erazor48/eviverse architecture

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

- Interactive diagram: https://gitdiagram.com/erazor48/eviverse
- Repository: https://github.com/erazor48/eviverse

## Overview

##### Project type and purpose
- EVIverse is a full-stack web application combining a FastAPI-based Python backend with a React/TailwindCSS frontend.
- Its goal is to let users generate, refine and manipulate 3D objects via an AI-driven chatbot interface.

##### Main components
a. Frontend
- React app (frontend/src) with pages/components (Analysis, Home, Chatbot UI, ModelViewer, Login/Register).
- Contexts (AuthContext) and services modules (auth.ts, analyses.ts, chat.ts, models.ts) handle API calls.
- Built and served via `npm start` (Node.js, TailwindCSS for styling).
b. Backend API
- FastAPI application (`backend/app/main.py`)
- Routers in `backend/app/api/` (analyses.py, chat.py, users.py)
- Core utilities: `backend/app/core/database.py`, `init_db.py` for SQLAlchemy/SQLite integration
- Business logic in `backend/app/services/` (auth, AI/chat orchestration, model3d processing)
- Pydantic schemas in `backend/app/schemas/` and ORM models in `backend/app/models/`
c. Persistence layer
- SQLite database file (`eviverse.db`) managed via SQLAlchemy
- File storage under `backend/uploads/images` for user-uploaded assets and AI-generated 3D files
d. AI/ML model assets
- Potential local `backend/app/models_3d` or external AI service endpoints invoked from chat service
e. Scripts & environment
- `setup.bat` and `demarrer.bat` orchestrate Conda env creation, dependency installs (environment.yml, requirements.txt, package.json), and launch front+back servers
f. External services
- Third-party LLM/3D generation APIs (must be represented if used in `app/services/chat.py` or analysis endpoints)

##### Relationships & interactions
- User (browser) → React UI → HTTP(S) → FastAPI REST endpoints
- FastAPI → SQLAlchemy ORM → SQLite DB (users, analyses, model metadata)
- FastAPI → Services → AI generation engine (internal or external) → generates 3D assets
- FastAPI → writes 3D files and thumbnails → `uploads/images` storage
- React UI polls or streams websocket/chat responses from `/api/chat` for real-time feedback
- Authentication flow: React → `/api/users` → auth service → issues JWT or session → protected routes

##### Architectural patterns and design principles
- Layered architecture:
- Presentation (React UI)
- API/Controller (FastAPI routers)
- Service/Business logic (app/services)
- Data access (SQLAlchemy models & Pydantic schemas)
- Separation of concerns & single responsibility
- RESTful design for CRUD and AI-chat endpoints
- Use of dependency injection in FastAPI for database session, auth
- React Context for global state (auth, chat session)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UI["React + Tailwind UI"]:::frontend
        subgraph "Pages & Layout"
            direction TB
            Home["Home"]:::frontend
            Analysis["Analysis"]:::frontend
            ModelViewer["ModelViewer"]:::frontend
            Login["Login"]:::frontend
            Register["Register"]:::frontend
            Layout["Layout"]:::frontend
            App["App"]:::frontend
            Index["Index"]:::frontend
        end
        subgraph "Contexts & Services"
            direction TB
            AuthCtx["AuthContext"]:::frontend
            AuthSvc["auth.ts"]:::frontend
            AnalysesSvc["analyses.ts"]:::frontend
            ChatSvc["chat.ts"]:::frontend
            ModelsSvc["models.ts"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Main["main.py (FastAPI)"]:::backend
        subgraph "API Layer"
            direction TB
            UsersAPI["users.py"]:::api
            AnalysesAPI["analyses.py"]:::api
            ChatAPI["chat.py"]:::api
            ModelsAPI["models.py"]:::api
        end
        subgraph "Service Layer"
            direction TB
            AuthService["auth.py"]:::service
            AIChatService["chat orchestration"]:::service
            Model3DService["model3d processing"]:::service
        end
        subgraph "Data Layer"
            direction TB
            DBCore["database.py"]:::service
            InitDB["init_db.py"]:::service
            subgraph "ORM Models"
                direction TB
                AnalysisModel["analysis.py"]:::data
                ChatModel["chat.py"]:::data
                Model3DModel["model3d.py"]:::data
                UserModel["user.py"]:::data
            end
            subgraph "Pydantic Schemas"
                direction TB
                AnalysisSchema["analysis.py"]:::data
                ChatSchema["chat.py"]:::data
                Model3DSchema["model3d.py"]:::data
                UserSchema["user.py"]:::data
            end
        end
    end

    %% Storage & External
    SQLite["SQLite DB (eviverse.db)"]:::storage
    FileStore["File Storage (uploads/images)"]:::storage
    ExternalAI["External AI Engine"]:::external
    Scripts["manage.bat & env configs"]:::tools

    %% Connections
    UI -->|"HTTP /api"| Main
    ChatSvc -->|"WebSocket /api/chat"| ChatAPI
    Main --> UsersAPI
    Main --> AnalysesAPI
    Main --> ChatAPI
    Main --> ModelsAPI

    UsersAPI -->|"calls"| AuthService
    AnalysesAPI -->|"calls"| Model3DService
    ChatAPI -->|"calls"| AIChatService
    ModelsAPI -->|"calls"| Model3DService

    AuthService --> UserModel
    AuthService --> UserSchema
    Model3DService --> Model3DModel
    AIChatService --> ChatModel

    Main --> DBCore
    DBCore -->|"SQL"| SQLite
    Model3DService -->|"FS"| FileStore
    AIChatService -->|"REST/gRPC"| ExternalAI

    Scripts --> UI
    Scripts --> Main

    %% Click Events - Frontend
    click UI "https://github.com/erazor48/eviverse/tree/main/frontend/src"
    click Home "https://github.com/erazor48/eviverse/blob/main/frontend/src/components/Home.tsx"
    click Analysis "https://github.com/erazor48/eviverse/blob/main/frontend/src/components/Analysis.tsx"
    click ModelViewer "https://github.com/erazor48/eviverse/blob/main/frontend/src/components/ModelViewer.tsx"
    click Login "https://github.com/erazor48/eviverse/blob/main/frontend/src/components/auth/Login.tsx"
    click Register "https://github.com/erazor48/eviverse/blob/main/frontend/src/components/auth/Register.tsx"
    click Layout "https://github.com/erazor48/eviverse/blob/main/frontend/src/components/Layout.tsx"
    click App "https://github.com/erazor48/eviverse/blob/main/frontend/src/App.tsx"
    click Index "https://github.com/erazor48/eviverse/blob/main/frontend/src/index.tsx"
    click AuthCtx "https://github.com/erazor48/eviverse/blob/main/frontend/src/contexts/AuthContext.tsx"
    click AuthSvc "https://github.com/erazor48/eviverse/blob/main/frontend/src/services/auth.ts"
    click AnalysesSvc "https://github.com/erazor48/eviverse/blob/main/frontend/src/services/analyses.ts"
    click ChatSvc "https://github.com/erazor48/eviverse/blob/main/frontend/src/services/chat.ts"
    click ModelsSvc "https://github.com/erazor48/eviverse/blob/main/frontend/src/services/models.ts"

    %% Click Events - Backend
    click Main "https://github.com/erazor48/eviverse/blob/main/backend/app/main.py"
    click UsersAPI "https://github.com/erazor48/eviverse/blob/main/backend/app/api/users.py"
    click AnalysesAPI "https://github.com/erazor48/eviverse/blob/main/backend/app/api/analyses.py"
    click ChatAPI "https://github.com/erazor48/eviverse/blob/main/backend/app/api/chat.py"
    click ModelsAPI "https://github.com/erazor48/eviverse/blob/main/backend/app/api/models.py"
    click DBCore "https://github.com/erazor48/eviverse/blob/main/backend/app/core/database.py"
    click InitDB "https://github.com/erazor48/eviverse/blob/main/backend/app/core/init_db.py"
    click AuthService "https://github.com/erazor48/eviverse/blob/main/backend/app/services/auth.py"
    click AnalysisModel "https://github.com/erazor48/eviverse/blob/main/backend/app/models/analysis.py"
    click ChatModel "https://github.com/erazor48/eviverse/blob/main/backend/app/models/chat.py"
    click Model3DModel "https://github.com/erazor48/eviverse/blob/main/backend/app/models/model3d.py"
    click UserModel "https://github.com/erazor48/eviverse/blob/main/backend/app/models/user.py"
    click AnalysisSchema "https://github.com/erazor48/eviverse/blob/main/backend/app/schemas/analysis.py"
    click ChatSchema "https://github.com/erazor48/eviverse/blob/main/backend/app/schemas/chat.py"
    click Model3DSchema "https://github.com/erazor48/eviverse/blob/main/backend/app/schemas/model3d.py"
    click UserSchema "https://github.com/erazor48/eviverse/blob/main/backend/app/schemas/user.py"
    click SQLite "https://github.com/erazor48/eviverse/blob/main/backend/eviverse.db"
    click FileStore "https://github.com/erazor48/eviverse/tree/main/backend/uploads/images"
    click Scripts "https://github.com/erazor48/eviverse/blob/main/scripts/manage.bat"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0066CC,stroke-width:1px
    classDef backend fill:#DFFFE0,stroke:#339900,stroke-width:1px
    classDef api fill:#E8FFE8,stroke:#33CC33,stroke-width:1px
    classDef service fill:#FFF5CC,stroke:#FFCC00,stroke-width:1px
    classDef data fill:#FFE8E8,stroke:#CC3333,stroke-width:1px
    classDef storage fill:#FFEFD5,stroke:#CC9900,stroke-width:1px
    classDef external fill:#F0E6FF,stroke:#9933FF,stroke-width:1px
    classDef tools fill:#F5F5F5,stroke:#999999,stroke-width:1px
    class UI,Home,Analysis,ModelViewer,Login,Register,Layout,App,Index,AuthCtx,AuthSvc,AnalysesSvc,ChatSvc,ModelsSvc frontend
    class Main,DBCore,InitDB backend
    class UsersAPI,AnalysesAPI,ChatAPI,ModelsAPI api
    class AuthService,AIChatService,Model3DService service
    class AnalysisModel,ChatModel,Model3DModel,UserModel,AnalysisSchema,ChatSchema,Model3DSchema,UserSchema data
    class SQLite,FileStore storage
    class ExternalAI external
    class Scripts tools
```
