# TocBuilderService

**Kind:** Service

**Source:** [`atloria-monorepo/apps/api/src/document/services/toc-builder.service.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/apps/api/src/document/services/toc-builder.service.ts#L10)

`TocBuilderService` is a NestJS service responsible for building a structured table of contents for document content. Its `extractToc()` method returns `TocEntry` objects that can be used by document APIs, renderers, or navigation components to present document headings hierarchically.

## Methods

| Method | Signature | Returns | Description |
|---|---|---|---|
| `extractToc` | `extractToc(content: string)` | `TocEntry[]` | Extract table of contents from markdown content |

## Diagram

```mermaid
sequenceDiagram
    participant Consumer as Document Controller/Service
    participant TocBuilder as TocBuilderService
    participant Entries as TocEntry[]

    Consumer->>TocBuilder: extractToc()
    TocBuilder->>TocBuilder: Analyze document heading structure
    TocBuilder->>Entries: Build ordered TOC entries
    Entries-->>TocBuilder: TocEntry[]
    TocBuilder-->>Consumer: TocEntry[]
```

## Usage

```ts
import { Injectable } from '@nestjs/common';
import { TocBuilderService } from './toc-builder.service';
import type { TocEntry } from '../types/toc-entry.type';

@Injectable()
export class DocumentNavigationService {
  constructor(private readonly tocBuilderService: TocBuilderService) {}

  getTableOfContents(): TocEntry[] {
    return this.tocBuilderService.extractToc();
  }
}
```

## AI Coding Instructions

- Inject `TocBuilderService` through NestJS dependency injection rather than creating it manually.
- Treat the result of `extractToc()` as ordered navigation data; preserve its entry order when returning or rendering it.
- Keep heading parsing and TOC construction logic centralized in this service instead of duplicating it in controllers or UI-facing services.
- Update the `TocEntry` contract and all consumers together if TOC fields, nesting behavior, or anchor-generation rules change.

## Referenced By

- `DocumentModule` (MODULE_PROVIDES)
- `DocumentModule` (MODULE_EXPORTS)
- `DocumentService` (DEPENDS_ON)
- `ProjectService` (DEPENDS_ON)