# jamil-rahman/capstone-fs architecture

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

- Interactive diagram: https://gitdiagram.com/jamil-rahman/capstone-fs
- Repository: https://github.com/jamil-rahman/capstone-fs

## Overview

##### Project Type and Purpose
- When-in-Roam is a full-stack roommate-finding web application.
- Frontend built with React (Vite) for SPA user interface and Firebase Authentication.
- Backend built with Node.js/Express exposing RESTful APIs, persisting data in MongoDB.
- Integrates with SendGrid for email, OpenAI for AI-driven city insights.

##### File Structure
- Top-level folders:
- backend/ – server code (app.js, config/, controllers/, models/, routes/, middleware/)
- frontend/ – client code (src/, public/, config and env files, Vite config)
- backend follows MVC:
- models/ define Mongoose schemas (User, Post, Trivia)
- controllers/ handle business logic (user, post, trivia, insights, email, dev)
- routes/ map HTTP endpoints to controllers
- middleware/ enforces auth (JWT/Firebase token validation)
- frontend is component-based:
- pages/ define route views (Home, Login, SignUp, Profile, Insights, PostManagement)
- components/ handle UI pieces (Navbar, Banner, Post cards, Modals, ProtectedRoute)
- services/ wrap axios calls to backend APIs
- context/AuthContext.jsx manages user session via Firebase SDK
- utils/ contain shared helpers (axios config, time formatting, auth utilities)
- Config files: .env for secrets, Procfile for Heroku, package.json for scripts.

##### Extract Architecture Insights from README
- User flow: signup/login via Firebase, create posts, browse posts, request AI insights, send emails.
- API calls: frontend → backend (Node/Express REST endpoints) → MongoDB; backend → SendGrid and OpenAI external APIs.
- All routes protected by authentication middleware.

