Technical Docs

Technical Docs manages technical-documentation freshness, identifying published pages made stale by project code changes and supporting screenshot re-shoots through FreshnessController and DocsTrueupService. It also runs grounded codebase chat through TechDocsChatService, including session memory, SSE answer streaming, feedback, and human escalation, with embeddings and a configured RAG chat model required for AI-backed responses.

134 entities in atloria-monorepo/apps/api/src/technical-docs. 5 other subsystems depend on it, which makes it the 10th most depended-upon part of this codebase.

What it is made of

Its 134 entities sit in 36 files under atloria-monorepo/apps/api/src/technical-docs: 47 HTTP endpoints, 33 interfaces, 26 functions, 20 services and 8 more. technical-docs.controller.ts holds 30 of them — more than any other file here. TechnicalDocsMaterializerService is what the rest of it leans on: 6 of its own members depend on it, more than on anything else inside the boundary. TechnicalDocsService declares 20 methods, the widest surface here.

Where work enters

4 controllers publish 47 HTTP endpoints — 23 POST, 16 GET, 6 PUT and 2 DELETE. They answer under /freshness and /technical-docs. TechnicalDocsController carries 29 of them; the remaining 18 are split across 3 other controllers. Every one of them declares a guard — JwtAuthGuard on 31 and OptionalJwtAuthGuard on 16.

• FreshnessController — atloria-monorepo/apps/api/src/technical-docs/freshness.controller.ts:14
• stale — atloria-monorepo/apps/api/src/technical-docs/freshness.controller.ts:19
• reshoot — atloria-monorepo/apps/api/src/technical-docs/freshness.controller.ts:27
• TechnicalDocsChatController — atloria-monorepo/apps/api/src/technical-docs/technical-docs-chat.controller.ts:19
• createSession — atloria-monorepo/apps/api/src/technical-docs/technical-docs-chat.controller.ts:48
• stream — atloria-monorepo/apps/api/src/technical-docs/technical-docs-chat.controller.ts:65

How work moves through it

mermaid
flowchart LR
  FreshnessController0["FreshnessController"]
  FreshnessService10["FreshnessService"]
  FreshnessController0 --> FreshnessService10
  PrismaService20["PrismaService"]
  FreshnessService10 --> PrismaService20
  DocAutomationService21["DocAutomationService"]
  FreshnessService10 --> DocAutomationService21
  DocAutomationGateway30["DocAutomationGateway"]
  DocAutomationService21 --> DocAutomationGateway30
  UrlService31["UrlService"]
  DocAutomationService21 --> UrlService31
  AssetsService32["AssetsService"]
  DocAutomationService21 --> AssetsService32
  DocumentIndexingService33["DocumentIndexingService"]
  DocAutomationService21 --> DocumentIndexingService33
  more2["+13 more"]
  DocAutomationService21 --> more2
  AzureSearchService40["AzureSearchService"]
  DocumentIndexingService33 --> AzureSearchService40
  KeywordExtractorService41["KeywordExtractorService"]
  DocumentIndexingService33 --> KeywordExtractorService41
  SnippetsService42["SnippetsService"]
  DocumentIndexingService33 --> SnippetsService42
  AzureBlobService43["AzureBlobService"]
  DocumentIndexingService33 --> AzureBlobService43
  more3["+8 more"]
  DocumentIndexingService33 --> more3
  stop["refused"]
  FreshnessService10 -. "ForbiddenException" .-> stop

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

1. FreshnessController takes the work first — atloria-monorepo/apps/api/src/technical-docs/freshness.controller.ts:14.
2. Next, FreshnessController hands off to FreshnessService — atloria-monorepo/apps/api/src/technical-docs/freshness.service.ts:65.
3. Then, FreshnessService calls PrismaService and DocAutomationService.
4. Then, DocAutomationService calls DocAutomationGateway, UrlService, AssetsService and DocumentIndexingService, along with 13 more.
5. Finally, DocumentIndexingService calls AzureSearchService, KeywordExtractorService, SnippetsService and AzureBlobService, along with 8 more.

Where the work stops

• FreshnessService stops the work with ForbiddenException when !project — “Project not found in your organization.”.
• DocAutomationService stops the work with NotFoundException when !job — “Documentation job not found”, in 9 places.
• DocAutomationService stops the work with ForbiddenException when job.organizationId !== user.organizationId && !this.isServiceAccount(user) — “You do not have access to this job”, in 4 places.
• AssetsService stops the work with BadRequestException when !asset — “Asset not found”, in 2 places.
• AssetsService stops the work with BadRequestException when !allowedMimeTypes.includes(file.mimetype) — “Invalid file type. Only JPEG, PNG, GIF, and WebP images are allowed.”.

When a step fails

• PrismaService handles failure in 1 place: it lets it reach the caller in all 1.
• DocAutomationService handles failure in 48 places: it logs it and continues in 32, discards it silently in 11, lets it reach the caller in 3, and turns it into a return value in 2. A failure discarded silently leaves no trace for whoever debugs this later.
• DocumentIndexingService handles failure in 14 places: it logs it and continues in 10, turns it into a return value in 2, lets it reach the caller in 1, and discards it silently in 1. A failure discarded silently leaves no trace for whoever debugs this later.
• AzureSearchService handles failure in 10 places: it lets it reach the caller in 9, and turns it into a return value in 1.

How it refuses and fails

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

Boundaries

5 other subsystems depend on this one — Api, Manuals Insights, Project, Trial, Webhooks. Changing what it exposes changes them.

Those 5 hold 13 edges between them, unevenly: Project reaches in across 6 edges, while 2 of them hold one each. 60 edges leave it against 13 arriving — it reads more of this repository than this repository reads of it. What they reach is narrower than the folder: 6 of its 134 members carry every inbound edge — TechDocsRagService (4), TechnicalDocsModule (3) and TechnicalDocsService (3), plus 3 more. Of the 60 it sends out, 19 go to Database — more than to any other.

It depends on Database, Doc Version, Documentation, Events, Issues, Graph, Reader Access, Email, Ai, Notification, L10n, Snippets, Changelog, Document, Parsing, Auth, Sdk, 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.