# vancovx/bull3d architecture

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

- Interactive diagram: https://gitdiagram.com/vancovx/bull3d
- Repository: https://github.com/vancovx/bull3d

## Overview

##### Project Type and Purpose
- BULL3D is a full-stack MERN (MongoDB, Express, React, Node.js) web application for centralized management of digital assets (3D models, textures, audio).
- It provides user authentication (JWT + bcrypt), asset CRUD operations, comments, favorites, downloads, and cloud storage integration (Google Drive).

##### File Structure Analysis
- Top-level:
- backend/ – Express API with MVC layers (models, routes, controllers) plus middleware and config
- frontend/ – React SPA with Redux slices (features), reusable components, pages, and state store
- Backend patterns: layered architecture (routing → controllers → models → MongoDB), middleware for auth, error handling, and Google Drive integration
- Frontend patterns: presentation components, pages, Redux Toolkit slices (assets, auth, comments, favorites, downloads, users) calling REST services

##### Main Architectural Components
a. Client Layer (Frontend)
- React SPA served from webpack dev server or static build
- Redux store manages global state; React components/pages dispatch actions and subscribe to slices
- Asset upload/download flows integrate with Google Drive middleware via backend
b. API Layer (Backend)
- Express.js server (server.js) exposes REST endpoints under /api
- Routes map to controllers (assetController, userController, etc.)
- Controllers execute business logic, call Mongoose models, and return JSON
- Middleware chain handles authentication (JWT), error responses, and Google Drive file transfers
c. Data Persistence
- MongoDB (self-hosted or Atlas) accessed via Mongoose ODM
- Schemas: User, Asset, Comment, Favorite, Download
d. External Services
- Google Drive / Google Cloud Storage for file uploads
- JWT issuer/validator
- bcrypt for password hashing

##### Component Relationships and Data Flows
- Browser → HTTP(S) → Frontend SPA
- SPA dispatches REST calls (Axios or fetch) to Express API
- Express middleware authenticates JWT, parses body, logs errors
- Controllers orchestrate:
- UserController (login, register, profile)
- AssetController (CRUD, search, view)
- CommentController, FavoriteController, DownloadController
- ProxyRoutes for Google Drive operations
- Controllers call Mongoose models → MongoDB
- For file storage, AssetController delegates to googleDriveMiddleware → Google Drive API → cloud storage
- Responses propagate back through middleware to SPA

