# ashutoshmore24/smart-apartment-maintenance-management-system architecture

> Architecture diagram of the GitHub repository ashutoshmore24/smart-apartment-maintenance-management-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashutoshmore24/smart-apartment-maintenance-management-system
- Repository: https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system

## Overview

1. **Overall shape**
   - This is a three-part, database-centric monorepo: a **React frontend**, an **Express/Node backend**, and a **MySQL schema layer**.
   - The backend is the system of record and business logic layer; the frontend is a thin role-based client; the SQL files define the core data model and some automation.

2. **Runtime boundaries**
   - **Frontend** runs as a Vite-built single-page app in the browser.
   - **Backend** runs as a Node.js/Express HTTP API.
   - **Database** is MySQL, populated and maintained through SQL scripts in the `database/` folder plus backend repair/migration utilities.

3. **Frontend architecture**
   - `frontend/src/api.js` is the API boundary for server communication.
   - `AuthContext.jsx` likely holds login state, tokens, and role information for route guarding and UI decisions.
   - Pages are split by user journey and role: `LandingPage`, `LoginPage`, `RegisterPage`, `OtpPage`, `DashboardPage`, `AdminDashboard`, `TechnicianDashboard`, `PaymentPage`, and `AddPayment`.
   - Shared UI is componentized into navbar, notifications, request lists, stats cards, task cards, payment widgets, and status badges.

4. **Role-based user flows**
   - The app is explicitly organized around **Resident**, **Technician**, and **Admin** roles.
   - Residents create maintenance requests, review request status, and handle payment-related views.
   - Technicians consume assigned work, update request progress, and submit maintenance cost on completion.
   - Admins monitor system-wide activity, users, requests, and analytics.

5. **Backend request handling**
   - `backend/server.js` is the API entrypoint and wires Express, middleware, routes, and database connectivity.
   - Routes are grouped by concern: `auth`, `user`, `request`, `asset`, `payment`, and `notification`.
   - Controllers hold the business logic, with `auth.controller.js` and `notification.controller.js` explicitly present in the tree.

6. **Security and session boundary**
   - `backend/middleware/auth.middleware.js` is the main access-control boundary for protected API endpoints.
   - `backend/utils/jwt.js` indicates token-based authentication.
   - The presence of OTP and Google utilities (`sendOtpEmail.js`, `google.js`) shows multiple login/verification paths, likely email OTP plus Google sign-in.

7. **Notifications and communication**
   - Notifications are a first-class subsystem, with dedicated controller, routes, and a script for creating the notifications table.
   - `mailer.js` and `sendOtpEmail.js` suggest email is used both for authentication and user-facing alerts.
   - This makes notification delivery a backend responsibility rather than a frontend-only concern.

8. **Payments and billing flow**
   - The payment subsystem is separated into its own route set and frontend screens.
   - The readme says completion requires cost entry and that maintenance bills are generated automatically; that implies the backend/database enforce billing rules after request resolution.
   - Payment history and pending bills are presented to residents through dedicated UI components like `PaymentForm` and `RecentPayments`.

9. **Database structure and business rules**
   - `database/schema.sql`, `seed.sql`, and `trigger.sql` define the core persistence model, starter data, and DB-level automation.
   - The repo also includes `queries.sql` and `railway_reset.sql`, which suggests support for manual SQL operations and environment resets.
   - The backend includes several repair/migration helpers such as `migrations.js`, `force_migrate.js`, `fix_fk.js`, and `alter_db.js`, indicating that schema evolution and constraint fixes are operational concerns in this project.

10. **Operational/tooling layer**
   - There are multiple backend test scripts (`test_db.js`, `test_http_post.js`, `test_railway.js`, etc.), showing the backend is validated with ad hoc integration checks rather than a single formal test framework.
   - `scripts/` contains schema utility scripts like adding columns or creating tables, reinforcing that DB maintenance is part of the codebase workflow.
   - Frontend deployment is prepared with `vercel.json`, while the backend is configured as a conventional Node service on port 5000.