a. Main Components
1. Frontend Client (React/Vite SPA)
2. Authentication Service (Firebase Auth)
3. API Layer (Express Server)
4. Data Store (MongoDB Atlas)
5. Email Service (SendGrid)
6. AI Service (OpenAI GPT-4)
7. Hosting/Deployment (Heroku or similar)
b. Relationships & Data Flows
- User interacts with React UI → invokes AuthContext for Firebase login.
- Upon login, React obtains Firebase JWT → attaches to axios requests.
- React services call Express endpoints (User, Post, Trivia, Insights, Email).
- Express middleware validates JWT (auth.js/auth-prod.js) → controllers execute.
- Controllers read/write via Mongoose to MongoDB.
- For email, controller calls SendGrid API.
- For city insights, controller calls OpenAI API.
- Responses flow back through Express → React → rendered UI.
c. Architectural Patterns
- MVC pattern on backend (Models, Controllers, Routes).
- Component-based architecture on frontend (presentational vs. container components).
- Service layer pattern for external API integration (sendgrid, openai).
- Context API for global state/auth.
d. Key Technologies & Frameworks
- React, Vite, Bootstrap, Firebase Auth, Axios (client)
- Node.js, Express, Mongoose, MongoDB (server)
- SendGrid SDK, OpenAI SDK (external integrations)
- Heroku (deployment), .env for configuration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        UI["Pages & Components"]:::client
        AuthCtx["AuthContext"]:::client
        FirebaseCfg["Firebase Configuration"]:::client
        AxiosCfg["Axios Configuration"]:::client
        AuthSvc["Auth Service"]:::client
        PostSvc["Post Service"]:::client
        EmailSvc["Email Service"]:::client
        InsightSvc["Insight Service"]:::client
        ProfileSvc["Profile Service"]:::client
    end

    %% Server Side
    subgraph "Server Side"
        APIGW["Express API (app.js)"]:::server
        AuthMW["Authentication Middleware"]:::server
        subgraph "Routes"
            UserRoutes["User Routes"]:::server
            PostRoutes["Post Routes"]:::server
            TriviaRoutes["Trivia Routes"]:::server
            EmailRoutes["Email Routes"]:::server
            InsightRoutes["Insights Routes"]:::server
            DevRoutes["Dev Routes"]:::server
        end
        subgraph "Controllers"
            UserCtrl["User Controller"]:::server
            PostCtrl["Post Controller"]:::server
            TriviaCtrl["Trivia Controller"]:::server
            EmailCtrl["Email Controller"]:::server
            InsightCtrl["Insight Controller"]:::server
            DevCtrl["Dev Controller"]:::server
        end
        subgraph "Models"
            UserModel["User Model"]:::server
            PostModel["Post Model"]:::server
            TriviaModel["Trivia Model"]:::server
        end
        DBConfig["Database Configuration"]:::server
    end

    %% External Services
    subgraph "External Services"
        Firebase["Firebase Auth"]:::external
        SendGrid["SendGrid"]:::external
        OpenAI["OpenAI GPT-4"]:::external
    end

    %% Database
    DB["MongoDB Atlas"]:::db

    %% Flows
    UI -->|uses| AuthCtx
    AuthCtx -->|authenticates| Firebase
    UI -->|calls| AuthSvc
    UI -->|calls| PostSvc
    UI -->|calls| EmailSvc
    UI -->|calls| InsightSvc
    UI -->|calls| ProfileSvc

    AuthSvc --> APIGW
    PostSvc --> APIGW
    EmailSvc --> APIGW
    InsightSvc --> APIGW
    ProfileSvc --> APIGW

    APIGW -->|routes to| UserRoutes
    APIGW -->|routes to| PostRoutes
    APIGW -->|routes to| TriviaRoutes
    APIGW -->|routes to| EmailRoutes
    APIGW -->|routes to| InsightRoutes
    APIGW -->|routes to| DevRoutes

    UserRoutes --> AuthMW
    PostRoutes --> AuthMW
    TriviaRoutes --> AuthMW
    EmailRoutes --> AuthMW
    InsightRoutes --> AuthMW
    DevRoutes --> AuthMW

    AuthMW --> UserCtrl
    AuthMW --> PostCtrl
    AuthMW --> TriviaCtrl
    AuthMW --> EmailCtrl
    AuthMW --> InsightCtrl
    AuthMW --> DevCtrl

    UserCtrl --> UserModel
    PostCtrl --> PostModel
    TriviaCtrl --> TriviaModel
    EmailCtrl -->|sends via| SendGrid
    InsightCtrl -->|requests| OpenAI

    UserModel --> DBConfig
    PostModel --> DBConfig
    TriviaModel --> DBConfig
    DBConfig --> DB

    %% Click Events
    click UI "https://github.com/jamil-rahman/capstone-fs/tree/master/frontend/src/"
    click AuthCtx "https://github.com/jamil-rahman/capstone-fs/blob/master/frontend/src/context/AuthContext.jsx"
    click FirebaseCfg "https://github.com/jamil-rahman/capstone-fs/blob/master/frontend/src/config/firebase.js"
    click AxiosCfg "https://github.com/jamil-rahman/capstone-fs/blob/master/frontend/src/utils/axiosConfig.js"
    click AuthSvc "https://github.com/jamil-rahman/capstone-fs/blob/master/frontend/src/services/authService.js"
    click PostSvc "https://github.com/jamil-rahman/capstone-fs/blob/master/frontend/src/services/postService.js"
    click EmailSvc "https://github.com/jamil-rahman/capstone-fs/blob/master/frontend/src/services/emailService.js"
    click InsightSvc "https://github.com/jamil-rahman/capstone-fs/blob/master/frontend/src/services/insightService.js"
    click ProfileSvc "https://github.com/jamil-rahman/capstone-fs/blob/master/frontend/src/services/profileService.js"
    click APIGW "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/app.js"
    click UserRoutes "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/routes/user-routes.js"
    click PostRoutes "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/routes/post-routes.js"
    click TriviaRoutes "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/routes/trivia-routes.js"
    click EmailRoutes "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/routes/email-routes.js"
    click InsightRoutes "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/routes/insights-routes.js"
    click DevRoutes "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/routes/dev-routes.js"
    click AuthMW "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/middleware/auth.js"
    click UserCtrl "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/controllers/user-controller.js"
    click PostCtrl "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/controllers/post-controller.js"
    click TriviaCtrl "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/controllers/trivia-controller.js"
    click EmailCtrl "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/controllers/email-controller.js"
    click InsightCtrl "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/controllers/insight-controller.js"
    click DevCtrl "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/controllers/dev-controller.js"
    click UserModel "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/models/User.js"
    click PostModel "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/models/Post.js"
    click TriviaModel "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/models/Trivia.js"
    click DBConfig "https://github.com/jamil-rahman/capstone-fs/blob/master/backend/config/db.js"
    click Procfile "https://github.com/jamil-rahman/capstone-fs/tree/master/Procfile"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef server fill:#DFFFE0,stroke:#000,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#000,stroke-width:1px
    classDef db fill:#F2F2F2,stroke:#000,stroke-width:1px
```