##### Key Architectural Patterns and Principles
- Layered (Presentation → Business → Data)
- Separation of concerns (frontend vs. backend, controllers vs. models)
- Stateless authentication using JWT
- Single API gateway (Express monolith) rather than microservices
- Redux Toolkit for predictable state transitions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser["Browser"]:::frontend

    subgraph "Frontend (Client)" 
        direction TB
        Index["Entry Point\nfrontend/src/index.js"]:::frontend
        App["Main App Component\nfrontend/src/App.js"]:::frontend
        Store["Redux Store\nfrontend/src/app/store.js"]:::frontend

        subgraph "Redux Slices & Services"
            direction TB
            AssetsSlice["Asset Slice\nassetSlice.js"]:::frontend
            AssetsService["Asset Service\nassetService.js"]:::frontend
            AuthSlice["Auth Slice\nauthSlice.js"]:::frontend
            AuthService["Auth Service\nauthService.js"]:::frontend
            CommentSlice["Comment Slice\ncommentSlice.js"]:::frontend
            CommentService["Comment Service\ncommentService.js"]:::frontend
            FavoriteSlice["Favorite Slice\nfavoriteSlice.js"]:::frontend
            FavoriteService["Favorite Service\nfavoriteService.js"]:::frontend
            DownloadSlice["Download Slice\ndownloadSlice.js"]:::frontend
            DownloadService["Download Service\ndownloadService.js"]:::frontend
            UserSlice["User Slice\nuserSlice.js"]:::frontend
            UserService["User Service\nuserService.js"]:::frontend
        end

        subgraph "UI Components & Pages"
            direction TB
            ComponentsDir["Components Directory\nfrontend/src/components"]:::frontend
            PagesDir["Pages Directory\nfrontend/src/pages"]:::frontend
        end

        Index --> App
        App --> Store
        App --> ComponentsDir
        App --> PagesDir
        Store --> AssetsSlice
        Store --> AuthSlice
        Store --> CommentSlice
        Store --> FavoriteSlice
        Store --> DownloadSlice
        Store --> UserSlice

        %% Services usage
        App --> AssetsService
        App --> AuthService
        App --> CommentService
        App --> FavoriteService
        App --> DownloadService
        App --> UserService
    end

    Browser -->|"HTTP REST Calls\nGET/POST /api/*"| App

    %% API Layer
    subgraph "Backend (API)" 
        direction TB
        Server["Express Server\nbackend/server.js"]:::backend
        ConfigDB["DB Config\nbackend/config/db.js"]:::backend

        subgraph "Middleware"
            direction TB
            AuthMW["Auth Middleware\nbackend/middleware/authMiddleware.js"]:::backend
            ErrorMW["Error Middleware\nbackend/middleware/errorMiddleware.js"]:::backend
            DriveMW["Google Drive Middleware\nbackend/middleware/googleDriveMiddleware.js"]:::backend
        end

        subgraph "Routes"
            direction TB
            AssetRoutes["Asset Routes\nbackend/routes/assetRoutes.js"]:::backend
            UserRoutes["User Routes\nbackend/routes/userRoutes.js"]:::backend
            CommentRoutes["Comment Routes\nbackend/routes/commentRoutes.js"]:::backend
            FavoriteRoutes["Favorite Routes\nbackend/routes/favoriteRoutes.js"]:::backend
            DownloadRoutes["Download Routes\nbackend/routes/downloadRoutes.js"]:::backend
            ProxyRoutes["Proxy Routes\nbackend/routes/proxyRoutes.js"]:::backend
        end

        subgraph "Controllers"
            direction TB
            AssetCtrl["Asset Controller\nbackend/controllers/assetController.js"]:::backend
            UserCtrl["User Controller\nbackend/controllers/userController.js"]:::backend
            CommentCtrl["Comment Controller\nbackend/controllers/commentController.js"]:::backend
            FavoriteCtrl["Favorite Controller\nbackend/controllers/favoriteController.js"]:::backend
            DownloadCtrl["Download Controller\nbackend/controllers/downloadController.js"]:::backend
        end

        subgraph "Models"
            direction TB
            UserModel["User Model\nbackend/models/userModel.js"]:::backend
            AssetModel["Asset Model\nbackend/models/assetModel.js"]:::backend
            CommentModel["Comment Model\nbackend/models/commentModel.js"]:::backend
            FavoriteModel["Favorite Model\nbackend/models/favoriteModel.js"]:::backend
            DownloadModel["Download Model\nbackend/models/downloadModel.js"]:::backend
        end

        TokenUtil["Refresh Token Utility\nbackend/getRefreshToken.js"]:::backend

        Server --> ConfigDB
        ConfigDB --> DB[(MongoDB)]:::db

        Server --> AuthMW
        Server --> ErrorMW
        Server --> DriveMW

        Server --> AssetRoutes
        Server --> UserRoutes
        Server --> CommentRoutes
        Server --> FavoriteRoutes
        Server --> DownloadRoutes
        Server --> ProxyRoutes

        AssetRoutes --> AssetCtrl
        UserRoutes --> UserCtrl
        CommentRoutes --> CommentCtrl
        FavoriteRoutes --> FavoriteCtrl
        DownloadRoutes --> DownloadCtrl
        ProxyRoutes --> DriveMW

        AssetCtrl --> AssetModel
        UserCtrl --> UserModel
        CommentCtrl --> CommentModel
        FavoriteCtrl --> FavoriteModel
        DownloadCtrl --> DownloadModel

        DriveMW --> TokenUtil
        DriveMW -->|"Google Drive API"| GoogleDrive[(Google Drive)]:::external
        DB -->|"Mongoose CRUD"| AssetModel
        DB --> UserModel
        DB --> CommentModel
        DB --> FavoriteModel
        DB --> DownloadModel
    end

    App -->|"HTTP REST Calls"| Server

    classDef frontend fill:#cce5ff,stroke:#3399ff,stroke-width:1px;
    classDef backend fill:#d4edda,stroke:#28a745,stroke-width:1px;
    classDef db fill:#ffe5b4,stroke:#ff8c00,stroke-width:1px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px;

    %% Click Events
    click Server "https://github.com/vancovx/bull3d/blob/master/backend/server.js"
    click ConfigDB "https://github.com/vancovx/bull3d/blob/master/backend/config/db.js"
    click AuthMW "https://github.com/vancovx/bull3d/blob/master/backend/middleware/authMiddleware.js"
    click ErrorMW "https://github.com/vancovx/bull3d/blob/master/backend/middleware/errorMiddleware.js"
    click DriveMW "https://github.com/vancovx/bull3d/blob/master/backend/middleware/googleDriveMiddleware.js"
    click UserCtrl "https://github.com/vancovx/bull3d/blob/master/backend/controllers/userController.js"
    click AssetCtrl "https://github.com/vancovx/bull3d/blob/master/backend/controllers/assetController.js"
    click CommentCtrl "https://github.com/vancovx/bull3d/blob/master/backend/controllers/commentController.js"
    click FavoriteCtrl "https://github.com/vancovx/bull3d/blob/master/backend/controllers/favoriteController.js"
    click DownloadCtrl "https://github.com/vancovx/bull3d/blob/master/backend/controllers/downloadController.js"
    click TokenUtil "https://github.com/vancovx/bull3d/blob/master/backend/getRefreshToken.js"
    click UserModel "https://github.com/vancovx/bull3d/blob/master/backend/models/userModel.js"
    click AssetModel "https://github.com/vancovx/bull3d/blob/master/backend/models/assetModel.js"
    click CommentModel "https://github.com/vancovx/bull3d/blob/master/backend/models/commentModel.js"
    click FavoriteModel "https://github.com/vancovx/bull3d/blob/master/backend/models/favoriteModel.js"
    click DownloadModel "https://github.com/vancovx/bull3d/blob/master/backend/models/downloadModel.js"
    click AssetRoutes "https://github.com/vancovx/bull3d/blob/master/backend/routes/assetRoutes.js"
    click UserRoutes "https://github.com/vancovx/bull3d/blob/master/backend/routes/userRoutes.js"
    click CommentRoutes "https://github.com/vancovx/bull3d/blob/master/backend/routes/commentRoutes.js"
    click FavoriteRoutes "https://github.com/vancovx/bull3d/blob/master/backend/routes/favoriteRoutes.js"
    click DownloadRoutes "https://github.com/vancovx/bull3d/blob/master/backend/routes/downloadRoutes.js"
    click ProxyRoutes "https://github.com/vancovx/bull3d/blob/master/backend/routes/proxyRoutes.js"
    click Index "https://github.com/vancovx/bull3d/blob/master/frontend/src/index.js"
    click App "https://github.com/vancovx/bull3d/blob/master/frontend/src/App.js"
    click Store "https://github.com/vancovx/bull3d/blob/master/frontend/src/app/store.js"
    click AssetsSlice "https://github.com/vancovx/bull3d/blob/master/frontend/src/features/assets/assetSlice.js"
    click AssetsService "https://github.com/vancovx/bull3d/blob/master/frontend/src/features/assets/assetService.js"
    click AuthSlice "https://github.com/vancovx/bull3d/blob/master/frontend/src/features/auth/authSlice.js"
    click AuthService "https://github.com/vancovx/bull3d/blob/master/frontend/src/features/auth/authService.js"
    click CommentSlice "https://github.com/vancovx/bull3d/blob/master/frontend/src/features/comments/commentSlice.js"
    click CommentService "https://github.com/vancovx/bull3d/blob/master/frontend/src/features/comments/commentService.js"
    click FavoriteSlice "https://github.com/vancovx/bull3d/blob/master/frontend/src/features/favorites/favoriteSlice.js"
    click FavoriteService "https://github.com/vancovx/bull3d/blob/master/frontend/src/features/favorites/favoriteService.js"
    click DownloadSlice "https://github.com/vancovx/bull3d/blob/master/frontend/src/features/downloads/downloadSlice.js"
    click DownloadService "https://github.com/vancovx/bull3d/blob/master/frontend/src/features/downloads/downloadService.js"
    click UserSlice "https://github.com/vancovx/bull3d/blob/master/frontend/src/features/users/userSlice.js"
    click UserService "https://github.com/vancovx/bull3d/blob/master/frontend/src/features/users/userService.js"
    click ComponentsDir "https://github.com/vancovx/bull3d/tree/master/frontend/src/components"
    click PagesDir "https://github.com/vancovx/bull3d/tree/master/frontend/src/pages"
```
