# CategoryDocumentsController

**Kind:** Controller

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

Category Documents Controller - Handles document ordering within categories

`CategoryDocumentsController` manages document ordering within categories in the API. It receives category-specific document update requests, delegates ordering logic to the document service layer, and returns the updated category document state.

## Diagram

```mermaid
graph LR
  Client[API Client] --> Controller[CategoryDocumentsController]
  Controller --> Service[Document Service]
  Service --> Database[(Database)]
  Database --> Service
  Service --> Controller
  Controller --> Client
```

## Usage

```ts
import axios from 'axios';

// Reorder documents within a category.
// Use the route and payload shape defined by CategoryDocumentsController.
async function reorderCategoryDocuments(
  categoryId: string,
  documentIds: string[],
) {
  const response = await axios.patch(
    `/categories/${categoryId}/documents/order`,
    { documentIds },
  );

  return response.data;
}

await reorderCategoryDocuments('category_123', [
  'document_3',
  'document_1',
  'document_2',
]);
```

## AI Coding Instructions

- Keep controller methods thin: validate request parameters and DTOs, then delegate ordering behavior to the appropriate service.
- Preserve document ownership and category membership validation before applying a new order.
- Update ordering atomically when multiple documents are reordered to avoid partial or duplicate positions.
- Follow existing NestJS patterns for decorators, guards, DTO validation, and API response handling in the surrounding API modules.
- Avoid accepting arbitrary document IDs without verifying that each document belongs to the requested category.

## Relationships

- MODULE_DECLARES → `reorderDocuments`
- DEPENDS_ON → `DocumentService`

## Referenced By

- `DocumentModule` (MODULE_DECLARES)