# DocsPrController

**Kind:** Controller

**Source:** [`atloria-monorepo/apps/api/src/docs-pr/docs-pr.controller.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/apps/api/src/docs-pr/docs-pr.controller.ts#L24)

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)