# Neo4jDocsOrchestratorService

**Kind:** Service

**Source:** [`atloria-monorepo/apps/api/src/documentation/services/neo4j-docs-orchestrator.service.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/apps/api/src/documentation/services/neo4j-docs-orchestrator.service.ts#L17)

Orchestrates complete documentation generation from Neo4j knowledge graph data

This service handles the entire documentation workflow:
1. Query Neo4j for workflows, entities, and relationships
2. Generate all documentation types (Overview, Guides, Tutorials, Features)
3. Create category hierarchy (Doc Type → Business Module → Subcategory)
4. Save documents to database with proper ordering
5. Return complete documentation structure

`Neo4jDocsOrchestratorService` orchestrates end-to-end documentation generation by pulling workflows, entities, and relationships from a Neo4j knowledge graph and transforming them into structured docs. It generates multiple doc types (Overview, Guides, Tutorials, Features), builds a hierarchical category structure (Doc Type → Business Module → Subcategory), persists the ordered results to the database, and returns the final documentation tree for consumers.

## Methods

| Method | Signature | Returns | Description |
|---|---|---|---|
| `generateCompleteDocumentation` | `generateCompleteDocumentation(projectId: string, organizationId: string, userId: string, options: {
      types?: ('overview' | 'guides' | 'tutorials' | 'features')[];
      saveToDatabase?: boolean;
      createCategories?: boolean;
    })` | `Promise<GeneratedDocumentationResult>` | Generate complete documentation from Neo4j knowledge graph |

## Dependencies

- `PrismaService`
- `AzureClaudeProvider`
- `KnowledgeGraphService`
- `Neo4jService`

## When something fails

- `Neo4jDocsOrchestratorService` handles failure in 2 places: it turns it into a return value in 1, and lets it reach the caller in 1.

## Diagram

```mermaid
sequenceDiagram
  autonumber
  participant Caller
  participant Orchestrator as Neo4jDocsOrchestratorService
  participant Neo4j as Neo4j (Knowledge Graph)
  participant Generators as Doc Generators<br/>(Overview/Guides/Tutorials/Features)
  participant Categorizer as Category Hierarchy Builder
  participant DB as Database (Docs)

  Caller->>Orchestrator: generateDocumentation()
  Orchestrator->>Neo4j: queryWorkflowsEntitiesRelationships()
  Neo4j-->>Orchestrator: graphData (workflows/entities/relationships)
  Orchestrator->>Generators: generateAllDocTypes(graphData)
  Generators-->>Orchestrator: documents[]
  Orchestrator->>Categorizer: buildHierarchy(documents)
  Categorizer-->>Orchestrator: categorizedDocs (DocType→Module→Subcategory)
  Orchestrator->>DB: saveDocumentsWithOrdering(categorizedDocs)
  DB-->>Orchestrator: persistedStructure
  Orchestrator-->>Caller: documentationStructure
```

## Usage

```ts
import { Injectable } from '@nestjs/common';
import { Neo4jDocsOrchestratorService } from './documentation/services/neo4j-docs-orchestrator.service';

@Injectable()
export class DocsJobRunner {
  constructor(
    private readonly neo4jDocsOrchestrator: Neo4jDocsOrchestratorService,
  ) {}

  async run() {
    // Triggers the full workflow:
    // 1) Query Neo4j
    // 2) Generate Overview/Guides/Tutorials/Features
    // 3) Build category hierarchy
    // 4) Persist ordered docs
    // 5) Return final structure
    const result = await this.neo4jDocsOrchestrator.generateDocumentation();

    // Example: return to an API caller, enqueue follow-up jobs, etc.
    return {
      generatedAt: new Date().toISOString(),
      categories: result.categories,
      documentsCount: result.documents?.length ?? 0,
    };
  }
}
```

## AI Coding Instructions

- Treat this service as the orchestration layer: keep Neo4j querying, doc generation, categorization, and persistence as clearly separated steps (don’t mix responsibilities inside a single method).
- Preserve deterministic ordering when saving documents; ordering impacts navigation and downstream rendering—avoid non-stable sorts or relying on database default ordering.
- When extending doc types (e.g., adding a new generator), integrate it through the “generate all documentation types” step and ensure the category hierarchy logic understands the new type.
- Be defensive about Neo4j result shapes: validate required nodes/relationships before generating docs to prevent partial graphs from producing broken category trees.

## Relationships

- DEPENDS_ON → `PrismaService`
- DEPENDS_ON → `AzureClaudeProvider`
- DEPENDS_ON → `knowledgegraphservice`
- DEPENDS_ON → `Neo4jService`

## Referenced By

- `DocumentationController` (DEPENDS_ON)
- `DocumentationModule` (MODULE_PROVIDES)