DocsPrController

Kind: Controller

Source: atloria-monorepo/apps/api/src/docs-pr/docs-pr.controller.ts

Owner surface for Freshness-as-PRs. Every route is membership-scoped to the project. Nothing here runs unless the owner has explicitly enabled the feature.

DocsPrController exposes the owner-facing API for creating and managing Freshness-as-PR workflows within a project. It enforces project membership scoping and delegates business logic to the Docs PR service layer. Requests are only actionable when the project owner has explicitly enabled the Freshness-as-PRs feature.

Diagram

mermaid
graph LR
  Owner[Project owner or member] --> Controller[DocsPrController]
  Controller --> Membership[Project membership validation]
  Controller --> FeatureFlag[Freshness-as-PRs enabled check]
  Controller --> Service[Docs PR service]
  Service --> Docs[Documentation freshness data]
  Service --> PR[Generated pull request workflow]

Usage

ts
// Example API client usage for a membership-scoped Docs PR endpoint.
async function createDocsFreshnessPr(
  projectId: string,
  documentId: string,
  accessToken: string,
) {
  const response = await fetch(
    `${process.env.API_URL}/projects/${projectId}/docs-prs`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        documentId,
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`Unable to create Docs PR: ${response.statusText}`);
  }

  return response.json();
}

AI Coding Instructions

• Keep every route project-scoped and validate that the authenticated user belongs to the target project before accessing Docs PR data.
• Preserve the explicit Freshness-as-PRs enablement check; do not allow background creation or mutation when the owner has not enabled the feature.
• Keep controller methods thin: parse request inputs, apply guards/validation, and delegate workflow behavior to the Docs PR service.
• Return authorization and feature-state failures consistently so clients can distinguish missing membership from a disabled feature.
• When adding endpoints, ensure they operate only on project-owned documents and cannot accept cross-project document identifiers.

Relationships

• MODULE_DECLARES → getConfig
• MODULE_DECLARES → setConfig
• MODULE_DECLARES → listPrs
• MODULE_DECLARES → run
• DEPENDS_ON → PrismaService
• DEPENDS_ON → DocsPrService

Referenced By

• DocsPrModule (MODULE_DECLARES)