Neo4jDocsOrchestratorService

Kind: Service

Source: atloria-monorepo/apps/api/src/documentation/services/neo4j-docs-orchestrator.service.ts

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

  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)