# prabhat-190/synapse-flow- architecture

> Architecture diagram of the GitHub repository prabhat-190/synapse-flow-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prabhat-190/synapse-flow-
- Repository: https://github.com/prabhat-190/synapse-flow-

## Overview

SynapseFlow accepts queries through a secured FastAPI gateway, executes a stateful multi-agent DAG on a shared blackboard, and returns a trace and answer. The pipeline owns agent dispatch, compression on budget overflow, persistence, and resume behavior. Supporting branches cover two-hop retrieval, model reliability, streaming and distributed execution, human-approved prompt rewrites, and evaluation. Edges reflect shown calls, source-index references, or README claims; some capabilities are documented but their implementation details were not sampled.

Main entry points: [`src/synapse/agents/pipeline.py`](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/pipeline.py) (DAG Pipeline), [`src/synapse/gateway/app.py`](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/gateway/app.py) (FastAPI Gateway), [`src/synapse/eval/harness.py`](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/eval/harness.py) (Evaluation Harness), [`src/synapse/agents/base.py`](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/base.py) (Agent Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and Access"]
  node_gateway["FastAPI Gateway<br/>[app.py]"]
  node_security["Request Security<br/>[security.py]"]
end

subgraph group_execution["Agent Execution"]
  node_pipeline["DAG Pipeline<br/>[pipeline.py]"]
  node_blackboard["Shared Blackboard<br/>[blackboard.py]"]
  node_domain["Execution Models<br/>[models.py]"]
  node_orchestrator["Orchestrator Agent<br/>[orchestrator.py]"]
  node_decomposition["Decomposition Agent<br/>[decomposition.py]"]
  node_reasoning["Reasoning Agent<br/>[reasoning.py]"]
  node_critique["Critique Agent<br/>[critique.py]"]
  node_synthesis["Synthesis Agent<br/>[synthesis.py]"]
  node_compression["Compression Agent<br/>[compression.py]"]
  node_meta["Meta Agent<br/>[meta.py]"]
  node_agentbase["Agent Runtime<br/>[base.py]"]
end

subgraph group_knowledge["Retrieval and Models"]
  node_retrieval["Retrieval Agent<br/>[retrieval.py]"]
  node_rag["Two-Hop RAG<br/>[two_hop.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_llm["LLM Router<br/>[llm.py]"]
  node_modelprovider["Gemini Provider<br/>[llm.py]"]
end

subgraph group_reliability["Persistence and Operations"]
  node_database[("PostgreSQL Store<br/>[database.py]")]
  node_redis["Redis Event Bus<br/>[redis_bus.py]"]
  node_celery["Celery Workers<br/>[celery_app.py]"]
  node_metrics["Prometheus Metrics<br/>[metrics.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evalapi["Evaluation Harness<br/>[harness.py]"]
  node_evaldata["Evaluation Cases<br/>[datasets.py]"]
end

node_client(("API Client"))
node_modelservice(("Gemini API<br/>external service"))

node_client -->|"submits query"| node_gateway
node_gateway -->|"screens requests"| node_security
node_gateway -->|"runs query"| node_pipeline
node_gateway -->|"queues async run"| node_celery
node_gateway -->|"loads traces"| node_database
node_gateway -->|"streams events"| node_redis
node_gateway -->|"exposes metrics"| node_metrics
node_gateway -->|"approves rewrites"| node_meta
node_gateway -->|"starts evaluation"| node_evalapi
node_pipeline -->|"dispatches agents"| node_orchestrator
node_pipeline -->|"dispatches agents"| node_decomposition
node_pipeline -->|"dispatches agents"| node_retrieval
node_pipeline -->|"dispatches agents"| node_reasoning
node_pipeline -->|"dispatches agents"| node_critique
node_pipeline -->|"dispatches agents"| node_synthesis
node_pipeline -->|"dispatches agents"| node_meta
node_pipeline -->|"handles overflow"| node_compression
node_pipeline -->|"shares state"| node_blackboard
node_pipeline -->|"persists traces"| node_database
node_pipeline -->|"loads checkpoints"| node_redis
node_agentbase -->|"records events"| node_blackboard
node_agentbase -->|"requests generation"| node_llm
node_agentbase -->|"publishes events"| node_redis
node_retrieval -->|"retrieves context"| node_rag
node_retrieval -->|"embeds queries"| node_embeddings
node_rag -->|"uses vectors"| node_embeddings
node_rag -->|"searches documents"| node_database
node_llm -->|"routes generation"| node_modelprovider
node_modelprovider -.->|"calls Gemini"| node_modelservice
node_celery -->|"runs tasks"| node_pipeline
node_evalapi -->|"loads cases"| node_evaldata
node_evalapi -->|"evaluates runs"| node_pipeline
node_evalapi -->|"judges results"| node_llm

click node_gateway "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/gateway/app.py"
click node_security "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/gateway/security.py"
click node_pipeline "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/pipeline.py"
click node_blackboard "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/core/blackboard.py"
click node_domain "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/core/models.py"
click node_orchestrator "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/orchestrator.py"
click node_decomposition "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/decomposition.py"
click node_reasoning "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/reasoning.py"
click node_critique "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/critique.py"
click node_synthesis "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/synthesis.py"
click node_compression "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/compression.py"
click node_meta "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/meta.py"
click node_agentbase "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/base.py"
click node_retrieval "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/retrieval.py"
click node_rag "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/rag/two_hop.py"
click node_embeddings "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/rag/embeddings.py"
click node_llm "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/infra/llm.py"
click node_modelprovider "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/infra/llm.py"
click node_database "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/infra/database.py"
click node_redis "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/infra/redis_bus.py"
click node_celery "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/infra/celery_app.py"
click node_metrics "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/observability/metrics.py"
click node_evalapi "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/eval/harness.py"
click node_evaldata "https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/eval/datasets.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway,node_security,node_client toneBlue
class node_pipeline,node_blackboard,node_domain,node_orchestrator,node_decomposition,node_reasoning,node_critique,node_synthesis,node_compression,node_meta,node_agentbase toneAmber
class node_retrieval,node_rag,node_embeddings,node_llm,node_modelprovider,node_modelservice toneMint
class node_database,node_redis,node_celery,node_metrics toneRose
class node_evalapi,node_evaldata toneIndigo
```

## Components

### API and Access

- [FastAPI Gateway](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/gateway/app.py): `src/synapse/gateway/app.py`
- [Request Security](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/gateway/security.py): `src/synapse/gateway/security.py`

### Agent Execution

- [DAG Pipeline](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/pipeline.py): `src/synapse/agents/pipeline.py`
- [Shared Blackboard](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/core/blackboard.py): `src/synapse/core/blackboard.py`
- [Execution Models](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/core/models.py): `src/synapse/core/models.py`
- [Orchestrator Agent](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/orchestrator.py): `src/synapse/agents/orchestrator.py`
- [Decomposition Agent](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/decomposition.py): `src/synapse/agents/decomposition.py`
- [Reasoning Agent](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/reasoning.py): `src/synapse/agents/reasoning.py`
- [Critique Agent](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/critique.py): `src/synapse/agents/critique.py`
- [Synthesis Agent](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/synthesis.py): `src/synapse/agents/synthesis.py`
- [Compression Agent](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/compression.py): `src/synapse/agents/compression.py`
- [Meta Agent](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/meta.py): `src/synapse/agents/meta.py`
- [Agent Runtime](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/base.py): `src/synapse/agents/base.py`

### Retrieval and Models

- [Retrieval Agent](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/agents/retrieval.py): `src/synapse/agents/retrieval.py`
- [Two-Hop RAG](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/rag/two_hop.py): `src/synapse/rag/two_hop.py`
- [Embeddings](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/rag/embeddings.py): `src/synapse/rag/embeddings.py`
- [LLM Router](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/infra/llm.py): `src/synapse/infra/llm.py`
- [Gemini Provider](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/infra/llm.py): `src/synapse/infra/llm.py`

### Persistence and Operations

- [PostgreSQL Store](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/infra/database.py): `src/synapse/infra/database.py`
- [Redis Event Bus](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/infra/redis_bus.py): `src/synapse/infra/redis_bus.py`
- [Celery Workers](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/infra/celery_app.py): `src/synapse/infra/celery_app.py`
- [Prometheus Metrics](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/observability/metrics.py): `src/synapse/observability/metrics.py`

### Evaluation

- [Evaluation Harness](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/eval/harness.py): `src/synapse/eval/harness.py`
- [Evaluation Cases](https://github.com/prabhat-190/synapse-flow-/blob/main/src/synapse/eval/datasets.py): `src/synapse/eval/datasets.py`

### Other components

- **API Client**
- **Gemini API**: external service

## Connections

- API Client → FastAPI Gateway: submits query (evidence: `README.md`)
- FastAPI Gateway → Request Security: screens requests (evidence: `src/synapse/gateway/app.py`)
- FastAPI Gateway → DAG Pipeline: runs query (evidence: `src/synapse/gateway/app.py`)
- FastAPI Gateway → Celery Workers: queues async run (evidence: `src/synapse/gateway/app.py`)
- FastAPI Gateway → PostgreSQL Store: loads traces (evidence: `src/synapse/gateway/app.py`)
- FastAPI Gateway → Redis Event Bus: streams events (evidence: `src/synapse/gateway/app.py`)
- FastAPI Gateway → Prometheus Metrics: exposes metrics (evidence: `src/synapse/gateway/app.py`)
- FastAPI Gateway → Meta Agent: approves rewrites (evidence: `src/synapse/gateway/app.py`)
- FastAPI Gateway → Evaluation Harness: starts evaluation (evidence: `src/synapse/gateway/app.py`)
- DAG Pipeline → Orchestrator Agent: dispatches agents (evidence: `src/synapse/agents/pipeline.py`)
- DAG Pipeline → Decomposition Agent: dispatches agents (evidence: `src/synapse/agents/pipeline.py`)
- DAG Pipeline → Retrieval Agent: dispatches agents (evidence: `src/synapse/agents/pipeline.py`)
- DAG Pipeline → Reasoning Agent: dispatches agents (evidence: `src/synapse/agents/pipeline.py`)
- DAG Pipeline → Critique Agent: dispatches agents (evidence: `src/synapse/agents/pipeline.py`)
- DAG Pipeline → Synthesis Agent: dispatches agents (evidence: `src/synapse/agents/pipeline.py`)
- DAG Pipeline → Meta Agent: dispatches agents (evidence: `src/synapse/agents/pipeline.py`)
- DAG Pipeline → Compression Agent: handles overflow (evidence: `src/synapse/agents/pipeline.py`)
- DAG Pipeline → Shared Blackboard: shares state (evidence: `src/synapse/agents/pipeline.py`)
- DAG Pipeline → PostgreSQL Store: persists traces (evidence: `src/synapse/agents/pipeline.py`)
- DAG Pipeline → Redis Event Bus: loads checkpoints (evidence: `src/synapse/agents/pipeline.py`)
- Agent Runtime → Shared Blackboard: records events (evidence: `src/synapse/agents/base.py`)
- Agent Runtime → LLM Router: requests generation (evidence: `src/synapse/agents/base.py`)
- Agent Runtime → Redis Event Bus: publishes events (evidence: `src/synapse/agents/base.py`)
- Retrieval Agent → Two-Hop RAG: retrieves context (evidence: `src/synapse/agents/retrieval.py`)
- Retrieval Agent → Embeddings: embeds queries (evidence: `src/synapse/agents/retrieval.py`)
- Two-Hop RAG → Embeddings: uses vectors (evidence: `src/synapse/rag/two_hop.py`)
- Two-Hop RAG → PostgreSQL Store: searches documents (evidence: `README.md`)
- LLM Router → Gemini Provider: routes generation (evidence: `src/synapse/infra/llm.py`)
- Gemini Provider → Gemini API: calls Gemini · Inferred; not shown in the code that was read.
- Celery Workers → DAG Pipeline: runs tasks (evidence: `src/synapse/infra/celery_app.py`)
- Evaluation Harness → Evaluation Cases: loads cases (evidence: `src/synapse/eval/harness.py`)
- Evaluation Harness → DAG Pipeline: evaluates runs (evidence: `src/synapse/eval/harness.py`)
- Evaluation Harness → LLM Router: judges results (evidence: `src/synapse/eval/harness.py`)
