# vanshwadhwa24/hourvest-1 architecture

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

- Interactive diagram: https://gitdiagram.com/vanshwadhwa24/hourvest-1
- Repository: https://github.com/vanshwadhwa24/hourvest-1

## Overview

##### Project Type and Purpose
- Hourvest is a full-stack web application: a time-bank marketplace where users trade “minits.”
- The frontend is a React SPA; the backend is a monolithic Node.js/Express API with MongoDB.
- Key flows: user authentication (Google OAuth + JWT), task proposals (create/send/accept), real-time chat per task, balance adjustments.

##### File Structure Analysis
- Top level: two folders `frontend/` and `backend/`.
- Frontend: React components, CSS, a `socket.js` for chat.
- Backend: standard Express structure—`routes/`, `controllers/`, `models/`, `middleware/`, `config/`, plus Passport setup.
- Utils include token helpers and a Python script (standalone).
- No microservices—single API server handles auth, proposals, tasks, chat.

##### README Insights
- Tech stack calls out React, Node/Express, MongoDB/Mongoose, Passport.js for Google OAuth, JWT.
- Describes feature set: auth, proposals, task CRUD, chat, and a “time economy.”

##### Main Components
a. Client (Browser) – React SPA
b. API Gateway – Express server entry point (`backend/server.js`)
c. Auth Module
- Google OAuth (external) ↔ Passport.js
- JWT issuance & validation (`authMiddleware.js`)
d. Business Logic Layer
- Controllers: auth, user, task, proposal, chat
- Routes: REST endpoints (`/auth`, `/tasks`, `/proposals`, `/chat`, `/users`)
e. Real-Time Chat
- Socket.io (or WebSocket) server integration (`frontend/src/chat/socket.js`, backend chatController)
f. Data Layer
- MongoDB cluster
- Mongoose models: User, Task, Proposal, Conversation, Message
g. External Services
- Google OAuth
- MongoDB Atlas (if hosted)
h. Utility Services
- Token utilities (`tokenUtils.js`)
- Error handling middleware (`errorHandler.js`)

##### Relationships and Data Flow
1. User clicks “Login with Google” → Browser → Passport.js ↔ Google OAuth → JWT returned.
2. Browser stores JWT → sends “Authorization: Bearer <token>” on API calls.
3. Express middleware validates JWT → routes delegate to controllers → Mongoose performs DB queries/updates.
4. Chat: Browser connects to Socket endpoint → messages handled by chatController → persisted in MongoDB → broadcast back.
5. Proposals: Client posts proposal → API updates Proposal & Task models, adjusts user balances on acceptance.

