# KGSyncService

**Kind:** Service

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

`KGSyncService` coordinates synchronization between parsed project data and the knowledge graph. It supports full syncs, batch syncs, project-specific sync and resync operations, and exposes aggregate synchronization status for monitoring or API consumers.

## Methods

| Method | Signature | Returns | Description |
|---|---|---|---|
| `sync` | `sync(parseResult: ParseResult)` | `Promise<SyncResult>` | Sync a single parse result to the Knowledge Graph |
| `syncBatch` | `syncBatch(parseResults: ParseResult[])` | `Promise<SyncResult>` | Sync multiple parse results in batch (optimized) |
| `syncProject` | `syncProject(projectResult: ProjectParseResult)` | `Promise<SyncResult>` | Sync a project parse result |
| `resyncProject` | `resyncProject(projectId: string, parseResults: ParseResult[])` | `Promise<SyncResult>` | Clear and resync all parse results for a project |
| `getSyncStatus` | `getSyncStatus(projectId: string)` | `Promise<{
    totalEntities: number;
    totalRelationships: number;
    lastSyncedAt?: Date;
  }>` | Get sync status for a project |

## Dependencies

- `KnowledgeGraphService`

## When something fails

- `KGSyncService` handles failure in 4 places: it logs it and continues in all 4.

## Diagram

```mermaid
sequenceDiagram
  participant Caller
  participant KGSyncService
  participant Parser as Parsed Project Data
  participant KG as Knowledge Graph

  Caller->>KGSyncService: sync() / syncProject()
  KGSyncService->>Parser: Load entities and relationships
  Parser-->>KGSyncService: Parsed graph data
  KGSyncService->>KG: Upsert entities
  KGSyncService->>KG: Upsert relationships
  KG-->>KGSyncService: Sync result
  KGSyncService-->>Caller: Promise<SyncResult>

  Caller->>KGSyncService: getSyncStatus()
  KGSyncService->>KG: Query graph counts and last sync time
  KG-->>KGSyncService: Status data
  KGSyncService-->>Caller: totalEntities, totalRelationships, lastSyncedAt
```

## Usage

```ts
import { Injectable } from '@nestjs/common';
import { KGSyncService } from './knowledge-graph/sync/kg-sync.service';

@Injectable()
export class KnowledgeGraphAdminService {
  constructor(private readonly kgSyncService: KGSyncService) {}

  async syncCurrentProject() {
    const result = await this.kgSyncService.syncProject();

    return {
      success: true,
      result,
      status: await this.kgSyncService.getSyncStatus(),
    };
  }

  async rebuildProjectGraph() {
    // Use resync when existing project graph data should be refreshed.
    return this.kgSyncService.resyncProject();
  }
}
```

## AI Coding Instructions

- Use `syncProject()` for normal project-level synchronization and `resyncProject()` when existing graph data must be rebuilt or refreshed.
- Prefer `syncBatch()` when processing multiple synchronization units to avoid repeatedly invoking individual sync operations.
- Treat `SyncResult` as the source of truth for operation outcomes; do not assume all entities or relationships were synchronized successfully.
- Call `getSyncStatus()` for observability and administrative endpoints rather than calculating graph totals in callers.
- Preserve NestJS dependency injection patterns: inject `KGSyncService` through constructors instead of instantiating it directly.

## Relationships

- DEPENDS_ON → `knowledgegraphservice`

## Referenced By

- `KnowledgeGraphModule` (MODULE_PROVIDES)
- `KnowledgeGraphModule` (MODULE_EXPORTS)
- `OrchestratorService` (DEPENDS_ON)