# alfonsoconejo/kitab-api architecture

> Architecture diagram of the GitHub repository alfonsoconejo/kitab-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alfonsoconejo/kitab-api
- Repository: https://github.com/alfonsoconejo/kitab-api

## Overview

#### 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: [`src/modules/periods/periods.routes.js`](https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/periods/periods.routes.js) (Academic routes), [`src/services/period.service.js`](https://github.com/alfonsoconejo/kitab-api/blob/main/src/services/period.service.js) (Academic services), [`src/validators/auth.validator.js`](https://github.com/alfonsoconejo/kitab-api/blob/main/src/validators/auth.validator.js) (Feature validators), [`src/config/db.js`](https://github.com/alfonsoconejo/kitab-api/blob/main/src/config/db.js) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_app["Express application<br/>HTTP entry point<br/>[app.js]"]
  node_auth_routes["Auth routes<br/>router<br/>[auth.routes.js]"]
  node_academic_routes["Academic routes<br/>feature routers<br/>[periods.routes.js]"]
  node_auth_controller["Auth controller<br/>[auth.controller.js]"]
  node_request_validation["Feature validators<br/>request validation<br/>[auth.validator.js]"]
end

subgraph group_identity["Identity &amp; sessions"]
  node_auth_middleware["Access-token guard<br/>middleware<br/>[auth.middleware.js]"]
  node_user_context["Authenticated user context<br/>middleware<br/>[user.middleware.js]"]
  node_auth_service["Authentication service<br/>[auth.service.js]"]
  node_token_service["Token service<br/>[token.service.js]"]
  node_session_services["Session lifecycle services<br/>[session.service.js]"]
end

subgraph group_academic["Academic domain"]
  node_period_controller["Period controller"]
  node_subject_controller["Subject controller"]
  node_class_controller["Class controller"]
  node_academic_services["Academic services<br/>[period.service.js]"]
end

subgraph group_data["Persistence"]
  node_postgres[("PostgreSQL<br/>system of record<br/>[db.js]")]
  node_schema_contract["Schema contract<br/>database schema<br/>[database_schema.md]"]
end

subgraph group_ops["Lifecycle jobs"]
  node_cleanup_jobs["Session cleanup jobs<br/>background jobs<br/>[index.js]"]
end

node_app -->|"mounts"| node_auth_routes
node_app -->|"mounts"| node_academic_routes
node_app -->|"uses"| node_auth_middleware
node_auth_routes -->|"dispatches"| node_auth_controller
node_academic_routes -->|"dispatches"| node_period_controller
node_academic_routes -->|"dispatches"| node_subject_controller
node_academic_routes -->|"dispatches"| node_class_controller
node_auth_middleware -->|"verifies access token"| node_token_service
node_auth_middleware -->|"establishes identity"| node_user_context
node_auth_controller -->|"validates payload"| node_request_validation
node_period_controller -->|"validates payload"| node_request_validation
node_subject_controller -->|"validates payload"| node_request_validation
node_class_controller -->|"validates payload"| node_request_validation
node_auth_controller -->|"invokes"| node_auth_service
node_auth_service -->|"issues tokens"| node_token_service
node_auth_service -->|"creates refresh session"| node_session_services
node_period_controller -->|"invokes"| node_academic_services
node_subject_controller -->|"invokes"| node_academic_services
node_class_controller -->|"invokes"| node_academic_services
node_session_services -->|"persists sessions"| node_postgres
node_academic_services -->|"reads and writes"| node_postgres
node_schema_contract -.->|"defines contract"| node_postgres
node_cleanup_jobs -->|"cleans stale state"| node_postgres

