# haasini-p/cult_quest architecture

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

- Interactive diagram: https://gitdiagram.com/haasini-p/cult_quest
- Repository: https://github.com/haasini-p/cult_quest

## Overview

##### Project Type and Purpose
- CultQuest is a full-stack web application. The frontend is built with React (using Vite, TypeScript, shadcn-ui, and Tailwind CSS) housed in the src directory, while the backend is implemented as a Node.js server (located in the server directory) that follows a modular MVC style. In addition, the project uses static assets under the public folder, and there’s some configuration (e.g., app.py appears at the root which might be for alternative interfacing or lightweight service).

##### Analyzing the File Structure
- Top-Level Files/Folders:
- Public: Contains images, textures, sounds, and uploads that support the front-end visuals and audio.
- src: Contains the entire React frontend—including components, pages, contexts, hooks, and integrations. Notice the separation into UI components (shadcn-ui style customizations) and domain-specific components like games and maps.
- server: Contains back-end code using controllers (authController, eventController, userController), models (Event, Message, User), middleware (for error handling, authorization, async processing), and routes. There are also configuration files (db.js, socket.js) indicating database connectivity and real-time communication.
- Others: There is an index.html, configuration files for ESLint, PostCSS, Tailwind, Vite, TypeScript, and a package.json at the root and within the server folder. This suggests a separation in dependencies between the client and the server.
- The overall structure follows a clear separation of concerns. The backend follows an MVC-like organization, whereas the frontend is component-based and leverages hooks and React contexts for state management.

##### Insights from the README
- The README explains the development workflow (clone, install dependencies, run dev server) and lists the key technologies. Although the description is brief, it clearly outlines the primary stack (Vite, TypeScript, React, shadcn-ui, and Tailwind CSS), which is central to how we represent the frontend, while the backend is typically Node.js powered.

a. Main Components:
- Frontend: Client-side application built with React.
- Components: UI elements (buttons, dialogs, accordions, etc.), pages (About, Auth, Chat, Profile, etc.), and integrations (supabase client).
- State Management: Managed via React contexts (AuthContext, ChatContext) and custom hooks.
- Backend: Server-side application structured following an MVC pattern.
- Controllers: Manage business logic and API endpoints.
- Models: Represent data (events, messages, users) and interact with the database.
- Routes: Define API endpoints for authentication, events, and user management.
- Middleware: Handle authentication, error processing, and asynchronous operations.
- Configurations: Database connection (db.js) and socket configuration (socket.js) for real-time functionalities.
- Static Assets: All images, sounds, backgrounds, and uploads stored in the public directory.
- Additional Integrations:
- Supabase integration under src/integrations for extended services (possibly for real-time database or authentication features).
- Optional Python file (app.py) suggesting there might be some auxiliary service or alternative entry point.

b. Relationships & Interactions:
- The Backend interacts with the database (referenced in db.js) and is in turn accessed by controllers and middleware.
- Real-time data may be managed via websockets (as indicated in socket.js).
- The Frontend can interact with external integrations like Supabase for additional services.
- Static assets in the public directory are served by the web server and used by the frontend for UI enhancement.

c. Architectural Patterns and Design Principles:
- MVC Pattern: The backend segments into models, controllers, and routes.
- Component-Based Architecture: The React frontend’s separation into UI components, pages, contexts, and hooks.
- Modular Separation: Clear delineation between frontend, backend, and static assets.
- Real-time Communication: The presence of socket configuration for handling live updates.

