# Data Flows and Event Model

## Primary Request Flow
```mermaid
flowchart LR
    U[User] --> G[Gateway]
    G --> R[Router]
    R --> TM[Tool Manager]
    TM --> SW[Swapper]
    TM --> MEM[Memory Service]
    TM --> AR[Artifact Registry]
    R --> LLM[Cloud or Local LLM]
    R --> G
    G --> U
```

## Canonical NATS Run Subject Policy
- Canonical publish: `agent.run.requested.{agent_id}`
- Canonical subscribe: `agent.run.requested.*`
- Keep `run_id`, `trace_id`, `tenant_id` in payload.

## Migration Plan (No Downtime)
1. Consumers subscribe to both: `agent.run.requested` and `agent.run.requested.*`.
2. Producers publish to new canonical subject and temporarily duplicate to legacy.
3. Remove legacy publish after metric confirms no consumers need it.
4. Remove legacy subscribe after legacy traffic reaches zero.

## Runtime Subject Inventory (Current vs Target)
- Current in code: `agent.run.requested` (subscriber in `services/crewai-worker/main.py`).
- Target canonical: `agent.run.requested.{agent_id}` with wildcard consumer.
- Artifact jobs already namespaced (`artifact.job.<job_type>.requested`).
- Attachment pipeline uses typed subjects (`attachment.created.{type}`, `attachment.parsed.{type}`).

## Ingest/Parser Placement Note
- On NODE1: currently **not active** in compose.
- Flow remains architecturally defined and must be bound to concrete deploy location (node/host/manifest) before marked DEPLOYED.

## Source pointers
- `services/crewai-worker/main.py`
- `services/router/main.py`
- `services/artifact-registry/app/main.py`
- `services/ingest-service/main.py`
- `services/parser-pipeline/main.py`
- `docs/NATS_SUBJECT_MAP.md`
