Ai

The Ai subsystem manages AI-assisted document and codebase analysis workflows through AIController and AIService, including document enhancement, outline generation, writing improvement, summarization, provider listing, and paginated organization usage logs. It also turns frontend code and related files into UI, code, and Playwright-test documentation through FileContextService, UIAnalyzerService, CodeAnalysisService, and PlaywrightGeneratorService, while parsing uploaded business-context files into structured summaries.

231 entities in atloria-monorepo/apps/api/src/ai. 10 other subsystems depend on it, which makes it the 3rd most depended-upon part of this codebase.

What it is made of

Its 231 entities sit in 23 files under atloria-monorepo/apps/api/src/ai: 187 doc comments, 14 interfaces, 8 services, 7 classes and 15 more. ai.controller.ts holds 7 of them — more than any other file here. AIService is what the rest of it leans on: 4 of its own members depend on it, more than on anything else inside the boundary. FileContextService declares 9 methods, the widest surface here.

Where work enters

1 controller publishes 6 HTTP endpoints — 4 POST and 2 GET. They answer under /ai. Every one of them declares a guard — JwtAuthGuard on 6 and RateLimitGuard on 6.

• AIController — atloria-monorepo/apps/api/src/ai/ai.controller.ts:29
• usageLogs — atloria-monorepo/apps/api/src/ai/ai.controller.ts:39
• enhance — atloria-monorepo/apps/api/src/ai/ai.controller.ts:77
• generateOutline — atloria-monorepo/apps/api/src/ai/ai.controller.ts:101
• improve — atloria-monorepo/apps/api/src/ai/ai.controller.ts:125
• summarize — atloria-monorepo/apps/api/src/ai/ai.controller.ts:149

How work moves through it

mermaid
flowchart LR
  AIController0["AIController"]
  AIService10["AIService"]
  AIController0 --> AIService10
  AIUsageService11["AIUsageService"]
  AIController0 --> AIUsageService11
  PrismaService20["PrismaService"]
  AIService10 --> PrismaService20
  AzureClaudeProvider21["AzureClaudeProvider"]
  AIService10 --> AzureClaudeProvider21
  AzureOpenAIProvider22["AzureOpenAIProvider"]
  AIService10 --> AzureOpenAIProvider22
  stop["refused"]
  AIService10 -. "NotFoundException" .-> stop

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

1. AIController takes the work first — atloria-monorepo/apps/api/src/ai/ai.controller.ts:29.
2. Next, AIController calls AIService and AIUsageService.
3. Finally, AIService calls PrismaService, AzureClaudeProvider and AzureOpenAIProvider.

Where the work stops

• AIService stops the work with NotFoundException when !document — “Document not found”, in 2 places.
• AIService stops the work with NotFoundException when !provider.
• AIUsageService stops the work with BadRequestException when !Number.isFinite(amount) || amount <= 0 — “Credit deduction amount must be a positive number”.
• AIUsageService stops the work with PaymentRequiredException when result.count === 0.
• AzureClaudeProvider stops the work with Error when !projectEndpoint — “Azure AI Project configuration missing. Please set AZURE_EXISTING_AIPROJECT_ENDPOINT”.

When a step fails

• AIUsageService handles failure in 1 place: it logs it and continues in all 1.
• PrismaService handles failure in 1 place: it lets it reach the caller in all 1.
• AzureClaudeProvider handles failure in 5 places: it turns it into a return value in 2, lets it reach the caller in 2, and logs it and continues in 1.
• AzureOpenAIProvider handles failure in 4 places: it lets it reach the caller in 2, logs it and continues in 1, and turns it into a return value in 1.

How it refuses and fails

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

Boundaries

10 other subsystems depend on this one — Api, Billing, Changelog, Documentation, Graph, L10n, Project, Support Agent, Technical Docs, Workflow. Changing what it exposes changes them.

Those 10 hold 33 edges between them, unevenly: Documentation reaches in across 12 edges, while 3 of them hold one each. 33 edges arrive against 5 leaving — more of this repository reaches into it than it reaches out to. What they reach is narrower than the folder: 6 of its 231 members carry every inbound edge — AIModule (10), AIUsageService (9) and AzureClaudeProvider (8), plus 3 more. Of the 5 it sends out, 4 go to Database — more than to any other.

It depends on Database, Auth, 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.