# hamza9021/roam-roster architecture

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

- Interactive diagram: https://gitdiagram.com/hamza9021/roam-roster
- Repository: https://github.com/hamza9021/roam-roster

## Overview

##### Project type and purpose
- From the file tree and README, “ROAM ROSTER” is a full-stack MVC web application built with Node.js/Express, EJS templating for server-side rendering, MongoDB for data storage, and Cloudinary for image hosting.
- Purpose: a room-booking platform with secure user authentication, property listings, reviews, and advanced search.

##### File structure
- Top-level files:
- app.js (Express application entrypoint)
- cloudConfig.js (Cloudinary configuration)
- schema.js (Mongoose connection/config)
- middleware.js (global middleware)
- init/ (data seeding scripts)
- package.json (dependencies & scripts)
- MVC directories:
- models/ (Mongoose schemas: User, Listing, Review, OTP)
- controllers/ (business logic: user actions, listing CRUD, reviews)
- routes/ (Express routers mapping HTTP endpoints to controllers)
- views/ (EJS templates for pages & layouts)
- Public assets:
- public/CSS, public/js (static CSS/JS served to client)
- Utilities:
- utils/CustomError.js, wrapAsync.js (error handling helpers)

##### README for additional insights
- Technology stack: Express, EJS, MongoDB, Cloudinary
- Features: RESTful APIs, MVC, secure authentication, search filters
- Deployment/config: environment variables for DB & Cloudinary credentials

##### Main components & their interactions
a. Client / Browser (UI)
- Requests HTML via routes, submits forms (login, signup, new listing, reviews).
- Static assets (CSS/JS) served from public/.
b. Express Server (app.js)
- Loads cloudConfig, connects to MongoDB (schema.js).
- Applies middleware (middleware.js), mounts routers (routes/).
- Handles errors via utils and renders views.
c. Routing Layer (routes/*.js)
- Maps HTTP methods and URLs to controller methods.
- Example: POST /listings → controllers/listing.createListing.
d. Controller Layer (controllers/*.js)
- Validates input, calls Models, invokes Cloudinary for image uploads, applies business rules.
e. Data Layer (models/*.js)
- Mongoose schemas define data structures: Listing, User, Review, OTP.
- Interact with MongoDB for CRUD operations.
f. External Services
- MongoDB Atlas (NoSQL data store).
- Cloudinary (media hosting/upload).
g. Utilities
- CustomError & wrapAsync manage error flow across async middleware.

##### Architectural patterns & design principles
- MVC separation: Views (EJS) ↔ Controllers ↔ Models
- RESTful routing
- Centralized error handling
- Configuration abstraction (cloudConfig.js, .env)
- Seed data module (init/) for demo or testing

## Diagram (Mermaid)

```mermaid
graph TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["Client / Browser"]:::presentation
        StaticAssets["Static Assets\n(public/CSS, public/js)"]:::presentation
        EJSViews["EJS Views\n(views/)"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        App["Express Server\n(app.js)"]:::app
        CloudCfg["Cloudinary Config\n(cloudConfig.js)"]:::app
        DBConfig["MongoDB Config\n(schema.js)"]:::app
        Middleware["Global Middleware\n(middleware.js)"]:::app

        subgraph "Routing Layer"
            direction TB
            ListingRouter["Listing Routes\n(routes/listing.js)"]:::app
            UserRouter["User Routes\n(routes/user.js)"]:::app
            ReviewRouter["Review Routes\n(routes/review.js)"]:::app
        end

        subgraph "Controller Layer"
            direction TB
            ListingCtrl["Listing Controller\n(controllers/listing.js)"]:::app
            UserCtrl["User Controller\n(controllers/user.js)"]:::app
            ReviewCtrl["Review Controller\n(controllers/review.js)"]:::app
        end

        subgraph "Utilities"
            direction TB
            CustomErr["Custom Error Class\n(utils/CustomError.js)"]:::app
            WrapAsync["Async Wrapper\n(utils/wrapAsync.js)"]:::app
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        ListingModel["Listing Model\n(models/listing.js)"]:::data
        UserModel["User Model\n(models/user.js)"]:::data
        ReviewModel["Review Model\n(models/review.js)"]:::data
        OTPModel["OTP Model\n(models/otp.js)"]:::data
        MongoDB["MongoDB Atlas"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Cloudinary["Cloudinary"]:::external
    end

    %% Seed Data Module
    subgraph "Seed Module"
        direction TB
        InitIndex["Seed Index\n(init/index.js)"]:::app
        InitData["Seed Data\n(init/data.js)"]:::app
    end

    %% Connections
    Browser -->|"requests HTML/forms"| App
    Browser -->|"loads static assets"| StaticAssets
    Browser -->|"renders views"| EJSViews

    App --> CloudCfg
    App --> DBConfig
    App --> Middleware
    App --> ListingRouter
    App --> UserRouter
    App --> ReviewRouter

    ListingRouter --> ListingCtrl
    UserRouter --> UserCtrl
    ReviewRouter --> ReviewCtrl

    ListingCtrl --> ListingModel
    UserCtrl --> UserModel
    ReviewCtrl --> ReviewModel

    ListingCtrl --> CloudCfg --> Cloudinary
    ReviewCtrl --> CloudCfg --> Cloudinary

    ListingModel --> MongoDB
    UserModel --> MongoDB
    ReviewModel --> MongoDB
    OTPModel --> MongoDB

    InitIndex --> InitData
    InitIndex --> MongoDB

    %% Click Events
    click StaticAssets "https://github.com/hamza9021/roam-roster/tree/main/public/CSS/"
    click StaticAssets "https://github.com/hamza9021/roam-roster/tree/main/public/js/"
    click EJSViews "https://github.com/hamza9021/roam-roster/tree/main/views/"
    click App "https://github.com/hamza9021/roam-roster/blob/main/app.js"
    click CloudCfg "https://github.com/hamza9021/roam-roster/blob/main/cloudConfig.js"
    click DBConfig "https://github.com/hamza9021/roam-roster/blob/main/schema.js"
    click Middleware "https://github.com/hamza9021/roam-roster/blob/main/middleware.js"
    click ListingRouter "https://github.com/hamza9021/roam-roster/blob/main/routes/listing.js"
    click UserRouter "https://github.com/hamza9021/roam-roster/blob/main/routes/user.js"
    click ReviewRouter "https://github.com/hamza9021/roam-roster/blob/main/routes/review.js"
    click ListingCtrl "https://github.com/hamza9021/roam-roster/blob/main/controllers/listing.js"
    click UserCtrl "https://github.com/hamza9021/roam-roster/blob/main/controllers/user.js"
    click ReviewCtrl "https://github.com/hamza9021/roam-roster/blob/main/controllers/review.js"
    click ListingModel "https://github.com/hamza9021/roam-roster/blob/main/models/listing.js"
    click UserModel "https://github.com/hamza9021/roam-roster/blob/main/models/user.js"
    click ReviewModel "https://github.com/hamza9021/roam-roster/blob/main/models/review.js"
    click OTPModel "https://github.com/hamza9021/roam-roster/blob/main/models/otp.js"
    click CustomErr "https://github.com/hamza9021/roam-roster/blob/main/utils/CustomError.js"
    click WrapAsync "https://github.com/hamza9021/roam-roster/blob/main/utils/wrapAsync.js"
    click InitIndex "https://github.com/hamza9021/roam-roster/blob/main/init/index.js"
    click InitData "https://github.com/hamza9021/roam-roster/blob/main/init/data.js"

    %% Styles
    classDef presentation fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef app fill:#d4edda,stroke:#333,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px
```
