# sanju234-san/fc_pipeline_restructured architecture

> Architecture diagram of the GitHub repository sanju234-san/fc_pipeline_restructured, 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/sanju234-san/fc_pipeline_restructured
- Repository: https://github.com/sanju234-san/fc_pipeline_restructured

## Overview

Functional Connectivity Analysis Pipeline is an EEG analysis application: a user submits an analysis request through Chainlit, the request is clarified and planned, approved, processed into connectivity metrics, evaluated, and reported. The package also exposes stage workers through an MCP server, offers run-context follow-ups and visualization, and has a separate optional methodology-research helper. The README provides only the product name, so the workflow is assembled from the source index and sampled excerpts; dashed links mark orchestration details not directly shown in those excerpts.

Main entry points: [`chainlit_app.py`](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/chainlit_app.py) (Chainlit app), [`src/fc_pipeline/mcp_server/workers.py`](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/mcp_server/workers.py) (Stage workers), [`src/fc_pipeline/agentic/supervisor/agent.py`](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/supervisor/agent.py) (Supervisor agent), [`src/fc_pipeline/mcp_server/server.py`](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/mcp_server/server.py) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_chainlit["Chainlit app<br/>[chainlit_app.py]"]
end

subgraph group_orchestration["Planning and orchestration"]
  node_query["Query transformer"]
  node_supervisor["Supervisor agent<br/>[agent.py]"]
  node_llm["LLM provider<br/>[llm_provider.py]"]
  node_graph["Pipeline graph<br/>[graph.py]"]
  node_nodes["Pipeline nodes<br/>[nodes.py]"]
  node_plan["Analysis plan<br/>[plan.py]"]
  node_manifest["Parameter manifest<br/>[manifest.py]"]
  node_gates["Approval gates"]
end

subgraph group_analysis["EEG analysis"]
  node_prep["Data preparation<br/>[executor.py]"]
  node_connectivity["Connectivity metrics<br/>[executor.py]"]
  node_toolbox["Discovery toolbox<br/>[registry.py]"]
end

subgraph group_outputs["Evaluation and results"]
  node_evaluator["Evaluation agent<br/>[agent.py]"]
  node_synthesis["Synthesis agent<br/>[agent.py]"]
  node_viewer["EEG viewers<br/>[eeg_viewer.py]"]
  node_launcher["Viewer launcher<br/>[viewer_launcher.py]"]
end

subgraph group_services["Services and context"]
  node_mcp["MCP server<br/>[server.py]"]
  node_workers["Stage workers<br/>[workers.py]"]
  node_runcontext[("Run context<br/>[run_context.py]")]
  node_followup["Follow-up context<br/>[context_window.py]"]
  node_memory[("User memory<br/>[user_memory.py]")]
  node_tracking["MLflow tracking<br/>[mlflow_tracker.py]"]
  node_research["Research helper<br/>[research_agent.py]"]
  node_websearch["Web search<br/>[web_search.py]"]
end

node_user(("Researcher"))

node_user -->|"submits request"| node_chainlit
node_chainlit -->|"starts or resumes"| node_graph
node_chainlit -.->|"transforms request"| node_query
node_query -->|"calls"| node_llm
node_graph -.->|"dispatches stages"| node_nodes
node_nodes -.->|"invokes planning"| node_supervisor
node_supervisor -.->|"requests completions"| node_llm
node_supervisor -.->|"produces plan"| node_plan
node_supervisor -.->|"records parameters"| node_manifest
node_chainlit -.->|"handles approval"| node_gates
node_mcp -->|"unwraps tools"| node_toolbox
node_mcp -->|"dispatches stages"| node_workers
node_workers -->|"runs preparation"| node_prep
node_workers -->|"runs metrics"| node_connectivity
node_workers -->|"runs checks"| node_evaluator
node_workers -->|"runs synthesis"| node_synthesis
node_workers -->|"persists context"| node_runcontext
node_mcp -->|"reads context"| node_runcontext
node_chainlit -->|"starts tracking"| node_tracking
node_chainlit -.->|"manages follow-ups"| node_followup
node_followup -.->|"uses run data"| node_runcontext
node_chainlit -.->|"uses conversation memory"| node_memory
node_chainlit -->|"opens viewer"| node_viewer
node_chainlit -->|"launches viewer"| node_launcher
node_research -->|"uses search tool"| node_websearch
node_research -->|"obtains model"| node_llm

