# WorkflowStorageService

**Kind:** Service

**Source:** [`atloria-monorepo/apps/api/src/workflow/workflow-storage.service.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/apps/api/src/workflow/workflow-storage.service.ts#L11)

`WorkflowStorageService` is a NestJS service responsible for persisting discovered workflow metadata and retrieving it for later use. It provides a small storage abstraction for saving the current workflow set, reading stored `DiscoveredWorkflow` records, and clearing persisted workflows when they need to be refreshed or removed.

## Methods

| Method | Signature | Returns | Description |
|---|---|---|---|
| `storeWorkflows` | `storeWorkflows(projectId: string, workflows: DiscoveredWorkflow[])` | `Promise<void>` | Store discovered workflows in Neo4j |
| `getWorkflows` | `getWorkflows(projectId: string)` | `Promise<DiscoveredWorkflow[]>` | Query workflows for a project |
| `deleteWorkflows` | `deleteWorkflows(projectId: string)` | `Promise<void>` | Delete workflows for a project |

## Dependencies

- `Neo4jService`

## When something fails

- `WorkflowStorageService` handles failure in 1 place: it lets it reach the caller in all 1.

## Diagram

```mermaid
sequenceDiagram
    participant Caller as Workflow Consumer
    participant Service as WorkflowStorageService
    participant Storage as Persistence Layer

    Caller->>Service: storeWorkflows()
    Service->>Storage: Persist discovered workflows
    Storage-->>Service: Write complete
    Service-->>Caller: Promise<void>

    Caller->>Service: getWorkflows()
    Service->>Storage: Read stored workflows
    Storage-->>Service: DiscoveredWorkflow[]
    Service-->>Caller: DiscoveredWorkflow[]

    Caller->>Service: deleteWorkflows()
    Service->>Storage: Remove stored workflows
    Storage-->>Service: Delete complete
    Service-->>Caller: Promise<void>
```

## Usage

```ts
import { Injectable } from '@nestjs/common';
import { WorkflowStorageService } from './workflow-storage.service';

@Injectable()
export class WorkflowRefreshService {
  constructor(
    private readonly workflowStorageService: WorkflowStorageService,
  ) {}

  async refreshWorkflows(): Promise<void> {
    // Clear outdated workflow records before persisting a refreshed set.
    await this.workflowStorageService.deleteWorkflows();

    // Persist workflows discovered by the workflow subsystem.
    await this.workflowStorageService.storeWorkflows();

    const workflows = await this.workflowStorageService.getWorkflows();

    console.log(`Loaded ${workflows.length} stored workflows.`);
  }
}
```

## AI Coding Instructions

- Inject `WorkflowStorageService` through NestJS constructor injection; do not instantiate it directly.
- Treat `storeWorkflows()` and `deleteWorkflows()` as asynchronous persistence operations and always `await` them.
- Use `getWorkflows()` as the canonical source for persisted `DiscoveredWorkflow` records rather than duplicating storage access in consumers.
- When implementing refresh flows, consider clearing stale records with `deleteWorkflows()` before calling `storeWorkflows()`.
- Preserve the `DiscoveredWorkflow[]` return contract when changing retrieval or storage integrations.

## Relationships

- DEPENDS_ON → `Neo4jService`

## Referenced By

- `GraphModule` (MODULE_PROVIDES)
- `GraphModule` (MODULE_EXPORTS)
- `KgSyncController` (DEPENDS_ON)
- `SyncController` (DEPENDS_ON)
- `WorkflowModule` (MODULE_PROVIDES)
- `WorkflowModule` (MODULE_EXPORTS)