# OrchestratorService

**Kind:** Service

**Source:** [`atloria-monorepo/apps/parser-orchestrator/src/orchestrator/orchestrator.service.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/apps/parser-orchestrator/src/orchestrator/orchestrator.service.ts#L43)

`OrchestratorService` coordinates project parsing jobs in the parser orchestrator backend. It selects an appropriate parser, dispatches work to the queue, exposes job status and results, and provides operational visibility through queue and knowledge-graph metrics.

## Methods

| Method | Signature | Returns | Description |
|---|---|---|---|
| `dispatchParseJob` | `dispatchParseJob(options: {
    projectId: string;
    files: string[];
    parserType: string;
    config?: Record<string, unknown>;
    priority?: number;
  })` | `Promise<string>` | Dispatch a single parse job to the queue |
| `parseProject` | `parseProject(config: ParseProjectConfig)` | `Promise<ProjectParseResult>` | Parse an entire project |
| `getJobStatus` | `getJobStatus(jobId: string)` | `Promise<JobStatus | null>` | Get job status |
| `getResult` | `getResult(jobId: string)` | `Promise<ParseResult[] | null>` | Get job result |
| `cancelJob` | `cancelJob(jobId: string)` | `Promise<boolean>` | Cancel a parse job |
| `getQueueMetrics` | `getQueueMetrics()` | `unknown` | Get queue metrics |
| `getKGStatistics` | `getKGStatistics()` | `unknown` | Get Knowledge Graph statistics |
| `determineParser` | `determineParser(filePath: string)` | `string | null` | Determine which parser to use for a file |
| `getAvailableParsers` | `getAvailableParsers()` | `string[]` | Get list of available parsers |
| `getParserPatterns` | `getParserPatterns(parser: string)` | `string[] | null` | Get parser patterns |

## Dependencies

- `ConfigService`
- `QueueService`
- `KnowledgeGraphService`
- `KGSyncService`

## Where it refuses work

- `OrchestratorService` stops the work with an early return when `this.matchGlob(filePath, glob)`.

## When something fails

- `OrchestratorService` handles failure in 2 places: it logs it and continues in all 2.

## Diagram

```mermaid
sequenceDiagram
    participant Client
    participant OrchestratorService
    participant ParserRegistry
    participant JobQueue
    participant Parser
    participant KnowledgeGraph

    Client->>OrchestratorService: dispatchParseJob(project)
    OrchestratorService->>ParserRegistry: determineParser(project)
    ParserRegistry-->>OrchestratorService: parser name
    OrchestratorService->>JobQueue: enqueue parse job
    JobQueue-->>OrchestratorService: job ID
    OrchestratorService-->>Client: job ID

    JobQueue->>Parser: parse project
    Parser->>KnowledgeGraph: persist parsed entities
    Parser-->>JobQueue: ParseResult[]

    Client->>OrchestratorService: getJobStatus(jobId)
    OrchestratorService->>JobQueue: retrieve job status
    JobQueue-->>OrchestratorService: JobStatus
    OrchestratorService-->>Client: JobStatus
```

## Usage

```ts
import { Injectable } from '@nestjs/common';
import { OrchestratorService } from './orchestrator/orchestrator.service';

@Injectable()
export class ProjectImportService {
  constructor(private readonly orchestratorService: OrchestratorService) {}

  async importRepository(projectPath: string) {
    const parser = this.orchestratorService.determineParser(projectPath);

    if (!parser) {
      throw new Error(`No parser is available for project: ${projectPath}`);
    }

    const jobId = await this.orchestratorService.dispatchParseJob();

    const status = await this.orchestratorService.getJobStatus(jobId);

    return {
      jobId,
      parser,
      status,
      availableParsers: this.orchestratorService.getAvailableParsers(),
    };
  }

  async getImportResults(jobId: string) {
    const status = await this.orchestratorService.getJobStatus(jobId);

    if (!status) {
      return null;
    }

    return {
      status,
      results: await this.orchestratorService.getResult(),
    };
  }
}
```

## AI Coding Instructions

- Use `dispatchParseJob()` for asynchronous parsing workflows and retain the returned job ID for status polling or cancellation.
- Call `determineParser()` before dispatching when accepting arbitrary projects; handle a `null` result as an unsupported project or language.
- Treat `getJobStatus()` and `getResult()` as nullable values, since jobs may be missing, incomplete, expired, or not yet finished.
- Use `cancelJob()` only for active jobs and ensure callers handle a `false` result when cancellation is not possible.
- Keep parser-registration changes aligned with `getAvailableParsers()` and `getParserPatterns()` so parser discovery remains consistent.

## Relationships

- DEPENDS_ON → `configservice`
- DEPENDS_ON → `QueueService`
- DEPENDS_ON → `knowledgegraphservice`
- DEPENDS_ON → `KGSyncService`

## Referenced By

- `OrchestratorController` (DEPENDS_ON)
- `OrchestratorModule` (MODULE_PROVIDES)
- `OrchestratorModule` (MODULE_EXPORTS)