# krushit1307/stayverse architecture

> Architecture diagram of the GitHub repository krushit1307/stayverse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krushit1307/stayverse
- Repository: https://github.com/krushit1307/stayverse

## Overview

1. **Overall shape**
   - StayVerse is a **full-stack monorepo** with two major application surfaces:
     - a **Node.js backend** at the repository root
     - a **React + TypeScript frontend** in `Frontend/Wander-lust-main`
   - The backend owns authentication, bookings, and data persistence; the frontend is a separate SPA-style client.

2. **Backend application boundary**
   - The root `app.js` is the backend entry point and likely wires together Express, middleware, routes, and error handling.
   - The backend is organized in classic layered form:
     - **routes** define HTTP endpoints
     - **controllers** implement request handling and business logic
     - **models** define domain entities
     - **middleware** handles cross-cutting concerns
     - **utils** contains external integrations

3. **Backend domain model**
   - The core server-side entities are:
     - `user`
     - `listing`
     - `booking`
     - `review`
     - `otp`
   - This tells you the app centers on a marketplace/rental workflow with user accounts, property/listing management, reservations, and feedback, plus OTP-based verification or password recovery.

4. **Backend request flow**
   - Requests enter through `routes/auth.js` and `routes/booking.js`.
   - Those routes dispatch to `controllers/auth.js` and `controllers/booking.js`.
   - Controllers then interact with the models and supporting utilities, and responses are returned through the Express layer.
   - `middleware/errorHandler.js` suggests centralized error mapping, while `middleware/validator.js` indicates input validation before controller execution.

5. **Authentication and account recovery**
   - `controllers/auth.js`, `routes/auth.js`, `models/user.js`, and `models/otp.js` together form the account lifecycle subsystem.
   - `utils/sendEmail.js` indicates email delivery is part of the auth flow, likely for OTP verification and/or forgot-password recovery.
   - `middleware/auth.js` protects authenticated routes, so some endpoints are gated behind session/token-based checks.

6. **Booking subsystem**
   - `controllers/booking.js`, `routes/booking.js`, and `models/booking.js` form the reservation workflow.
   - This subsystem likely links users to listings and captures booking state, dates, and related actions.
   - In an architecture diagram, booking should be shown as a domain flow that depends on authenticated users and listing records.

7. **Listing presentation on the server**
   - The `views/listings/*.ejs` files indicate the backend also has a **server-rendered listing UI**:
     - index
     - show
     - new
     - edit
   - That means the repo is not purely API-only; it includes an EJS view layer for listing management or fallback pages.
   - `init/data.js` and `init/index.js` suggest seed/bootstrap data for these listing views and backend storage.

8. **Frontend application boundary**
   - The frontend is a **Vite-powered React app** with TypeScript.
   - Key entry points are `src/main.tsx` and `src/App.tsx`.
   - This client is structured as a standalone UI with its own routing/pages and reusable components, separate from the root backend.

9. **Frontend page and component structure**
   - `src/pages` contains the major screens:
     - Home
     - ListingDetail
     - Bookings
     - NewListing
     - EditListing
     - Login/Register/ForgotPassword
     - NotFound
   - `src/components` contains shared UI building blocks such as Navbar, Footer, ListingCard, FilterChips, and SplashScreen.
   - `src/context/AuthContext.tsx` indicates shared client-side auth state, while `src/hooks/useInView.ts` supports UI behavior/animation/visibility logic.

10. **Frontend data and domain shaping**
   - `src/constants/amenities.ts` and `src/data/mockListings.js` show the frontend has domain-specific presentation data and mock fallback content.
   - This suggests the SPA can render listings even when backend data is unavailable or during early development.
   - Styling is split between component/global CSS files, so presentation is mostly client-owned.

11. **Infrastructure and delivery**
   - The repo is container-aware: it has a root `Dockerfile`, a frontend `Dockerfile`, `.dockerignore` files, and `docker-compose.yml`.
   - `.github/workflows/ci.yml` shows CI automation is part of the delivery pipeline.
   - `DOCKER_GUIDE.md` implies containerized local/dev deployment is a supported workflow.

12. **How the pieces connect**
   - The backend is the system of record for users, listings, bookings, reviews, and OTP/email workflows.
   - The frontend consumes that backend for authentication and user-facing listing/booking interactions, while also maintaining its own UI state via `AuthContext`.
   - A useful architecture diagram would show:
     - browser/client traffic to the React app
     - React app calls into the backend API
     - backend routes/controllers talk to models and email utilities
     - data persists through the model layer, with seeded initialization supported by `init/`
     - EJS views as a secondary server-rendered listing interface

