How alfonsoconejo/kitab-api works
Purpose and runtime
Kitab is a Node.js/Express REST backend for managing a user’s academic periods, subjects, and classes. It persists data in PostgreSQL and uses JWT access tokens plus HttpOnly refresh-token cookies for authenticated sessions. The application entry point is src/app.js; database connectivity is centralized in src/config/db.js.
Application composition and routing
src/app.js assembles Express middleware, mounts API modules, and is the HTTP boundary for the service. Feature routers expose the public REST surface:
• Authentication: src/modules/auth/auth.routes.js
• Academic periods: src/modules/periods/periods.routes.js
• Subjects and class creation: src/modules/subjects/subjects.routes.js
• Class-specific endpoints: src/modules/classes/classes.routes.js
Controllers in each module translate HTTP requests into service calls and JSON responses, e.g. src/modules/auth/auth.controller.js and src/modules/periods/periods.controller.js.
Identity, sessions, and authorization
Authentication is layered around user credentials, signed JWTs, and server-managed refresh sessions:
• src/services/auth.service.js coordinates registration and login.
• src/services/token.service.js creates/verifies access and refresh tokens using src/config/jwt.config.js.
• src/services/session.service.js and src/services/refreshToken.service.js manage refresh-token/session lifecycle, including logout and logout-all behavior.
• src/middleware/auth.middleware.js protects routes by validating access tokens; src/middleware/user.middleware.js supplies authenticated-user context to downstream handlers.
Protected resource operations must derive ownership from this authenticated context rather than accepting user identity from request input.
Academic domain flow
The core ownership hierarchy is user → academic period → subject → class. Period endpoints create, query, update, and delete only the caller’s periods; they also provide period-scoped subject and class reads. The controlling layer is src/modules/periods/periods.controller.js, backed by src/services/period.service.js.
Subject operations create subjects inside a period, retrieve a subject with its classes, delete subjects, and create one or more classes under a subject. This crosses module boundaries through src/modules/subjects/subjects.controller.js, src/services/subject.service.js, and src/services/class.service.js. Class endpoints/controllers provide the remaining class-focused API surface at src/modules/classes/classes.controller.js.
Validation and request boundaries
Request payload validation is feature-specific and occurs before domain/service execution:
• src/validators/auth.validator.js
• src/validators/period.validator.js
• src/validators/subject.validator.js
• src/validators/class.validator.js
Controllers should remain transport-oriented: validate input, use authenticated identity and route parameters, invoke services, and map results/errors to JSON HTTP responses. Services form the database/business-rule boundary and should enforce resource ownership and relationship integrity.
Persistence and schema contract
PostgreSQL is the durable system of record, accessed through the shared connection/configuration in src/config/db.js. database_schema.md is the repository’s schema-level contract for users, sessions/tokens, and the academic hierarchy. Data-access logic is embedded in the domain services, including src/services/user.service.js, src/services/period.service.js, and src/services/subject.service.js.
Background lifecycle work
Scheduled or startup-registered cleanup is isolated from request handling in src/jobs/index.js and src/jobs/cleanup.job.js. This is the operational boundary for removing expired or stale session/refresh-token state and depends on the same PostgreSQL persistence layer.
Main entry points: periods.routes.js Academic routes · period.service.js Academic services · auth.validator.js Feature validators · db.js PostgreSQL
Components 17
HTTP API
- Express application · Assembles middleware and mounts API modules.
src/app.js - Auth routes
src/modules/auth/auth.routes.js - Academic routes · Periods, subjects, and class REST endpoints.
src/modules/periods/periods.routes.js - Auth controller
src/modules/auth/auth.controller.js - Feature validators · Validates auth, period, subject, and class payloads before services.
src/validators/auth.validator.js
Identity & sessions
- Access-token guard · Validates JWTs on protected routes.
src/middleware/auth.middleware.js - Authenticated user context · Supplies caller identity for ownership checks.
src/middleware/user.middleware.js - Authentication service · Coordinates registration and login.
src/services/auth.service.js - Token service · Creates and verifies access and refresh JWTs.
src/services/token.service.js - Session lifecycle services · Manage refresh sessions, logout, and logout-all.
src/services/session.service.js
Academic domain
- Period controller · Owns period-scoped reads for subjects and classes.
src/modules/periods/periods.controller.js - Subject controller · Creates subjects and classes within a subject.
src/modules/subjects/subjects.controller.js - Class controller
src/modules/classes/classes.controller.js - Academic services · Enforce ownership and period → subject → class integrity.
src/services/period.service.js
Persistence
- PostgreSQL · Stores users, sessions/tokens, and academic hierarchy.
src/config/db.js - Schema contract
database_schema.md
Lifecycle jobs
- Session cleanup jobs · Removes expired or stale session and refresh-token state.
src/jobs/index.js
Connections 23
- Express application → Auth routes: mounts
- Express application → Academic routes: mounts
- Express application → Access-token guard: uses
- Auth routes → Auth controller: dispatches
- Academic routes → Period controller: dispatches
- Academic routes → Subject controller: dispatches
- Academic routes → Class controller: dispatches
- Access-token guard → Token service: verifies access token
- Access-token guard → Authenticated user context: establishes identity
- Auth controller → Feature validators: validates payload
- Period controller → Feature validators: validates payload
- Subject controller → Feature validators: validates payload
- Class controller → Feature validators: validates payload
- Auth controller → Authentication service: invokes
- Authentication service → Token service: issues tokens
- Authentication service → Session lifecycle services: creates refresh session
- Period controller → Academic services: invokes
- Subject controller → Academic services: invokes
- Class controller → Academic services: invokes
- Session lifecycle services → PostgreSQL: persists sessions
- Academic services → PostgreSQL: reads and writes
- Schema contract → PostgreSQL: defines contract
- Session cleanup jobs → PostgreSQL: cleans stale state