# one-project-one-month/node-utility-management-system architecture

> Architecture diagram of the GitHub repository one-project-one-month/node-utility-management-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/one-project-one-month/node-utility-management-system
- Repository: https://github.com/one-project-one-month/node-utility-management-system

## Overview

##### Project type and purpose
- This is a backend-centric full-stack service (no dedicated frontend in this repo) for a utility management system.
- Purpose: expose a RESTful HTTP API (Express.js + TypeScript) to manage properties, tenants, billing, customer service, invoices and receipts.

##### File structure
- Top-level:
- src/index.ts: entry point – boots Express server, loads middleware, routes, Swagger docs.
- prisma/: schema.prisma, migrations, seed.ts – defines & evolves PostgreSQL schema via Prisma ORM.
- docker-compose.yml: spins up a PostgreSQL container.
- Layered directories under src/ following a classic MVC/Service-layered monolith:
- routes/ → defines Express routes and versioned base path (/api/v1/…)
- controllers/ → HTTP handlers (one per resource)
- services/ → business logic, orchestrates data operations & domain rules
- lib/prismaClient.ts → single Prisma client instance for all DB access
- common/ → shared utilities (logging, CORS, JWT auth, password hashing, rate-limiting)
- middlewares/ → auth, validation (Zod), error handling
- validations/ → Zod schemas per endpoint
- docs/ → OpenAPI/Swagger config, component schemas and example responses
- helpers/ → one-off utility functions
- Key config/build files: tsconfig.json, package.json, Makefile, docker-compose.yml, .env example

##### Insights from README
- Core tech: Node.js (v22+), Express, TypeScript, PostgreSQL + Prisma ORM, Zod for validation, JWT + bcrypt for auth.
- Deployment: containerized DB and app on Render; Swagger UI available under /docs.
- Multi-role (Admin/Staff/Tenant) RBAC.
- CRUD endpoints for Users, Rooms, Tenants, Contracts, Bills, Invoices, Customer Services, Receipts, Total Units, Analytics.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client (Web UI / Mobile App)"]:::external

    subgraph "API Layer"
        Routes["Express Routes (/api/v1)"]:::http
        Val["Validation Middleware (Zod)"]:::http
        Auth["Auth Middleware (JWT, CORS)"]:::http
        Error["Error Handling Middleware"]:::http
        Controller["HTTP Controllers"]:::logic
    end

    subgraph "Service Layer"
        Services["Business Logic Services"]:::logic
    end

    subgraph "Data Layer"
        PrismaClient["Prisma Client"]:::data
        DB["PostgreSQL DB (5432)"]:::data
    end

    subgraph "Documentation"
        Swagger["Swagger UI (/docs)"]:::http
    end

    subgraph "External Services"
        SMTP["SMTP Mail Transporter"]:::extservice
        Resend["Resend API Transporter"]:::extservice
        Logger["Logging Sink"]:::extservice
        Docker["Docker Compose (PostgreSQL)"]:::extservice
    end

    Client -->|"HTTP/HTTPS"| Routes
    Routes --> Val --> Auth --> Controller
    Controller --> Services
    Services --> PrismaClient
    PrismaClient --> DB
    Services --> SMTP
    Services --> Resend
    Controller -->|Response / Errors| Client
    Controller --> Error -->|Error Response| Client

    Client --> Swagger
    Swagger -->|Serves docs from| SwaggerConfig["OpenAPI Config"]:::http

    Docker --> DB
    Logger -.-> Services

    click Routes "https://github.com/one-project-one-month/node-utility-management-system/tree/dev/src/routes/"
    click Controller "https://github.com/one-project-one-month/node-utility-management-system/tree/dev/src/controllers/"
    click Services "https://github.com/one-project-one-month/node-utility-management-system/tree/dev/src/services/"
    click PrismaClient "https://github.com/one-project-one-month/node-utility-management-system/blob/dev/src/lib/prismaClient.ts"
    click DB "https://github.com/one-project-one-month/node-utility-management-system/blob/dev/prisma/schema.prisma"
    click Docker "https://github.com/one-project-one-month/node-utility-management-system/blob/dev/docker-compose.yml"
    click Val "https://github.com/one-project-one-month/node-utility-management-system/blob/dev/src/middlewares/validationMiddleware.ts"
    click Auth "https://github.com/one-project-one-month/node-utility-management-system/blob/dev/src/middlewares/authMiddleware.ts"
    click Error "https://github.com/one-project-one-month/node-utility-management-system/blob/dev/src/middlewares/errorHandlingMiddleware.ts"
    click Logger "https://github.com/one-project-one-month/node-utility-management-system/blob/dev/src/common/utils/customLogger.ts"
    click SwaggerConfig "https://github.com/one-project-one-month/node-utility-management-system/blob/dev/src/docs/openapi.ts"
    click SMTP "https://github.com/one-project-one-month/node-utility-management-system/blob/dev/src/common/utils/mail-service/mailTransporter.ts"
    click Resend "https://github.com/one-project-one-month/node-utility-management-system/blob/dev/src/common/utils/mail-service/resendMailTransporter.ts"

    classDef http fill:#D0E7FF,stroke:#4A90E2,color:#000;
    classDef logic fill:#E0FFE0,stroke:#3C763D,color:#000;
    classDef data fill:#FFF4E0,stroke:#D78E00,color:#000;
    classDef extservice fill:#F5E0FF,stroke:#8E43D1,color:#000;
    classDef external fill:#E8E8E8,stroke:#888888,color:#000;
```