click node_chainlit "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/chainlit_app.py"
click node_query "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/supervisor/query_transformer.py"
click node_supervisor "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/supervisor/agent.py"
click node_llm "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/supervisor/llm_provider.py"
click node_graph "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/pipeline/graph.py"
click node_nodes "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/pipeline/nodes.py"
click node_plan "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/schemas/plan.py"
click node_manifest "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/schemas/manifest.py"
click node_gates "https://github.com/sanju234-san/fc_pipeline_restructured/tree/main/src/fc_pipeline/gates"
click node_prep "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/deterministic/data_prep/executor.py"
click node_connectivity "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/deterministic/connectivity/executor.py"
click node_toolbox "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/toolbox/registry.py"
click node_evaluator "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/evaluator/agent.py"
click node_synthesis "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/synthesis/agent.py"
click node_viewer "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/viz/eeg_viewer.py"
click node_launcher "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/viz/viewer_launcher.py"
click node_mcp "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/mcp_server/server.py"
click node_workers "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/mcp_server/workers.py"
click node_runcontext "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/pipeline/run_context.py"
click node_followup "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/followup/context_window.py"
click node_memory "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/pipeline/user_memory.py"
click node_tracking "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/observability/mlflow_tracker.py"
click node_research "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/research/research_agent.py"
click node_websearch "https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/research/web_search.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_chainlit toneBlue
class node_query,node_supervisor,node_llm,node_graph,node_nodes,node_plan,node_manifest,node_gates toneAmber
class node_prep,node_connectivity,node_toolbox toneMint
class node_evaluator,node_synthesis,node_viewer,node_launcher toneRose
class node_mcp,node_workers,node_runcontext,node_followup,node_memory,node_tracking,node_research,node_websearch,node_user toneIndigo
```

## Components

### User interface

- [Chainlit app](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/chainlit_app.py): `chainlit_app.py`

### Planning and orchestration

- [Query transformer](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/supervisor/query_transformer.py): `src/fc_pipeline/agentic/supervisor/query_transformer.py`
- [Supervisor agent](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/supervisor/agent.py): `src/fc_pipeline/agentic/supervisor/agent.py`
- [LLM provider](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/supervisor/llm_provider.py): `src/fc_pipeline/agentic/supervisor/llm_provider.py`
- [Pipeline graph](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/pipeline/graph.py): `src/fc_pipeline/pipeline/graph.py`
- [Pipeline nodes](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/pipeline/nodes.py): `src/fc_pipeline/pipeline/nodes.py`
- [Analysis plan](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/schemas/plan.py): `src/fc_pipeline/schemas/plan.py`
- [Parameter manifest](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/schemas/manifest.py): `src/fc_pipeline/schemas/manifest.py`
- [Approval gates](https://github.com/sanju234-san/fc_pipeline_restructured/tree/main/src/fc_pipeline/gates): `src/fc_pipeline/gates`

### EEG analysis

- [Data preparation](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/deterministic/data_prep/executor.py): `src/fc_pipeline/deterministic/data_prep/executor.py`
- [Connectivity metrics](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/deterministic/connectivity/executor.py): `src/fc_pipeline/deterministic/connectivity/executor.py`
- [Discovery toolbox](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/toolbox/registry.py): `src/fc_pipeline/toolbox/registry.py`

### Evaluation and results

- [Evaluation agent](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/evaluator/agent.py): `src/fc_pipeline/agentic/evaluator/agent.py`
- [Synthesis agent](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/synthesis/agent.py): `src/fc_pipeline/agentic/synthesis/agent.py`
- [EEG viewers](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/viz/eeg_viewer.py): `src/fc_pipeline/viz/eeg_viewer.py`
- [Viewer launcher](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/viz/viewer_launcher.py): `src/fc_pipeline/viz/viewer_launcher.py`

### Services and context

- [MCP server](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/mcp_server/server.py): `src/fc_pipeline/mcp_server/server.py`
- [Stage workers](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/mcp_server/workers.py): `src/fc_pipeline/mcp_server/workers.py`
- [Run context](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/pipeline/run_context.py): `src/fc_pipeline/pipeline/run_context.py`
- [Follow-up context](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/agentic/followup/context_window.py): `src/fc_pipeline/agentic/followup/context_window.py`
- [User memory](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/pipeline/user_memory.py): `src/fc_pipeline/pipeline/user_memory.py`
- [MLflow tracking](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/observability/mlflow_tracker.py): `src/fc_pipeline/observability/mlflow_tracker.py`
- [Research helper](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/research/research_agent.py): `src/fc_pipeline/research/research_agent.py`
- [Web search](https://github.com/sanju234-san/fc_pipeline_restructured/blob/main/src/fc_pipeline/research/web_search.py): `src/fc_pipeline/research/web_search.py`

### Other components

- **Researcher**

## Connections

- Researcher → Chainlit app: submits request
- Chainlit app → Pipeline graph: starts or resumes (evidence: `chainlit_app.py`)
- Chainlit app → Query transformer: transforms request (evidence: `chainlit_app.py`)
- Query transformer → LLM provider: calls (evidence: `src/fc_pipeline/agentic/supervisor/query_transformer.py`)
- Pipeline graph → Pipeline nodes: dispatches stages
- Pipeline nodes → Supervisor agent: invokes planning
- Supervisor agent → LLM provider: requests completions
- Supervisor agent → Analysis plan: produces plan
- Supervisor agent → Parameter manifest: records parameters
- Chainlit app → Approval gates: handles approval
- MCP server → Discovery toolbox: unwraps tools (evidence: `src/fc_pipeline/mcp_server/server.py`)
- MCP server → Stage workers: dispatches stages (evidence: `src/fc_pipeline/mcp_server/server.py`)
- Stage workers → Data preparation: runs preparation (evidence: `src/fc_pipeline/mcp_server/workers.py`)
- Stage workers → Connectivity metrics: runs metrics (evidence: `src/fc_pipeline/mcp_server/workers.py`)
- Stage workers → Evaluation agent: runs checks (evidence: `src/fc_pipeline/mcp_server/workers.py`)
- Stage workers → Synthesis agent: runs synthesis (evidence: `src/fc_pipeline/mcp_server/workers.py`)
- Stage workers → Run context: persists context (evidence: `src/fc_pipeline/mcp_server/workers.py`)
- MCP server → Run context: reads context (evidence: `src/fc_pipeline/mcp_server/server.py`)
- Chainlit app → MLflow tracking: starts tracking (evidence: `chainlit_app.py`)
- Chainlit app → Follow-up context: manages follow-ups
- Follow-up context → Run context: uses run data (evidence: `src/fc_pipeline/agentic/followup/context_window.py`)
- Chainlit app → User memory: uses conversation memory (evidence: `chainlit_app.py`)
- Chainlit app → EEG viewers: opens viewer (evidence: `chainlit_app.py`)
- Chainlit app → Viewer launcher: launches viewer (evidence: `chainlit_app.py`)
- Research helper → Web search: uses search tool (evidence: `src/fc_pipeline/research/research_agent.py`)
- Research helper → LLM provider: obtains model (evidence: `src/fc_pipeline/research/research_agent.py`)