##### Architectural Patterns & Design Principles
- Layered architecture: Presentation (React) → API layer (Express routes + middleware) → Service/Controller logic → Persistence (MongoDB).
- Separation of concerns:
- Auth logic isolated in middleware & controllers
- Business logic in controllers
- Data models in Mongoose schemas
- Stateless API with JWT—horizontal scaling potential.
- Real-time subsystem (WebSocket) coexisting alongside REST.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    A["User (Browser)"]:::user

    %% Frontend Layer
    subgraph "Frontend (React SPA)"
        direction TB
        FE1["index.js"]:::frontend
        FE2["App.js"]:::frontend
        FE3["HomePage.jsx"]:::frontend
        FE4["HomePage.css"]:::frontend
        FE5["ChatPage.jsx"]:::frontend
        FE6["ChatList.jsx"]:::frontend
        FE7["ChatWindow.jsx"]:::frontend
        FE8["MessageBubble.jsx"]:::frontend
        FE9["socket.js"]:::frontend
        FE10["Proposals.jsx"]:::frontend
        FE11["ProposeForm.jsx"]:::frontend
        FE12["login.jsx"]:::frontend
        FE13["signup.jsx"]:::frontend
        FE14["profile.jsx"]:::frontend
        FE15["postTask.jsx"]:::frontend
    end

    %% Backend REST API Layer
    subgraph "Backend REST API (Express)"
        direction TB
        BE1["server.js"]:::backend
        BE2["passport.js"]:::backend
        BE3["authMiddleware.js"]:::backend
        BE4["errorHandler.js"]:::backend
        BE5["tokenUtils.js"]:::backend
        BE6["main2.py"]:::backend

        subgraph "Routes"
            direction TB
            BR1["auth.js"]:::backend
            BR2["userRoutes.js"]:::backend
            BR3["tasks.js"]:::backend
            BR4["proposalRoutes.js"]:::backend
            BR5["chat.js"]:::backend
        end

        subgraph "Controllers"
            direction TB
            BC1["authController.js"]:::backend
            BC2["userController.js"]:::backend
            BC3["taskController.js"]:::backend
            BC4["proposalController.js"]:::backend
            BC5["chatController.js"]:::backend
        end
    end

    %% Backend Real-Time Layer
    subgraph "Backend Real-Time Server"
        direction TB
        WS1["Socket.io (server)"]:::realtime
    end

    %% Database Layer
    subgraph "Database Models"
        direction TB
        M1["User.js"]:::database
        M2["Task.js"]:::database
        M3["Proposal.js"]:::database
        M4["Conversation.js"]:::database
        M5["Message.js"]:::database
    end
    DBCluster["MongoDB Atlas"]:::database

    %% External Services
    subgraph "External Services"
        direction TB
        EX1["Google OAuth"]:::external
    end

    %% Connections
    A -->|"loads"| FE1
    FE1 -->|"renders"| FE2
    FE2 -->|"calls REST API"| BE1
    FE9 -.->|"connects WebSocket"| WS1

    BE1 -->|"uses routes"| BR1
    BE1 -->|"uses routes"| BR2
    BE1 -->|"uses routes"| BR3
    BE1 -->|"uses routes"| BR4
    BE1 -->|"uses routes"| BR5

    BR1 --> BC1
    BR2 --> BC2
    BR3 --> BC3
    BR4 --> BC4
    BR5 --> BC5

    BC1 --> BE5
    BC1 --> BE2
    BE2 --> EX1
    BC2 --> M1
    BC3 --> M2
    BC4 --> M3
    BC5 --> M4
    BC5 --> M5

    M1 --> DBCluster
    M2 --> DBCluster
    M3 --> DBCluster
    M4 --> DBCluster
    M5 --> DBCluster

    WS1 --> BC5
    BC5 --> M4
    BC5 --> M5

    %% Middleware
    BE1 --> BE3
    BE1 --> BE4
    BE3 --> BC1

    %% JWT Flow Annotation
    EX1 -->|"OAuth handshake"| BE2
    BC1 -->|"issues JWT"| FE2
    FE2 -->|"Authorization: Bearer token"| BE1

    %% Click Events
    click FE1 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/index.js"
    click FE2 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/App.js"
    click FE3 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/HomePage.jsx"
    click FE4 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/HomePage.css"
    click FE5 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/chat/ChatPage.jsx"
    click FE6 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/chat/ChatList.jsx"
    click FE7 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/chat/ChatWindow.jsx"
    click FE8 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/chat/MessageBubble.jsx"
    click FE9 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/chat/socket.js"
    click FE10 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/Proposals.jsx"
    click FE11 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/ProposeForm.jsx"
    click FE12 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/login.jsx"
    click FE13 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/signup.jsx"
    click FE14 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/profile.jsx"
    click FE15 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/frontend/src/postTask.jsx"
    click BE1 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/server.js"
    click BE2 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/passport.js"
    click BE3 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/middleware/authMiddleware.js"
    click BE4 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/middleware/errorHandler.js"
    click BE5 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/utils/tokenUtils.js"
    click BE6 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/utils/main2.py"
    click BR1 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/routes/auth.js"
    click BR2 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/routes/userRoutes.js"
    click BR3 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/routes/tasks.js"
    click BR4 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/routes/proposalRoutes.js"
    click BR5 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/routes/chat.js"
    click BC1 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/controllers/authController.js"
    click BC2 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/controllers/userController.js"
    click BC3 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/controllers/taskController.js"
    click BC4 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/controllers/proposalController.js"
    click BC5 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/controllers/chatController.js"
    click M1 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/models/User.js"
    click M2 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/models/Task.js"
    click M3 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/models/Proposal.js"
    click M4 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/models/Conversation.js"
    click M5 "https://github.com/vanshwadhwa24/hourvest-1/blob/main/backend/models/Message.js"

    %% Styles
    classDef frontend fill:#E1F5FE,stroke:#0288D1,color:#01579B
    classDef backend fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
    classDef realtime fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef database fill:#ECEFF1,stroke:#607D8B,color:#37474F
    classDef external fill:#F5F5F5,stroke:#9E9E9E,color:#616161
    classDef user fill:#FFFFFF,stroke:#000000,color:#000000,font-weight:bold
```
