40227-vm/backend/docs/backend-architecture.md

Backend Architecture

The backend uses a three-layer architecture, mirroring the frontend (frontend/docs/frontend-architecture.md):

• API layer (HTTP)
• Business logic layer (BLL)
• Data access layer (DAL)

The goal is to keep routes thin, keep business rules testable and free of HTTP, and keep all persistence in one place.

Layer 1: API

Location:

• src/routes/ — thin route wiring: path → middleware → wrapAsync(controller).
• src/api/controllers/ — one <feature>.controller.ts per feature; exported async handler functions (req, res) => ….
• src/api/http/ — request helpers (wrapAsync, queryStr, queryNum, paramStr).
• src/middlewares/ — authenticate (passport), checkPermissions, csrf-origin, error-handler, upload.

Responsibilities:

• Parse and validate the HTTP request (query, params, body, cookies, uploads).
• Run middleware (auth, permissions, CSRF).
• Call exactly one BLL service and shape the HTTP response (status + body).
• Own multipart/upload parsing; pass parsed data (e.g. a file buffer) to the BLL.

The API layer must not:

• Import the DAL (@/db/api/*, @/db/models/*) — it goes through a service.
• Contain tenant/role/permission/workflow rules or DTO mapping.
• Run database queries.

Authentication and public routes

Every /api route is JWT-authenticated at the mount (authenticated = passport.authenticate('jwt', { session: false })) except the intentionally public surface:

• the /api/auth/* public endpoints (sign-in / refresh / sign-out, password reset, email verification, OAuth — the authenticated sub-routes such as /me apply passport per route);
• GET /api/public/campuses;
• GET /api/public/content-catalog/:contentType.

No tenant-owned mutable data is exposed publicly. Authorization is then by permission: generic-CRUD routers apply checkCrudPermissions(entity) (${METHOD}_${ENTITY}); the feature routes apply checkPermissions(<PRODUCT_FEATURE>) for page reads and the special actions (READ_FRAME, READ_WALKTHROUGH, READ_ATTENDANCE, READ_PARENT_COMM, READ_INTERNAL_COMM, FILL_ATTENDANCE, TAKE_QUIZ — names from shared/constants/product-permissions.ts, so custom_permissions can extend access), while the manager-only writes (FRAME/walkthrough/communications/content-catalog editing and the staff/attendance reports) stay gated in their services by role until a dedicated MANAGE_* permission exists. The users / staff / organizations write paths add the §3.3 relational policy. Both POST /api/file/upload and GET /api/file/download require JWT, the local file handlers reject path traversal, and download enforces a per-file tenant/ownership check (the file's owning organization must match the requester's unless they have global access; see file.md).

Layer 2: Business Logic (BLL)

Location:

• src/services/ — one <feature>.ts (class with static methods) per feature, plus per-feature mappers/validators/helpers as needed. Infra BLL lives in src/services/email/.

Responsibilities:

• Own workflows, transactions, and coordination across repositories.
• Apply tenant, role, campus, and permission rules.
• Map DB records to response DTOs; validate and normalize inputs.
• Accept typed inputs and return typed values/DTOs.

The BLL must not:

• Touch Express req/res or import express/middleware. (Two legacy exceptions remain — services/file.ts streaming and services/auth.ts session IP/UA + cookies — tracked by the boundary test and to be revisited.)
• Import the API layer.
• Render HTTP responses.

Layer 3: Data Access (DAL)

Location:

• src/db/api/ — one *DBApi class per entity (the repository layer).
• src/db/models/ — Sequelize models.
• src/db/migrations/, src/db/seeders/, src/db/utils.ts, db.config.ts.
• src/db/api/types.ts — DB-entity contract types (AuthenticatedUser, CurrentUser, DbApiOptions, …); DAL-coupled, so it stays in db/.

Responsibilities:

• Own all Sequelize queries and schema.
• Return records/plain data to the BLL.

The DAL must not:

• Import the API layer or the BLL. (One legacy exception: db/api/file.ts imports services/file for GCloud blob deletion — tracked, to be inverted.)
• Apply business rules or touch HTTP.

Cross-cutting

Location: src/shared/ (+ ambient types in src/types/).

• shared/constants/ — all constants/config values (was src/constants).
• shared/config/ — env-driven runtime config (index.ts + load-env.ts).
• shared/errors/ — AppError and subclasses.
• shared/notifications/ — i18n message catalog + helpers.
• shared/logger.ts, shared/csv.ts, shared/jwt.ts.
• shared/architecture/ — the import-boundary test.

Cross-cutting code depends on no layer and may be imported by any layer.

Import direction

Allowed:

Route → Controller → Service (BLL) → Repository/Model (DAL) → DB

shared/* may be imported by any layer. Disallowed:

API (routes/controllers) → DAL          (skip the BLL)
BLL (services)           → Express / API
DAL (db)                 → BLL / API
shared/*                 → any layer

Feature structure

Layer-first directories, one file per feature inside each layer (only create what a feature needs):

src/routes/<feature>.ts
src/api/controllers/<feature>.controller.ts
src/services/<feature>.ts            (+ mappers/validators when needed)
src/db/api/<feature>.ts              (repository)
src/db/models/<feature>.ts
src/shared/constants/<feature>.ts

Module authoring (shared factories & helpers)

Most modules are assembled from shared factories/helpers — keep them that way.

• Generic CRUD entity = three one-line config files:

  • src/services/<e>.ts → export default createCrudService(EntityDBApi, { notFoundCode });
  • src/api/controllers/<e>.controller.ts → export default createCrudController(service, { csvFields });
  • src/routes/<e>.ts → export default createCrudRouter(controller, { permission });

  Factories: services/shared/crud-service.ts, api/controllers/shared/crud-controller.ts, api/http/crud-router.ts (generic over the repository's entity types — no casts). 18 of 21 entities use them; entities with genuinely different behavior (users invitations, permissions no-globalAccess queries) stay hand-written.

• Repository (DAL) = entity-specific create/update/bulkImport/findBy/ findAll; the identical remove/deleteByIds/findAllAutocomplete delegate to db/api/shared/repository.ts (removeRecord, deleteRecordsByIds, autocompleteByField).

• Feature service (BLL) = reuse shared helpers: tenant/role access in services/shared/access.ts (getOrganizationId, getOrganizationIdOrGlobal, hasGlobalAccess, requireUserId, hasRoleAccess(user, roleNames), campusScope(user, tenantWideRoleNames), assertAuthenticatedTenantUser, …); validation in services/shared/validate.ts (clampLimit, nullableString, requiredIsoDate/optionalIsoDate); transactions via db/with-transaction.ts (withTransaction(fn)); CSV import via services/shared/csv-import.ts; isRecord from shared/object.ts.

  • getOrganizationIdOrGlobal(user): returns null for global access users (bypassing org filter) or the user's org ID; throws ForbiddenError if neither.
  • hasGlobalAccess(user): returns true when app_role.globalAccess === true.
  • assertAuthenticatedTenantUser(user): allows global access users even without an organization (useful for platform-level admins).

Error handling

Centralized — see backend/docs/error-handling.md. Handlers/services throw an AppError subclass; the terminal error-handler middleware turns it into the { message, code?, details? } JSON body the frontend ApiError consumes.

Global error handlers

The server registers process-level handlers in src/index.ts to prevent crashes from unhandled errors:

• process.on('uncaughtException') — catches synchronous errors
• process.on('unhandledRejection') — catches unhandled promise rejections

These log the error and allow the server to continue running. This protects against crashes from misconfigured external services (e.g., SMTP without credentials) or unexpected async failures.

Production credential guards

Development defaults (DB credentials, SECRET_KEY) are hardcoded in shared/constants/app.ts for local development convenience. However, these defaults are never applied in production-like environments:

• shared/config/index.ts: requiredEnvWithDevDefault() throws if SECRET_KEY is missing when NODE_ENV is production or dev_stage.
• db/models/index.ts: validateProductionDbConfig() throws if any DB_* credential is missing in production-like environments.

This ensures the server fails fast with a clear error message rather than silently using insecure defaults.

Enforcement & verification

• src/shared/architecture/import-boundaries.test.ts enforces the import direction. Hard invariants assert zero violations; the two remaining HTTP-in-BLL edge cases and the one DAL→BLL leak are capped by ceilings that must not grow.
• ESLint no-restricted-imports blocks (in eslint.config.ts) forbid the already-clean invariants at lint time (API→DAL, model/DAL/shared purity).
• npm run typecheck, npm run lint, npm test are the verification gates; npm test runs the Node test runner via tsx (error-handler + boundary tests).

Known remaining items

• services/file.ts and services/auth.ts still depend on req/res (file streaming; session IP/UA + cookies). To be revisited with the upload subsystem.
• db/api/file.ts → services/file (GCloud delete) is a DAL→BLL leak to invert (the BLL should orchestrate blob + row deletion).
• src/index.ts remains the composition root + entry; an app/server.ts split is optional and deferred (deploy runs dist/index.js).
• Repositories still hand-roll the findAll filter→where building per entity; a declarative where-builder could dedup it, deferred until the data platform stabilizes (higher-risk Sequelize typing).