# zalte45/sparespace-backend architecture

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

- Interactive diagram: https://gitdiagram.com/zalte45/sparespace-backend
- Repository: https://github.com/zalte45/sparespace-backend

## Overview

SpareSpace Backend is an API for account access, space listings, and rentals. A client reaches the Express app, which mounts authentication, listing, and booking routes; handlers validate requests, apply session protection where required, and return API results. Listing handlers manage owner listings and image uploads. Booking handlers preview pricing, check availability, create and manage bookings, using MongoDB-backed listing/user models and PostgreSQL booking operations. The README documents OTP verification and password recovery. Relationships below follow shown routes, imports, and calls; unsampled wiring is omitted.

Main entry points: [`src/controllers/booking.controller.js`](https://github.com/zalte45/sparespace-backend/blob/main/src/controllers/booking.controller.js) (Booking workflows), [`src/controllers/auth.controller.js`](https://github.com/zalte45/sparespace-backend/blob/main/src/controllers/auth.controller.js) (Account workflows), [`src/controllers/spaceListing.controller.js`](https://github.com/zalte45/sparespace-backend/blob/main/src/controllers/spaceListing.controller.js) (Listing workflows), [`src/app.js`](https://github.com/zalte45/sparespace-backend/blob/main/src/app.js) (Express API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_app["Express API<br/>[app.js]"]
end

subgraph group_identity["Identity and access"]
  node_auth_routes["Auth routes<br/>[auth.routes.js]"]
  node_auth_controller["Account workflows<br/>[auth.controller.js]"]
  node_auth_middleware["Session guard<br/>[auth.middleware.js]"]
  node_users[("User records<br/>[user.model.js]")]
  node_sessions[("Sessions<br/>[session.model.js]")]
  node_otps[("OTP records<br/>[otp.model.js]")]
end

subgraph group_spaces["Space listings"]
  node_listing_routes["Listing routes<br/>[listing.routes.js]"]
  node_listing_controller["Listing workflows"]
  node_listing_validation["Listing validation"]
  node_upload_middleware["Image upload middleware<br/>[upload.js]"]
  node_listings[("Listing records<br/>[listing.model.js]")]
end

subgraph group_rentals["Booking lifecycle"]
  node_booking_routes["Booking routes<br/>[booking.routes.js]"]
  node_booking_controller["Booking workflows"]
  node_booking_model[("Booking model<br/>[booking.model.js]")]
end

subgraph group_integrations["Persistence and services"]
  node_email_service["Email sender<br/>[email.service.js]"]
  node_email_provider["Email provider"]
  node_cloudinary_service["Image service<br/>[cloudinary.js]"]
  node_cloudinary["Cloudinary"]
  node_postgres_config["PostgreSQL client<br/>[postgres.js]"]
  node_postgres[("PostgreSQL bookings")]
  node_config["Runtime configuration<br/>[config.js]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_auth_routes
node_app -->|"mounts routes"| node_listing_routes
node_app -->|"mounts routes"| node_booking_routes
node_auth_routes -->|"dispatches to"| node_auth_controller
node_auth_controller -->|"reads and writes"| node_users
node_auth_controller -->|"reads and writes"| node_sessions
node_auth_controller -->|"reads and writes"| node_otps
node_auth_controller -->|"sends OTP"| node_email_service
node_email_service -->|"sends mail"| node_email_provider
node_auth_middleware -->|"checks session"| node_sessions
node_listing_routes -->|"dispatches to"| node_listing_controller
node_listing_routes -->|"protects routes"| node_auth_middleware
node_listing_routes -->|"uploads files"| node_upload_middleware
node_listing_controller -->|"validates data"| node_listing_validation
node_listing_controller -->|"looks up owner"| node_users
node_listing_controller -->|"creates and queries"| node_listings
node_listing_controller -->|"uploads images"| node_cloudinary_service
node_cloudinary_service -.->|"stores images"| node_cloudinary
node_booking_routes -->|"dispatches to"| node_booking_controller
node_booking_routes -->|"protects routes"| node_auth_middleware
node_booking_controller -->|"checks listing"| node_listings
node_booking_controller -->|"loads host data"| node_users
node_booking_controller -->|"queries bookings"| node_postgres_config
node_booking_controller -->|"creates and queries"| node_postgres
node_booking_controller -->|"manages legacy bookings"| node_booking_model
node_postgres_config -->|"uses settings"| node_config

click node_app "https://github.com/zalte45/sparespace-backend/blob/main/src/app.js"
click node_auth_routes "https://github.com/zalte45/sparespace-backend/blob/main/src/routes/auth.routes.js"
click node_auth_controller "https://github.com/zalte45/sparespace-backend/blob/main/src/controllers/auth.controller.js"
click node_auth_middleware "https://github.com/zalte45/sparespace-backend/blob/main/src/middleware/auth.middleware.js"
click node_users "https://github.com/zalte45/sparespace-backend/blob/main/src/model/user.model.js"
click node_sessions "https://github.com/zalte45/sparespace-backend/blob/main/src/model/session.model.js"
click node_otps "https://github.com/zalte45/sparespace-backend/blob/main/src/model/otp.model.js"
click node_email_service "https://github.com/zalte45/sparespace-backend/blob/main/src/services/email.service.js"
click node_listing_routes "https://github.com/zalte45/sparespace-backend/blob/main/src/routes/listing.routes.js"
click node_listing_controller "https://github.com/zalte45/sparespace-backend/blob/main/src/controllers/spaceListing.controller.js"
click node_listing_validation "https://github.com/zalte45/sparespace-backend/blob/main/src/middleware/listingValidation.js"
click node_upload_middleware "https://github.com/zalte45/sparespace-backend/blob/main/src/middleware/upload.js"
click node_listings "https://github.com/zalte45/sparespace-backend/blob/main/src/model/listing.model.js"
click node_cloudinary_service "https://github.com/zalte45/sparespace-backend/blob/main/src/services/cloudinary.js"
click node_booking_routes "https://github.com/zalte45/sparespace-backend/blob/main/src/routes/booking.routes.js"
click node_booking_controller "https://github.com/zalte45/sparespace-backend/blob/main/src/controllers/booking.controller.js"
click node_booking_model "https://github.com/zalte45/sparespace-backend/blob/main/src/model/booking.model.js"
click node_postgres_config "https://github.com/zalte45/sparespace-backend/blob/main/src/config/postgres.js"
click node_config "https://github.com/zalte45/sparespace-backend/blob/main/src/config/config.js"

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_client toneBlue
class node_auth_routes,node_auth_controller,node_auth_middleware,node_users,node_sessions,node_otps toneAmber
class node_listing_routes,node_listing_controller,node_listing_validation,node_upload_middleware,node_listings toneMint
class node_booking_routes,node_booking_controller,node_booking_model toneRose
class node_email_service,node_email_provider,node_cloudinary_service,node_cloudinary,node_postgres_config,node_postgres,node_config toneIndigo
```

## Components

### API entry

- [Express API](https://github.com/zalte45/sparespace-backend/blob/main/src/app.js): `src/app.js`

### Identity and access

- [Auth routes](https://github.com/zalte45/sparespace-backend/blob/main/src/routes/auth.routes.js): `src/routes/auth.routes.js`
- [Account workflows](https://github.com/zalte45/sparespace-backend/blob/main/src/controllers/auth.controller.js): `src/controllers/auth.controller.js`
- [Session guard](https://github.com/zalte45/sparespace-backend/blob/main/src/middleware/auth.middleware.js): `src/middleware/auth.middleware.js`
- [User records](https://github.com/zalte45/sparespace-backend/blob/main/src/model/user.model.js): `src/model/user.model.js`
- [Sessions](https://github.com/zalte45/sparespace-backend/blob/main/src/model/session.model.js): `src/model/session.model.js`
- [OTP records](https://github.com/zalte45/sparespace-backend/blob/main/src/model/otp.model.js): `src/model/otp.model.js`

### Space listings

- [Listing routes](https://github.com/zalte45/sparespace-backend/blob/main/src/routes/listing.routes.js): `src/routes/listing.routes.js`
- [Listing workflows](https://github.com/zalte45/sparespace-backend/blob/main/src/controllers/spaceListing.controller.js): `src/controllers/spaceListing.controller.js`
- [Listing validation](https://github.com/zalte45/sparespace-backend/blob/main/src/middleware/listingValidation.js): `src/middleware/listingValidation.js`
- [Image upload middleware](https://github.com/zalte45/sparespace-backend/blob/main/src/middleware/upload.js): `src/middleware/upload.js`
- [Listing records](https://github.com/zalte45/sparespace-backend/blob/main/src/model/listing.model.js): `src/model/listing.model.js`

### Booking lifecycle

- [Booking routes](https://github.com/zalte45/sparespace-backend/blob/main/src/routes/booking.routes.js): `src/routes/booking.routes.js`
- [Booking workflows](https://github.com/zalte45/sparespace-backend/blob/main/src/controllers/booking.controller.js): `src/controllers/booking.controller.js`
- [Booking model](https://github.com/zalte45/sparespace-backend/blob/main/src/model/booking.model.js): `src/model/booking.model.js`

### Persistence and services

- [Email sender](https://github.com/zalte45/sparespace-backend/blob/main/src/services/email.service.js): `src/services/email.service.js`
- **Email provider**
- [Image service](https://github.com/zalte45/sparespace-backend/blob/main/src/services/cloudinary.js): `src/services/cloudinary.js`
- **Cloudinary**
- [PostgreSQL client](https://github.com/zalte45/sparespace-backend/blob/main/src/config/postgres.js): `src/config/postgres.js`
- **PostgreSQL bookings**
- [Runtime configuration](https://github.com/zalte45/sparespace-backend/blob/main/src/config/config.js): `src/config/config.js`

### Other components

- **API client**

## Connections

- API client → Express API: sends requests (evidence: `README.md`)
- Express API → Auth routes: mounts routes (evidence: `src/app.js`)
- Express API → Listing routes: mounts routes (evidence: `src/app.js`)
- Express API → Booking routes: mounts routes (evidence: `src/app.js`)
- Auth routes → Account workflows: dispatches to (evidence: `src/routes/auth.routes.js`)
- Account workflows → User records: reads and writes (evidence: `src/controllers/auth.controller.js`)
- Account workflows → Sessions: reads and writes (evidence: `src/controllers/auth.controller.js`)
- Account workflows → OTP records: reads and writes (evidence: `src/controllers/auth.controller.js`)
- Account workflows → Email sender: sends OTP (evidence: `src/controllers/auth.controller.js`)
- Email sender → Email provider: sends mail (evidence: `src/services/email.service.js`)
- Session guard → Sessions: checks session (evidence: `src/middleware/auth.middleware.js`)
- Listing routes → Listing workflows: dispatches to (evidence: `src/routes/listing.routes.js`)
- Listing routes → Session guard: protects routes (evidence: `src/routes/listing.routes.js`)
- Listing routes → Image upload middleware: uploads files (evidence: `src/routes/listing.routes.js`)
- Listing workflows → Listing validation: validates data (evidence: `src/controllers/spaceListing.controller.js`)
- Listing workflows → User records: looks up owner (evidence: `src/controllers/spaceListing.controller.js`)
- Listing workflows → Listing records: creates and queries (evidence: `src/controllers/spaceListing.controller.js`)
- Listing workflows → Image service: uploads images (evidence: `src/controllers/spaceListing.controller.js`)
- Image service → Cloudinary: stores images
- Booking routes → Booking workflows: dispatches to (evidence: `src/routes/booking.routes.js`)
- Booking routes → Session guard: protects routes (evidence: `src/routes/booking.routes.js`)
- Booking workflows → Listing records: checks listing (evidence: `src/controllers/booking.controller.js`)
- Booking workflows → User records: loads host data (evidence: `src/controllers/booking.controller.js`)
- Booking workflows → PostgreSQL client: queries bookings (evidence: `src/controllers/booking.controller.js`)
- Booking workflows → PostgreSQL bookings: creates and queries (evidence: `src/controllers/booking.controller.js`)
- Booking workflows → Booking model: manages legacy bookings (evidence: `src/controllers/booking.controller.js`)
- PostgreSQL client → Runtime configuration: uses settings (evidence: `src/config/config.js`)
