How ashutoshmore24/smart-apartment-maintenance-management-system works
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: server.js Server entry · App.jsx App shell · schema.sql Schema · db.js DB layer
Components 22
React client
Browser SPA for residents, technicians, and admins.
- App shell · Top-level client app and routing shell.
frontend/src/App.jsx - API client · Frontend server communication layer.
frontend/src/api.js - Auth state · Login state, tokens, and role-aware UI gating.
frontend/src/context/AuthContext.jsx - Role pages · Resident, technician, and admin-facing pages.
frontend/src/pages/DashboardPage.jsx - Auth pages · Landing, login, register, OTP, and auth success screens.
frontend/src/pages/LoginPage.jsx - Payments UI · Payment page, add payment flow, and payment widgets.
frontend/src/pages/PaymentPage.jsx - Shared UI · 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 · Wires middleware, routes, and database connectivity.
backend/server.js - Auth flow · Authentication controller and route boundary.
backend/controllers/auth.controller.js - Access control · Protected-route authorization and token handling.
backend/middleware/auth.middleware.js - Requests · Maintenance request lifecycle and asset-related handling.
backend/routes/request.routes.js - Payments · Cost entry, bills, and payment history endpoints.
backend/routes/payment.routes.js - Notifications · Notification controller and route handling.
backend/controllers/notification.controller.js - Users · User and admin-facing API surface.
backend/routes/user.routes.js - Auth utils · JWT, Google sign-in, mailer, and OTP email helpers.
backend/utils/jwt.js - DB layer · Shared database access module used by controllers and routes.
backend/db.js
MySQL data
Schema, seeds, triggers, and SQL maintenance scripts.
- Schema · Core tables and persistence structure.
database/schema.sql - Seed data · Starter rows and sample data.
database/seed.sql - Triggers · Database-level automation and derived billing behavior.
database/trigger.sql - SQL ops · Ad hoc query and reset scripts for operational database work.
database/queries.sql
Maintenance
Repair, migration, and verification helpers around the main stack.
- Migrations · Schema fixes, migration helpers, and constraint repair utilities.
backend/migrations.js - Schema tools · Utility scripts for schema checks and table setup.
backend/scripts/check_schema.js
Connections 28
- 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.