# kpuneethharshanaik/neuroagent architecture

> Architecture diagram of the GitHub repository kpuneethharshanaik/neuroagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kpuneethharshanaik/neuroagent
- Repository: https://github.com/kpuneethharshanaik/neuroagent

## Overview

NeuroAgent accepts an event-marked EEG recording, processes it through validation, signal preparation, prediction, policy decision, and report stages, then keeps the human review distinct from the automated verdict. The React workspace uploads and tracks jobs, presents evidence and signal previews, and records reviews; a public landing page is also served. The README documents both an in-process pipeline and optional step-wise n8n orchestration. The map uses documented responsibilities and sampled wiring; unsampled implementation details are not inferred.

Main entry points: [`web/src/tool/Tool.tsx`](https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/Tool.tsx) (Review workspace), [`web/src/tool/useLiveJob.ts`](https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/useLiveJob.ts) (Live job tracking), [`backend/main.py`](https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/main.py) (FastAPI routes), [`backend/agents.py`](https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/agents.py) (Stage agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_jobstore[("Job records<br/>[main.py]")]
end

subgraph group_pipeline["Review pipeline"]
  node_stepagents["Stage agents<br/>[agents.py]"]
  node_graph["Pipeline graph<br/>[graph.py]"]
  node_eeg["EEG processing<br/>[eeg.py]"]
  node_evidence["Evidence checks<br/>[evidence.py]"]
  node_inference["FBCNet inference<br/>[inference.py]"]
  node_policy["Deterministic policy<br/>[policy.py]"]
  node_feedback["Review recording<br/>[feedback.py]"]
  node_schemas["Job and report types<br/>[schemas.py]"]
end

subgraph group_workspace["Review workspace"]
  node_tool["Review workspace<br/>[Tool.tsx]"]
  node_livejob["Live job tracking<br/>[useLiveJob.ts]"]
  node_clientapi["API client<br/>[api.ts]"]
  node_upload["Upload panel<br/>[UploadPanel.tsx]"]
  node_pipelineview["Pipeline view<br/>[PipelinePanel.tsx]"]
  node_evidenceview["Evidence panel<br/>[EvidencePanel.tsx]"]
  node_signalview["Signal lens<br/>[SignalLens.tsx]"]
  node_brief["Review brief<br/>[ReviewBrief.tsx]"]
end

subgraph group_public["Public site"]
  node_landing["Landing experience<br/>[Landing.tsx]"]
end

node_uploader(("EEG submitter"))
node_reviewer(("Human reviewer"))
node_n8n{{"n8n orchestrator"}}

node_uploader -->|"selects recording"| node_upload
node_upload -->|"submits file"| node_tool
node_tool -->|"starts or resumes"| node_livejob
node_livejob -->|"requests job"| node_clientapi
node_clientapi -->|"calls routes"| node_api
node_api -->|"stores job state"| node_jobstore
node_api -->|"runs pipeline"| node_graph
node_api -.->|"hands off optionally"| node_n8n
node_n8n -.->|"calls step routes"| node_api
node_graph -->|"dispatches stages"| node_stepagents
node_stepagents -->|"processes recording"| node_eeg
node_stepagents -->|"checks evidence"| node_evidence
node_stepagents -->|"classifies trials"| node_inference
node_stepagents -->|"evaluates gates"| node_policy
node_graph -->|"produces report"| node_schemas
node_api -->|"records review"| node_feedback
node_tool -->|"renders"| node_upload
node_tool -->|"renders"| node_pipelineview
node_tool -->|"renders"| node_evidenceview
node_tool -->|"renders"| node_signalview
node_tool -->|"renders"| node_brief
node_livejob -->|"supplies updates"| node_pipelineview
node_livejob -->|"supplies updates"| node_evidenceview
node_livejob -->|"supplies job"| node_signalview
node_livejob -->|"supplies report"| node_brief
node_signalview -->|"requests preview"| node_clientapi
node_brief -->|"presents verdict"| node_reviewer
node_reviewer -->|"submits decision"| node_brief
node_brief -->|"records review"| node_clientapi
node_landing -->|"offers workspace"| node_uploader

click node_api "https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/main.py"
click node_jobstore "https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/main.py"
click node_stepagents "https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/agents.py"
click node_graph "https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/graph.py"
click node_eeg "https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/eeg.py"
click node_evidence "https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/evidence.py"
click node_inference "https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/inference.py"
click node_policy "https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/policy.py"
click node_feedback "https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/feedback.py"
click node_schemas "https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/schemas.py"
click node_tool "https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/Tool.tsx"
click node_livejob "https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/useLiveJob.ts"
click node_clientapi "https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/lib/api.ts"
click node_upload "https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/UploadPanel.tsx"
click node_pipelineview "https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/PipelinePanel.tsx"
click node_evidenceview "https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/EvidencePanel.tsx"
click node_signalview "https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/SignalLens.tsx"
click node_brief "https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/ReviewBrief.tsx"
click node_landing "https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/landing/Landing.tsx"

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_api,node_jobstore,node_reviewer toneBlue
class node_stepagents,node_graph,node_eeg,node_evidence,node_inference,node_policy,node_feedback,node_schemas toneAmber
class node_tool,node_livejob,node_clientapi,node_upload,node_pipelineview,node_evidenceview,node_signalview,node_brief toneMint
class node_landing toneRose
class node_uploader,node_n8n toneIndigo
```

## Components

### API and orchestration

- [FastAPI routes](https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/main.py): `backend/main.py`
- [Job records](https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/main.py): `backend/main.py`

### Review pipeline

- [Stage agents](https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/agents.py): `backend/agents.py`
- [Pipeline graph](https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/graph.py): `backend/graph.py`
- [EEG processing](https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/eeg.py): `backend/eeg.py`
- [Evidence checks](https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/evidence.py): `backend/evidence.py`
- [FBCNet inference](https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/inference.py): `backend/inference.py`
- [Deterministic policy](https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/policy.py): `backend/policy.py`
- [Review recording](https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/feedback.py): `backend/feedback.py`
- [Job and report types](https://github.com/kpuneethharshanaik/neuroagent/blob/main/backend/schemas.py): `backend/schemas.py`

### Review workspace

- [Review workspace](https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/Tool.tsx): `web/src/tool/Tool.tsx`
- [Live job tracking](https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/useLiveJob.ts): `web/src/tool/useLiveJob.ts`
- [API client](https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Upload panel](https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/UploadPanel.tsx): `web/src/tool/UploadPanel.tsx`
- [Pipeline view](https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/PipelinePanel.tsx): `web/src/tool/PipelinePanel.tsx`
- [Evidence panel](https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/EvidencePanel.tsx): `web/src/tool/EvidencePanel.tsx`
- [Signal lens](https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/SignalLens.tsx): `web/src/tool/SignalLens.tsx`
- [Review brief](https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/tool/ReviewBrief.tsx): `web/src/tool/ReviewBrief.tsx`

### Public site

- [Landing experience](https://github.com/kpuneethharshanaik/neuroagent/blob/main/web/src/landing/Landing.tsx): `web/src/landing/Landing.tsx`

### Other components

- **EEG submitter**
- **Human reviewer**
- **n8n orchestrator**

## Connections

- EEG submitter → Upload panel: selects recording
- Upload panel → Review workspace: submits file
- Review workspace → Live job tracking: starts or resumes
- Live job tracking → API client: requests job
- API client → FastAPI routes: calls routes
- FastAPI routes → Job records: stores job state
- FastAPI routes → Pipeline graph: runs pipeline
- FastAPI routes → n8n orchestrator: hands off optionally
- n8n orchestrator → FastAPI routes: calls step routes
- Pipeline graph → Stage agents: dispatches stages
- Stage agents → EEG processing: processes recording
- Stage agents → Evidence checks: checks evidence
- Stage agents → FBCNet inference: classifies trials
- Stage agents → Deterministic policy: evaluates gates
- Pipeline graph → Job and report types: produces report
- FastAPI routes → Review recording: records review
- Review workspace → Upload panel: renders
- Review workspace → Pipeline view: renders
- Review workspace → Evidence panel: renders
- Review workspace → Signal lens: renders
- Review workspace → Review brief: renders
- Live job tracking → Pipeline view: supplies updates
- Live job tracking → Evidence panel: supplies updates
- Live job tracking → Signal lens: supplies job
- Live job tracking → Review brief: supplies report
- Signal lens → API client: requests preview
- Review brief → Human reviewer: presents verdict
- Human reviewer → Review brief: submits decision
- Review brief → API client: records review
- Landing experience → EEG submitter: offers workspace