d. Technologies, Frameworks, and Libraries:
- Frontend: React, Vite, TypeScript, shadcn-ui, Tailwind CSS.
- Backend: Node.js, Express (or similar based on the structure), and custom middleware.
- Integrations: Supabase for extended external service capabilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External
    U("User"):::external

    %% Frontend Layer
    subgraph "Frontend Layer (React/Vite Application)"
        FE1["React App (src)"]:::frontend
        FE2["Pages (src/pages)"]:::frontend
        FE3["Components (src/components)"]:::frontend
        FE4["Hooks (src/hooks)"]:::frontend
        FE5["Contexts (src/contexts)"]:::frontend
        FE6["Main Entry (src/main.tsx)"]:::frontend
        FE7["Supabase Integration (src/integrations/supabase)"]:::integration
    end

    %% Backend Layer
    subgraph "Backend Layer (Node.js Server Application)"
        SE["Server Entry (server/server.js)"]:::backend
        subgraph "Controllers"
            BC1["AuthController (server/controllers/authController.js)"]:::backend
            BC2["EventController (server/controllers/eventController.js)"]:::backend
            BC3["UserController (server/controllers/userController.js)"]:::backend
        end
        subgraph "Models"
            BM1["Event Model (server/models/Event.js)"]:::backend
            BM2["Message Model (server/models/Message.js)"]:::backend
            BM3["User Model (server/models/User.js)"]:::backend
        end
        subgraph "Routes"
            BR1["Auth Routes (server/routes/authRoutes.js)"]:::backend
            BR2["Event Routes (server/routes/eventRoutes.js)"]:::backend
            BR3["User Routes (server/routes/userRoutes.js)"]:::backend
        end
        subgraph "Middleware"
            BW1["Async Handler (server/middleware/asyncHandler.js)"]:::backend
            BW2["Auth Middleware (server/middleware/authMiddleware.js)"]:::backend
            BW3["Error Handler (server/middleware/errorHandler.js)"]:::backend
        end
        subgraph "Configuration"
            BCfg1["Database Config (server/config/db.js)"]:::backend
            BCfg2["Socket Config (server/config/socket.js)"]:::backend
        end
    end

    %% Static Assets & Auxiliary Layer
    subgraph "Static Assets & External Services"
        SA["Public Assets (public)"]:::static
        PY["Python Service (app.py)"]:::static
    end

    %% Relationships - External to Frontend
    U -->|"interacts"| FE1

    %% Frontend Internal Connections
    FE1 --> FE2
    FE1 --> FE3
    FE1 --> FE4
    FE1 --> FE5
    FE1 --> FE6
    FE1 --> FE7
    FE6 -->|"APICalls"| BR1

    %% Frontend to Static Assets
    FE1 -->|"loads"| SA

    %% Backend Relationships
    SE -->|"initConfig"| BCfg1
    SE --> BR1
    SE --> BR2
    SE --> BR3

    BR1 -->|"preProcess"| BW1
    BR1 -->|"handles"| BC1
    BR2 -->|"preProcess"| BW2
    BR2 -->|"handles"| BC2
    BR3 -->|"preProcess"| BW3
    BR3 -->|"handles"| BC3

    BC1 -->|"dataOps"| BM1
    BC2 -->|"dataOps"| BM2
    BC3 -->|"dataOps"| BM3

    %% Server serving static assets
    SE -->|"serves"| SA

    %% Class definitions
    classDef frontend fill:#ffebcd,stroke:#d2691e,stroke-width:2px;
    classDef backend fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef static fill:#98fb98,stroke:#006400,stroke-width:2px;
    classDef integration fill:#dda0dd,stroke:#800080,stroke-width:2px;
    classDef external fill:#ffe4e1,stroke:#b22222,stroke-width:2px;

    %% Click Events for Frontend
    click FE1 "https://github.com/haasini-p/cult_quest/tree/main/src"
    click FE2 "https://github.com/haasini-p/cult_quest/tree/main/src/pages"
    click FE3 "https://github.com/haasini-p/cult_quest/tree/main/src/components"
    click FE4 "https://github.com/haasini-p/cult_quest/tree/main/src/hooks"
    click FE5 "https://github.com/haasini-p/cult_quest/tree/main/src/contexts"
    click FE6 "https://github.com/haasini-p/cult_quest/blob/main/src/main.tsx"
    click FE7 "https://github.com/haasini-p/cult_quest/tree/main/src/integrations/supabase"

    %% Click Events for Backend - Controllers
    click BC1 "https://github.com/haasini-p/cult_quest/blob/main/server/controllers/authController.js"
    click BC2 "https://github.com/haasini-p/cult_quest/blob/main/server/controllers/eventController.js"
    click BC3 "https://github.com/haasini-p/cult_quest/blob/main/server/controllers/userController.js"
    %% Backend - Models
    click BM1 "https://github.com/haasini-p/cult_quest/blob/main/server/models/Event.js"
    click BM2 "https://github.com/haasini-p/cult_quest/blob/main/server/models/Message.js"
    click BM3 "https://github.com/haasini-p/cult_quest/blob/main/server/models/User.js"
    %% Backend - Routes
    click BR1 "https://github.com/haasini-p/cult_quest/blob/main/server/routes/authRoutes.js"
    click BR2 "https://github.com/haasini-p/cult_quest/blob/main/server/routes/eventRoutes.js"
    click BR3 "https://github.com/haasini-p/cult_quest/blob/main/server/routes/userRoutes.js"
    %% Backend - Middleware
    click BW1 "https://github.com/haasini-p/cult_quest/blob/main/server/middleware/asyncHandler.js"
    click BW2 "https://github.com/haasini-p/cult_quest/blob/main/server/middleware/authMiddleware.js"
    click BW3 "https://github.com/haasini-p/cult_quest/blob/main/server/middleware/errorHandler.js"
    %% Backend - Configuration
    click BCfg1 "https://github.com/haasini-p/cult_quest/blob/main/server/config/db.js"
    click BCfg2 "https://github.com/haasini-p/cult_quest/blob/main/server/config/socket.js"
    %% Backend - Server Entry
    click SE "https://github.com/haasini-p/cult_quest/blob/main/server/server.js"

    %% Click Events for Static Assets & Auxiliary
    click SA "https://github.com/haasini-p/cult_quest/tree/main/public"
    click PY "https://github.com/haasini-p/cult_quest/blob/main/app.py"
```
