01 — Architecture

Logical view

                   ┌────────────────────────────┐
                   │  Browser (SPA, React/Vite) │
                   │  property-management-main  │
                   └─────────────┬──────────────┘
                                 │  HTTPS  + JWT (Bearer)
                                 ▼
            ┌───────────────────────────────────────────┐
            │  Express API (property-management-api-main)│
            │  ─ Auth: express-jwt + custom verifyToken  │
            │  ─ Validation: Joi                         │
            │  ─ ORM-less: callback-style mysql driver   │
            │  ─ Logging: log4js (access / error / sql)  │
            │  ─ PDFs: pdf-lib + jsPDF                   │
            │  ─ Mail: nodemailer                        │
            └──────┬──────────┬─────────────┬───────────┘
                   │          │             │
                   ▼          ▼             ▼
            ┌──────────┐ ┌─────────┐ ┌────────────────┐
            │  MySQL   │ │  MinIO  │ │  AWS S3        │
            │  (RDS)   │ │  (file  │ │  (referral form │
            │  property│ │   blobs)│ │  uploads via   │
            │   *_dev  │ │         │ │   aws-sdk)     │
            │   _copy  │ │         │ │                │
            └──────────┘ └─────────┘ └────────────────┘

            ┌──────────────────────────────────┐
            │  Schedule process (separate PM2) │
            │  schedule/index.js (cron)         │
            │   ─ daily ranking (00:00)         │
            │   ─ loan notifications (every 6h) │
            └──────────────────────────────────┘

Runtime topology (PM2)

Defined in property-management-api-main/ecosystem.config.js:

Each apps[] entry calls one of:

• ./swagger.js — generates Swagger output then boots server.js (the API).
• ./schedule/index.js — boots only cron jobs.

The frontend is not behind PM2; it is a static SPA bundle deployed on Cloudflare (see deployment.md).

Process startup (API)

server.js:

1. Load env (process.env.TIMEZONE) and set moment-timezone global default.
2. Configure log4js (access / error / sql / schedule daily-rotated files in logs/node/).
3. Override console.log/console.error to write through log4js after running sanitizeAccessLogArgs (see app/utils/log-sanitizer.js).
4. Import and mount ~90 route files under /api/... — full list: backend.md § Routes.
5. Mount Swagger UI at /doc.
6. Mount express-jwt middleware globally after /api/login and a few public referral endpoints; everything else requires Bearer JWT.
7. Mount notFoundHandler then errorHandler last.
8. Listen on process.env.PORT.
9. Handle SIGTERM / SIGINT by closing both DB pools (general + transaction) — gracefulShutdown in server.js lines 268–294.

Request lifecycle

HTTP request
  → express.json / urlencoded
  → CORS (open: app.use(cors()) with no whitelist)
  → /doc → Swagger UI
  → /api/login* (public)
  → express-jwt parses Authorization: Bearer <token>
  → mounted route /api/<entity>
  → controller:
      ├─ Joi.validate(req.body)      ← validation
      ├─ decodeToken(req.headers.authorization)  ← user/role/agentId
      └─ Model.<op>(data, callback)  ← MySQL via app/models/db.js
            │ uses middleware/commonSqlUtil.js helpers
            │ (addCondition, addLikeCondition, addPageCondition,
            │  addCommonConditions=is_deleted filter, queryRecord, etc.)
            ▼
      callback(err, result)
        ├─ on err → next(err) → middleware/errorhandler.js
        │     converts MySQL/Joi/JWT errors → AppError → JSON
        └─ on success → res.send({ status: 200, message: 'success', data })

JWT details: security.md. DB layer details: backend.md § Database layer.

State storage

Observability

• Logs: log4js writes daily-rotated files (yyyy-MM-dd.log) for access, error, sql, schedule. Retention = 365 days. Console is also tee’d.
• SQL log: app/utils/sql-logger.js plus a connection.query patch in app/models/db.js log every query, mutation outcomes, and errors with duration.
• Swagger at /doc for the API (autogen output checked in as swagger-output.json).
• No Sentry / Datadog / New Relic integration in the code.

Key cross-cutting conventions

• Soft delete — every business table has is_deleted (0/1). All list queries pass through addCommonConditions (middleware/commonSqlUtil.js) which appends WHERE (table.is_deleted = 0 OR table.is_deleted IS NULL). Forgetting this on ad-hoc queries leaks deleted rows.
• Audit fields — create_account_id, created_date, last_modified_account_id, last_modified_date on every table. decodeToken(req.headers.authorization) is used to populate these in controllers.
• Number generation — generateNo(tableName, prefix, idColumn) produces document numbers like INV24070001 (prefix + YYMM + 5-digit running). Each entity has its own /generateXxxNo endpoint.
• Response envelope — { status: 200, message: 'success', data }. Errors: { status, message, error, details? } — see middleware/errorhandler.js.
• Multiple statements enabled in MySQL connection (multipleStatements: true) so several large INSERT INTO commission_* ... blocks can be issued at once. See commission-engine.md.

What is NOT in the architecture

• No queue / worker layer (BullMQ / SQS / RabbitMQ): cron is the only async path.
• No Redis / Memcached.
• No GraphQL / tRPC: REST only, hand-mounted in server.js.
• No ORM. Raw SQL via the callback driver, with the helpers in middleware/commonSqlUtil.js.
• No CI config in repo (no .github/workflows/* content delivered — there is a .github/ folder, see if dependabot etc. only).
• No automated tests.