11. **Primary data flow**
   - User action starts in the browser UI, goes through the frontend API layer, reaches an Express route, is authenticated/authorized by middleware, then processed by a controller.
   - Controllers read/write MySQL through `backend/db.js`, and some outcomes are additionally enforced or automated by SQL triggers.
   - Results return to the frontend for dashboard updates, status badges, notifications, and payment views.

12. **What to draw in an architecture diagram**
   - Draw three major boxes: **React client**, **Express API**, **MySQL database**.
   - Inside the API box, separate **auth**, **requests/assets**, **payments**, **notifications**, and **user/admin** flows.
   - Show auxiliary external integrations for **email/OTP** and **Google authentication**.
   - Show the database as containing both domain tables and trigger-driven automation, with a separate maintenance/migration path for schema repair and setup.

Main entry points: [`backend/server.js`](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/server.js) (Server entry), [`frontend/src/App.jsx`](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/App.jsx) (App shell), [`database/schema.sql`](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/database/schema.sql) (Schema), [`backend/db.js`](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/db.js) (DB layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React client"]
  node_frontend_app["App shell<br/>React/Vite SPA<br/>[App.jsx]"]
  node_frontend_api["API client<br/>HTTP boundary<br/>[api.js]"]
  node_frontend_auth["Auth state<br/>session context<br/>[AuthContext.jsx]"]
  node_frontend_dashboards["Role pages<br/>dashboard views<br/>[DashboardPage.jsx]"]
  node_frontend_authpages["Auth pages<br/>entry flows<br/>[LoginPage.jsx]"]
  node_frontend_payment["Payments UI<br/>billing views<br/>[PaymentPage.jsx]"]
  node_frontend_shared["Shared UI<br/>components<br/>[Navbar.jsx]"]
end

subgraph group_backend["Express API"]
  node_backend_server["Server entry<br/>Express API<br/>[server.js]"]
  node_backend_auth["Auth flow<br/>identity logic<br/>[auth.controller.js]"]
  node_backend_security["Access control<br/>middleware/jwt<br/>[auth.middleware.js]"]
  node_backend_requests["Requests<br/>service routes<br/>[request.routes.js]"]
  node_backend_payment["Payments<br/>billing routes<br/>[payment.routes.js]"]
  node_backend_notifications["Notifications<br/>notification service"]
  node_backend_users["Users<br/>profile/admin routes<br/>[user.routes.js]"]
  node_backend_utils["Auth utils<br/>email/oauth/jwt<br/>[jwt.js]"]
  node_backend_db["DB layer<br/>MySQL connector<br/>[db.js]"]
end

subgraph group_database["MySQL data"]
  node_db_schema[("Schema<br/>SQL model<br/>[schema.sql]")]
  node_db_seed["Seed data<br/>SQL bootstrap<br/>[seed.sql]"]
  node_db_triggers["Triggers<br/>DB automation<br/>[trigger.sql]"]
  node_db_queries["SQL ops<br/>manual scripts<br/>[queries.sql]"]
end

subgraph group_ops["Maintenance"]
  node_ops_migrate["Migrations<br/>repair scripts<br/>[migrations.js]"]
  node_ops_scripts["Schema tools<br/>maintenance scripts<br/>[check_schema.js]"]
end

node_frontend_app -->|"calls API"| node_frontend_api
node_frontend_app -->|"uses state"| node_frontend_auth
node_frontend_app -->|"renders"| node_frontend_dashboards
node_frontend_app -->|"routes to"| node_frontend_authpages
node_frontend_app -->|"shows"| node_frontend_payment
node_frontend_app -->|"composes"| node_frontend_shared
node_backend_server -->|"protects"| node_backend_security
node_backend_server -->|"mounts"| node_backend_auth
node_backend_server -->|"mounts"| node_backend_requests
node_backend_server -->|"mounts"| node_backend_payment
node_backend_server -->|"mounts"| node_backend_notifications
node_backend_server -->|"mounts"| node_backend_users
node_backend_auth -->|"uses"| node_backend_utils
node_backend_notifications -->|"sends mail"| node_backend_utils
node_backend_requests -->|"reads/writes"| node_backend_db
node_backend_payment -->|"reads/writes"| node_backend_db
node_backend_notifications -->|"reads/writes"| node_backend_db
node_backend_users -->|"reads/writes"| node_backend_db
node_backend_server -->|"connects"| node_backend_db
node_backend_db -->|"targets"| node_db_schema
node_db_schema -->|"bootstraps"| node_db_seed
node_db_schema -->|"automates"| node_db_triggers
node_db_schema -->|"supports"| node_db_queries
node_ops_migrate -->|"repairs"| node_db_schema
node_ops_scripts -->|"maintains"| node_db_schema
node_frontend_payment -->|"submits"| node_backend_payment
node_frontend_dashboards -->|"views tasks"| node_backend_requests
node_frontend_shared -->|"shows alerts"| node_backend_notifications

click node_frontend_app "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/App.jsx"
click node_frontend_api "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/api.js"
click node_frontend_auth "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/context/AuthContext.jsx"
click node_frontend_dashboards "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/pages/DashboardPage.jsx"
click node_frontend_authpages "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/pages/LoginPage.jsx"
click node_frontend_payment "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/pages/PaymentPage.jsx"
click node_frontend_shared "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/components/Navbar.jsx"
click node_backend_server "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/server.js"
click node_backend_auth "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/controllers/auth.controller.js"
click node_backend_security "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/middleware/auth.middleware.js"
click node_backend_requests "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/routes/request.routes.js"
click node_backend_payment "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/routes/payment.routes.js"
click node_backend_notifications "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/controllers/notification.controller.js"
click node_backend_users "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/routes/user.routes.js"
click node_backend_utils "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/utils/jwt.js"
click node_backend_db "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/db.js"
click node_db_schema "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/database/schema.sql"
click node_db_seed "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/database/seed.sql"
click node_db_triggers "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/database/trigger.sql"
click node_db_queries "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/database/queries.sql"
click node_ops_migrate "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/migrations.js"
click node_ops_scripts "https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/scripts/check_schema.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_frontend_app,node_frontend_api,node_frontend_auth,node_frontend_dashboards,node_frontend_authpages,node_frontend_payment,node_frontend_shared toneBlue
class node_backend_server,node_backend_auth,node_backend_security,node_backend_requests,node_backend_payment,node_backend_notifications,node_backend_users,node_backend_utils,node_backend_db toneAmber
class node_db_schema,node_db_seed,node_db_triggers,node_db_queries toneMint
class node_ops_migrate,node_ops_scripts toneRose
```

## Components

### React client

Browser SPA for residents, technicians, and admins.

- [App shell](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/App.jsx): React/Vite SPA · Top-level client app and routing shell. · `frontend/src/App.jsx`
- [API client](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/api.js): HTTP boundary · Frontend server communication layer. · `frontend/src/api.js`
- [Auth state](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/context/AuthContext.jsx): session context · Login state, tokens, and role-aware UI gating. · `frontend/src/context/AuthContext.jsx`
- [Role pages](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/pages/DashboardPage.jsx): dashboard views · Resident, technician, and admin-facing pages. · `frontend/src/pages/DashboardPage.jsx`
- [Auth pages](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/pages/LoginPage.jsx): entry flows · Landing, login, register, OTP, and auth success screens. · `frontend/src/pages/LoginPage.jsx`
- [Payments UI](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/pages/PaymentPage.jsx): billing views · Payment page, add payment flow, and payment widgets. · `frontend/src/pages/PaymentPage.jsx`
- [Shared UI](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/frontend/src/components/Navbar.jsx): components · Reusable widgets for requests, tasks, stats, badges, notifications, and navigation. · `frontend/src/components/Navbar.jsx`

### Express API

Node/Express application handling auth, requests, payments, and notifications.

- [Server entry](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/server.js): Express API · Wires middleware, routes, and database connectivity. · `backend/server.js`
- [Auth flow](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/controllers/auth.controller.js): identity logic · Authentication controller and route boundary. · `backend/controllers/auth.controller.js`
- [Access control](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/middleware/auth.middleware.js): middleware/jwt · Protected-route authorization and token handling. · `backend/middleware/auth.middleware.js`
- [Requests](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/routes/request.routes.js): service routes · Maintenance request lifecycle and asset-related handling. · `backend/routes/request.routes.js`
- [Payments](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/routes/payment.routes.js): billing routes · Cost entry, bills, and payment history endpoints. · `backend/routes/payment.routes.js`
- [Notifications](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/controllers/notification.controller.js): notification service · Notification controller and route handling. · `backend/controllers/notification.controller.js`
- [Users](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/routes/user.routes.js): profile/admin routes · User and admin-facing API surface. · `backend/routes/user.routes.js`
- [Auth utils](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/utils/jwt.js): email/oauth/jwt · JWT, Google sign-in, mailer, and OTP email helpers. · `backend/utils/jwt.js`
- [DB layer](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/db.js): MySQL connector · Shared database access module used by controllers and routes. · `backend/db.js`

### MySQL data

Schema, seeds, triggers, and SQL maintenance scripts.

- [Schema](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/database/schema.sql): SQL model · Core tables and persistence structure. · `database/schema.sql`
- [Seed data](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/database/seed.sql): SQL bootstrap · Starter rows and sample data. · `database/seed.sql`
- [Triggers](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/database/trigger.sql): DB automation · Database-level automation and derived billing behavior. · `database/trigger.sql`
- [SQL ops](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/database/queries.sql): manual scripts · Ad hoc query and reset scripts for operational database work. · `database/queries.sql`

### Maintenance

Repair, migration, and verification helpers around the main stack.

- [Migrations](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/migrations.js): repair scripts · Schema fixes, migration helpers, and constraint repair utilities. · `backend/migrations.js`
- [Schema tools](https://github.com/ashutoshmore24/smart-apartment-maintenance-management-system/blob/main/backend/scripts/check_schema.js): maintenance scripts · Utility scripts for schema checks and table setup. · `backend/scripts/check_schema.js`

## Connections

- App shell → API client: calls API · Browser UI sends requests through the frontend API layer.
- App shell → Auth state: uses state · Pages read auth state for routing and role-based UI.
- App shell → Role pages: renders · Primary role dashboards and work views.
- App shell → Auth pages: routes to · Authentication and onboarding screens.
- App shell → Payments UI: shows · Payment-related resident views and forms.
- App shell → Shared UI: composes · Shared navigation, stats, lists, and badges.
- Server entry → Access control: protects · Middleware guards protected endpoints.
- Server entry → Auth flow: mounts · Authentication routes and logic are exposed from the server.
- Server entry → Requests: mounts · Maintenance request APIs.
- Server entry → Payments: mounts · Billing and payment APIs.
- Server entry → Notifications: mounts · Notification APIs.
- Server entry → Users: mounts · User and admin APIs.
- Auth flow → Auth utils: uses · Auth flow depends on JWT, OTP email, Google sign-in, and mail delivery.
- Notifications → Auth utils: sends mail · Notification delivery may use shared mail helpers.
- Requests → DB layer: reads/writes · Request and asset state is persisted in MySQL.
- Payments → DB layer: reads/writes · Billing data and payment history are stored in MySQL.
- Notifications → DB layer: reads/writes · Notifications are persisted in MySQL.
- Users → DB layer: reads/writes · User and dashboard data comes from MySQL.
- Server entry → DB layer: connects · Central database connection used by the API.
- DB layer → Schema: targets · Shared connector talks to the schema-defined MySQL database.
- Schema → Seed data: bootstraps · Seed scripts populate starter data.
- Schema → Triggers: automates · Triggers enforce derived behavior and billing automation.
- Schema → SQL ops: supports · Operational SQL scripts act on the same schema.
- Migrations → Schema: repairs · Migration and fix scripts adjust schema and constraints.
- Schema tools → Schema: maintains · Schema helper scripts create or validate database structure.
- Payments UI → Payments: submits · Payment screens drive billing endpoints.
- Role pages → Requests: views tasks · Role dashboards consume request and assignment data.
- Shared UI → Notifications: shows alerts · Notification UI reflects backend notification delivery.