Main entry points: [`Frontend/Wander-lust-main/src/App.tsx`](https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/App.tsx) (React app), [`controllers/booking.js`](https://github.com/krushit1307/stayverse/blob/main/controllers/booking.js) (Booking controller), [`routes/auth.js`](https://github.com/krushit1307/stayverse/blob/main/routes/auth.js) (Auth routes), [`routes/booking.js`](https://github.com/krushit1307/stayverse/blob/main/routes/booking.js) (Booking routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_app["app.js<br/>Express entry<br/>[app.js]"]
  node_auth_routes["Auth routes<br/>HTTP routes<br/>[auth.js]"]
  node_booking_routes["Booking routes<br/>HTTP routes<br/>[booking.js]"]
  node_auth_controller["Auth controller<br/>Auth logic<br/>[auth.js]"]
  node_booking_controller["Booking controller<br/>Booking logic<br/>[booking.js]"]
  node_auth_middleware["Auth guard<br/>Middleware<br/>[auth.js]"]
  node_validator_middleware["Validator<br/>Middleware<br/>[validator.js]"]
  node_error_handler["Error handler<br/>Middleware<br/>[errorHandler.js]"]
  node_user_model[("User<br/>Model<br/>[user.js]")]
  node_listing_model[("Listing<br/>Model<br/>[listing.js]")]
  node_booking_model[("Booking<br/>Model<br/>[booking.js]")]
  node_review_model[("Review<br/>Model<br/>[review.js]")]
  node_otp_model[("OTP<br/>Model<br/>[otp.js]")]
  node_send_email["Send email<br/>Mail utility<br/>[sendEmail.js]"]
  node_init_data["Seed data<br/>Bootstrap data<br/>[data.js]"]
  node_init_index["Init script<br/>Bootstrap<br/>[index.js]"]
  node_listing_views["Listing views<br/>EJS templates<br/>[index.ejs]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["React app<br/>Vite SPA<br/>[App.tsx]"]
  node_frontend_main["Main entry<br/>Client bootstrap<br/>[main.tsx]"]
  node_auth_context["Auth context<br/>Client state<br/>[AuthContext.tsx]"]
  node_pages["Pages<br/>Screens<br/>[Home.tsx]"]
  node_components["Components<br/>[Navbar.tsx]"]
  node_frontend_data["UI data<br/>Client data<br/>[mockListings.js]"]
end

subgraph group_infra["Delivery"]
  node_docker["Docker<br/>Container setup<br/>[docker-compose.yml]"]
  node_ci["CI workflow<br/>Automation<br/>[ci.yml]"]
end

node_app -->|"mounts"| node_auth_routes
node_app -->|"mounts"| node_booking_routes
node_app -->|"uses"| node_error_handler
node_auth_routes -->|"protects"| node_auth_middleware
node_auth_routes -->|"validates"| node_validator_middleware
node_auth_routes -->|"dispatches"| node_auth_controller
node_booking_routes -->|"protects"| node_auth_middleware
node_booking_routes -->|"validates"| node_validator_middleware
node_booking_routes -->|"dispatches"| node_booking_controller
node_auth_controller -->|"reads/writes"| node_user_model
node_auth_controller -->|"reads/writes"| node_otp_model
node_auth_controller -->|"sends"| node_send_email
node_booking_controller -->|"reads/writes"| node_booking_model
node_booking_controller -->|"reads"| node_listing_model
node_booking_controller -->|"reads"| node_user_model
node_booking_controller -.->|"relates to"| node_review_model
node_init_index -->|"loads"| node_init_data
node_init_index -->|"seeds"| node_listing_model
node_listing_views -->|"renders"| node_listing_model
node_frontend_main -->|"boots"| node_frontend_app
node_frontend_app -->|"uses"| node_auth_context
node_frontend_app -->|"navigates"| node_pages
node_pages -->|"composes"| node_components
node_pages -->|"uses"| node_frontend_data
node_frontend_app -.->|"alternates with"| node_listing_views
node_frontend_app -->|"calls API"| node_auth_routes
node_pages -->|"calls API"| node_booking_routes
node_docker -->|"packages"| node_app
node_docker -->|"packages"| node_frontend_app
node_ci -->|"validates"| node_docker

click node_app "https://github.com/krushit1307/stayverse/blob/main/app.js"
click node_auth_routes "https://github.com/krushit1307/stayverse/blob/main/routes/auth.js"
click node_booking_routes "https://github.com/krushit1307/stayverse/blob/main/routes/booking.js"
click node_auth_controller "https://github.com/krushit1307/stayverse/blob/main/controllers/auth.js"
click node_booking_controller "https://github.com/krushit1307/stayverse/blob/main/controllers/booking.js"
click node_auth_middleware "https://github.com/krushit1307/stayverse/blob/main/middleware/auth.js"
click node_validator_middleware "https://github.com/krushit1307/stayverse/blob/main/middleware/validator.js"
click node_error_handler "https://github.com/krushit1307/stayverse/blob/main/middleware/errorHandler.js"
click node_user_model "https://github.com/krushit1307/stayverse/blob/main/models/user.js"
click node_listing_model "https://github.com/krushit1307/stayverse/blob/main/models/listing.js"
click node_booking_model "https://github.com/krushit1307/stayverse/blob/main/models/booking.js"
click node_review_model "https://github.com/krushit1307/stayverse/blob/main/models/review.js"
click node_otp_model "https://github.com/krushit1307/stayverse/blob/main/models/otp.js"
click node_send_email "https://github.com/krushit1307/stayverse/blob/main/utils/sendEmail.js"
click node_init_data "https://github.com/krushit1307/stayverse/blob/main/init/data.js"
click node_init_index "https://github.com/krushit1307/stayverse/blob/main/init/index.js"
click node_listing_views "https://github.com/krushit1307/stayverse/blob/main/views/listings/index.ejs"
click node_frontend_app "https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/App.tsx"
click node_frontend_main "https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/main.tsx"
click node_auth_context "https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/context/AuthContext.tsx"
click node_pages "https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/pages/Home.tsx"
click node_components "https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/components/Navbar.tsx"
click node_frontend_data "https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/data/mockListings.js"
click node_docker "https://github.com/krushit1307/stayverse/blob/main/docker-compose.yml"
click node_ci "https://github.com/krushit1307/stayverse/blob/main/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_auth_routes,node_booking_routes,node_auth_controller,node_booking_controller,node_auth_middleware,node_validator_middleware,node_error_handler,node_user_model,node_listing_model,node_booking_model,node_review_model,node_otp_model,node_send_email,node_init_data,node_init_index,node_listing_views toneBlue
class node_frontend_app,node_frontend_main,node_auth_context,node_pages,node_components,node_frontend_data toneAmber
class node_docker,node_ci toneMint
```

## Components

### Backend

Node.js server, request flow, and domain persistence

- [app.js](https://github.com/krushit1307/stayverse/blob/main/app.js): Express entry · Backend entry point wiring server middleware and routes · `app.js`
- [Auth routes](https://github.com/krushit1307/stayverse/blob/main/routes/auth.js): HTTP routes · Authentication and account recovery endpoints · `routes/auth.js`
- [Booking routes](https://github.com/krushit1307/stayverse/blob/main/routes/booking.js): HTTP routes · Reservation endpoints · `routes/booking.js`
- [Auth controller](https://github.com/krushit1307/stayverse/blob/main/controllers/auth.js): Auth logic · Login, register, OTP, and recovery flows · `controllers/auth.js`
- [Booking controller](https://github.com/krushit1307/stayverse/blob/main/controllers/booking.js): Booking logic · Booking creation and user-listing reservation handling · `controllers/booking.js`
- [Auth guard](https://github.com/krushit1307/stayverse/blob/main/middleware/auth.js): Middleware · Protects authenticated server routes · `middleware/auth.js`
- [Validator](https://github.com/krushit1307/stayverse/blob/main/middleware/validator.js): Middleware · Validates incoming request data · `middleware/validator.js`
- [Error handler](https://github.com/krushit1307/stayverse/blob/main/middleware/errorHandler.js): Middleware · Centralized error mapping and response handling · `middleware/errorHandler.js`
- [User](https://github.com/krushit1307/stayverse/blob/main/models/user.js): Model · Account identity and authentication data · `models/user.js`
- [Listing](https://github.com/krushit1307/stayverse/blob/main/models/listing.js): Model · Property or rental listing record · `models/listing.js`
- [Booking](https://github.com/krushit1307/stayverse/blob/main/models/booking.js): Model · Reservation state and booking records · `models/booking.js`
- [Review](https://github.com/krushit1307/stayverse/blob/main/models/review.js): Model · User feedback on listings · `models/review.js`
- [OTP](https://github.com/krushit1307/stayverse/blob/main/models/otp.js): Model · One-time verification or recovery codes · `models/otp.js`
- [Send email](https://github.com/krushit1307/stayverse/blob/main/utils/sendEmail.js): Mail utility · Email delivery for OTP and recovery flows · `utils/sendEmail.js`
- [Seed data](https://github.com/krushit1307/stayverse/blob/main/init/data.js): Bootstrap data · Initial listing/bootstrap dataset · `init/data.js`
- [Init script](https://github.com/krushit1307/stayverse/blob/main/init/index.js): Bootstrap · Startup seeding and initialization logic · `init/index.js`
- [Listing views](https://github.com/krushit1307/stayverse/blob/main/views/listings/index.ejs): EJS templates · Server-rendered listing pages for browse, detail, create, and edit · `views/listings/index.ejs`

### Frontend

React + TypeScript single-page client

- [React app](https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/App.tsx): Vite SPA · Frontend application shell and routing · `Frontend/Wander-lust-main/src/App.tsx`
- [Main entry](https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/main.tsx): Client bootstrap · Client-side React mount point · `Frontend/Wander-lust-main/src/main.tsx`
- [Auth context](https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/context/AuthContext.tsx): Client state · Shared frontend authentication state · `Frontend/Wander-lust-main/src/context/AuthContext.tsx`
- [Pages](https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/pages/Home.tsx): Screens · Home, listing detail, bookings, auth, and listing forms · `Frontend/Wander-lust-main/src/pages/Home.tsx`
- [Components](https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/components/Navbar.tsx): UI components · Shared UI pieces such as navbar, cards, footer, and splash screen · `Frontend/Wander-lust-main/src/components/Navbar.tsx`
- [UI data](https://github.com/krushit1307/stayverse/blob/main/Frontend/Wander-lust-main/src/data/mockListings.js): Client data · Amenity constants and mock listings for presentation fallback · `Frontend/Wander-lust-main/src/data/mockListings.js`

### Delivery

Container and CI pipeline

- [Docker](https://github.com/krushit1307/stayverse/blob/main/docker-compose.yml): Container setup · Repository containerization for backend and frontend · `docker-compose.yml`
- [CI workflow](https://github.com/krushit1307/stayverse/blob/main/.github/workflows/ci.yml): Automation · Continuous integration pipeline · `.github/workflows/ci.yml`

## Connections

- app.js → Auth routes: mounts · Registers authentication routes on the server
- app.js → Booking routes: mounts · Registers booking routes on the server
- app.js → Error handler: uses · Centralized server error handling
- Auth routes → Auth guard: protects · Some auth endpoints require authenticated access
- Auth routes → Validator: validates · Validates auth request payloads
- Auth routes → Auth controller: dispatches · Routes delegate auth requests to controller logic
- Booking routes → Auth guard: protects · Booking operations are gated by auth
- Booking routes → Validator: validates · Validates booking request payloads
- Booking routes → Booking controller: dispatches · Routes delegate reservation requests to controller logic
- Auth controller → User: reads/writes · Manages account records
- Auth controller → OTP: reads/writes · Creates and checks OTP records
- Auth controller → Send email: sends · Delivers OTP or recovery emails
- Booking controller → Booking: reads/writes · Persists booking records
- Booking controller → Listing: reads · Resolves the listing being reserved
- Booking controller → User: reads · Uses authenticated user identity
- Booking controller → Review: relates to · Bookings sit alongside listing feedback data
- Init script → Seed data: loads · Bootstraps seed data
- Init script → Listing: seeds · Initializes listing storage
- Listing views → Listing: renders · Server-rendered listing pages are backed by listing data
- Main entry → React app: boots · Mounts the React application
- React app → Auth context: uses · Shares auth state across the client
- React app → Pages: navigates · Page-level routing and screen composition
- Pages → Components: composes · Screens reuse shared UI building blocks
- Pages → UI data: uses · Supports presentation with mock or static data
- React app → Listing views: alternates with · Backend also exposes server-rendered listing pages
- React app → Auth routes: calls API · Client auth flows depend on backend endpoints
- Pages → Booking routes: calls API · Booking screens depend on reservation endpoints
- Docker → app.js: packages · Containerizes backend service
- Docker → React app: packages · Containerizes frontend service
- CI workflow → Docker: validates · CI supports build and delivery workflow