click node_app "https://github.com/alfonsoconejo/kitab-api/blob/main/src/app.js"
click node_auth_routes "https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/auth/auth.routes.js"
click node_academic_routes "https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/periods/periods.routes.js"
click node_auth_controller "https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/auth/auth.controller.js"
click node_period_controller "https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/periods/periods.controller.js"
click node_subject_controller "https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/subjects/subjects.controller.js"
click node_class_controller "https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/classes/classes.controller.js"
click node_request_validation "https://github.com/alfonsoconejo/kitab-api/blob/main/src/validators/auth.validator.js"
click node_auth_middleware "https://github.com/alfonsoconejo/kitab-api/blob/main/src/middleware/auth.middleware.js"
click node_user_context "https://github.com/alfonsoconejo/kitab-api/blob/main/src/middleware/user.middleware.js"
click node_auth_service "https://github.com/alfonsoconejo/kitab-api/blob/main/src/services/auth.service.js"
click node_token_service "https://github.com/alfonsoconejo/kitab-api/blob/main/src/services/token.service.js"
click node_session_services "https://github.com/alfonsoconejo/kitab-api/blob/main/src/services/session.service.js"
click node_academic_services "https://github.com/alfonsoconejo/kitab-api/blob/main/src/services/period.service.js"
click node_postgres "https://github.com/alfonsoconejo/kitab-api/blob/main/src/config/db.js"
click node_schema_contract "https://github.com/alfonsoconejo/kitab-api/blob/main/database_schema.md"
click node_cleanup_jobs "https://github.com/alfonsoconejo/kitab-api/blob/main/src/jobs/index.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_app,node_auth_routes,node_academic_routes,node_auth_controller,node_request_validation toneBlue
class node_auth_middleware,node_user_context,node_auth_service,node_token_service,node_session_services toneAmber
class node_period_controller,node_subject_controller,node_class_controller,node_academic_services toneMint
class node_postgres,node_schema_contract toneRose
class node_cleanup_jobs toneIndigo
```

## Components

### HTTP API

- [Express application](https://github.com/alfonsoconejo/kitab-api/blob/main/src/app.js): HTTP entry point · Assembles middleware and mounts API modules. · `src/app.js`
- [Auth routes](https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/auth/auth.routes.js): router · `src/modules/auth/auth.routes.js`
- [Academic routes](https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/periods/periods.routes.js): feature routers · Periods, subjects, and class REST endpoints. · `src/modules/periods/periods.routes.js`
- [Auth controller](https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/auth/auth.controller.js): controller · `src/modules/auth/auth.controller.js`
- [Feature validators](https://github.com/alfonsoconejo/kitab-api/blob/main/src/validators/auth.validator.js): request validation · Validates auth, period, subject, and class payloads before services. · `src/validators/auth.validator.js`

### Identity & sessions

- [Access-token guard](https://github.com/alfonsoconejo/kitab-api/blob/main/src/middleware/auth.middleware.js): middleware · Validates JWTs on protected routes. · `src/middleware/auth.middleware.js`
- [Authenticated user context](https://github.com/alfonsoconejo/kitab-api/blob/main/src/middleware/user.middleware.js): middleware · Supplies caller identity for ownership checks. · `src/middleware/user.middleware.js`
- [Authentication service](https://github.com/alfonsoconejo/kitab-api/blob/main/src/services/auth.service.js): service · Coordinates registration and login. · `src/services/auth.service.js`
- [Token service](https://github.com/alfonsoconejo/kitab-api/blob/main/src/services/token.service.js): service · Creates and verifies access and refresh JWTs. · `src/services/token.service.js`
- [Session lifecycle services](https://github.com/alfonsoconejo/kitab-api/blob/main/src/services/session.service.js): services · Manage refresh sessions, logout, and logout-all. · `src/services/session.service.js`

### Academic domain

- [Period controller](https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/periods/periods.controller.js): controller · Owns period-scoped reads for subjects and classes. · `src/modules/periods/periods.controller.js`
- [Subject controller](https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/subjects/subjects.controller.js): controller · Creates subjects and classes within a subject. · `src/modules/subjects/subjects.controller.js`
- [Class controller](https://github.com/alfonsoconejo/kitab-api/blob/main/src/modules/classes/classes.controller.js): controller · `src/modules/classes/classes.controller.js`
- [Academic services](https://github.com/alfonsoconejo/kitab-api/blob/main/src/services/period.service.js): services · Enforce ownership and period → subject → class integrity. · `src/services/period.service.js`

### Persistence

- [PostgreSQL](https://github.com/alfonsoconejo/kitab-api/blob/main/src/config/db.js): system of record · Stores users, sessions/tokens, and academic hierarchy. · `src/config/db.js`
- [Schema contract](https://github.com/alfonsoconejo/kitab-api/blob/main/database_schema.md): database schema · `database_schema.md`

### Lifecycle jobs

- [Session cleanup jobs](https://github.com/alfonsoconejo/kitab-api/blob/main/src/jobs/index.js): background jobs · Removes expired or stale session and refresh-token state. · `src/jobs/index.js`

## Connections

- 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