Change Request

The Change Request subsystem manages project-scoped documentation change requests from opening through review, closure, diff refresh, conflict handling, and merge. ChangeRequestController accepts lifecycle actions, while ChangeRequestService records request state and proposed files. DiffService compares requests against the current main branch, and the queued CrWorker stages proposals on cr/<id> branches and performs gated merge writeback. DocsConfigService controls each project’s documentation review gate.

52 entities in atloria-monorepo/apps/api/src/change-request. 5 other subsystems depend on it, which makes it the 11th most depended-upon part of this codebase.

What it is made of

Its 52 entities sit in 13 files under atloria-monorepo/apps/api/src/change-request: 16 interfaces, 10 HTTP endpoints, 8 constants, 6 classes and 12 more. change-request.service.ts holds 11 of them — more than any other file here. ChangeRequestService declares 15 methods, the widest surface here.

Where work enters

2 controllers publish 10 HTTP endpoints — 6 POST, 3 GET and 1 PATCH. They answer under /projects. ChangeRequestController carries 8 of them; the remaining 2 are split across 1 other controller. Every one of them declares a guard — JwtAuthGuard on 10 and ProjectOrgGuard on 10.

• ChangeRequestController — atloria-monorepo/apps/api/src/change-request/change-request.controller.ts:21
• open — atloria-monorepo/apps/api/src/change-request/change-request.controller.ts:31
• list — atloria-monorepo/apps/api/src/change-request/change-request.controller.ts:51
• get — atloria-monorepo/apps/api/src/change-request/change-request.controller.ts:61
• close — atloria-monorepo/apps/api/src/change-request/change-request.controller.ts:70
• merge — atloria-monorepo/apps/api/src/change-request/change-request.controller.ts:81

How work moves through it

mermaid
flowchart LR
  ChangeRequestController0["ChangeRequestController"]
  ChangeRequestService10["ChangeRequestService"]
  ChangeRequestController0 --> ChangeRequestService10
  PreviewService11["PreviewService"]
  ChangeRequestController0 --> PreviewService11
  PrismaService20["PrismaService"]
  ChangeRequestService10 --> PrismaService20
  DocsCrQueue21["DocsCrQueue"]
  ChangeRequestService10 --> DocsCrQueue21
  stop["refused"]
  ChangeRequestService10 -. "BadRequestException" .-> stop

Work enters at ChangeRequestController and passes through 4 other components. Each step below is a dependency edge between two entities in this repository, followed outward in order.

1. ChangeRequestController takes the work first — atloria-monorepo/apps/api/src/change-request/change-request.controller.ts:21.
2. Next, ChangeRequestController calls ChangeRequestService and PreviewService.
3. Finally, ChangeRequestService calls PrismaService and DocsCrQueue.

Where the work stops

• ChangeRequestService stops the work with BadRequestException when row.status !== 'open', in 2 places.
• ChangeRequestService stops the work with BadRequestException when totalBytes >= MAX_PROPOSED_BYTES.
• PreviewService stops the work with Error when !s — “JWT_SECRET not configured — preview tokens cannot be signed”.
• PreviewService stops the work with NotFoundException when !src — “Preview not found”.

When a step fails

• ChangeRequestService handles failure in 3 places: it turns it into a return value in 2, and discards it silently in 1. A failure discarded silently leaves no trace for whoever debugs this later.
• PreviewService handles failure in 1 place: it turns it into a return value in all 1.
• PrismaService handles failure in 1 place: it lets it reach the caller in all 1.
• DocsCrQueue handles failure in 2 places: it logs it and continues in 1, and turns it into a return value in 1.

How it refuses and fails

5 of its components record a refusal or a failure handler. All 5 of them refuse work outright, under a condition written into the component itself. Their catch blocks handle a failure that already happened in 19 places. Of those 19, 8 let it reach the caller, 6 turn it into a return value, 3 log it and continue and 2 discard it without recording anything.

Boundaries

5 other subsystems depend on this one — Api, Docs Pr, Documentation, Git Sync, Project. Changing what it exposes changes them.

They hold 5 edges into it between them. 5 edges arrive and 5 leave. What they reach is narrower than the folder: 3 of its 52 members carry every inbound edge — PreviewService (2), ChangeRequestService (2) and ChangeRequestModule (1). Of the 5 it sends out, 3 go to Database — more than to any other.

It depends on Docs Repo, Database, and on nothing else in this repository.

How this code is named

These conventions cover most of the codebase. Learning them is faster than reading an index — each one lets you find any member of its family without looking it up.