# pman369/neuralpeace-ai architecture

> Architecture diagram of the GitHub repository pman369/neuralpeace-ai, 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/pman369/neuralpeace-ai
- Repository: https://github.com/pman369/neuralpeace-ai

## Overview

NeuralPeace AI is a neuroscience learning and chat application. Users can explore structured learning modules, sign in, and ask expertise-adapted questions; the chat persists sessions and messages, streams AI responses with citations, and can surface brain-atlas context. Authenticated users can also participate in debates, with a separate fact-check function. The README documents ethical guardrails, Semantic Scholar citations, vector search, and the interactive atlas; several of those implementations were not sampled, so their internal wiring is shown only where documented or left unverified.

Main entry points: [`frontend/src/App.tsx`](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/App.tsx) (App routing), [`frontend/src/pages/ChatPage.tsx`](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/ChatPage.tsx) (Chat page), [`frontend/src/hooks/useDebateRoom.ts`](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/hooks/useDebateRoom.ts) (Debate state), [`frontend/src/lib/services/ai.service.ts`](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/lib/services/ai.service.ts) (AI client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_app["App routing<br/>[App.tsx]"]
  node_auth["Auth context<br/>[AuthContext.tsx]"]
  node_onboarding["Onboarding<br/>[OnboardingPage.tsx]"]
end

subgraph group_learning["Learning and Atlas"]
  node_modules["Module library<br/>[ModuleLibrary.tsx]"]
  node_module_detail["Module detail<br/>[ModuleDetail.tsx]"]
  node_atlas["Brain atlas<br/>[BrainAtlas.tsx]"]
end

subgraph group_conversation["Chat and Debate"]
  node_chat_page["Chat page<br/>[ChatPage.tsx]"]
  node_chat_ui["Chat interface<br/>[ChatInput.tsx]"]
  node_citations["Citation panel<br/>[CitationPanel.tsx]"]
  node_debate_lobby["Debate lobby<br/>[DebateLobby.tsx]"]
  node_debate_room["Debate room<br/>[DebateRoom.tsx]"]
  node_debate_hook["Debate state<br/>[useDebateRoom.ts]"]
end

subgraph group_services["AI and Data Services"]
  node_module_data["Module progress<br/>[database.ts]"]
  node_chat_repo["Chat persistence<br/>[chat.repository.ts]"]
  node_ai_service["AI client<br/>[ai.service.ts]"]
  node_edge_chat["Chat function<br/>[index.ts]"]
  node_rag["Hybrid retrieval<br/>[rag.ts]"]
  node_fact_check["Fact check<br/>[index.ts]"]
  node_knowledge_embed["Knowledge embedding<br/>[index.ts]"]
end

node_user(("Learner"))
node_gemini["Gemini AI"]
node_semantic_scholar["Semantic Scholar"]
node_supabase[("Supabase")]

node_user -->|"opens"| node_app
node_app -->|"provides auth"| node_auth
node_app -->|"routes to"| node_onboarding
node_app -->|"routes to"| node_modules
node_app -->|"routes to"| node_module_detail
node_modules -->|"loads progress"| node_module_data
node_module_detail -->|"reads module"| node_supabase
node_app -->|"routes to"| node_chat_page
node_chat_page -->|"renders"| node_chat_ui
node_chat_page -->|"loads and saves"| node_chat_repo
node_chat_page -.->|"requests response"| node_ai_service
node_ai_service -->|"invokes"| node_edge_chat
node_edge_chat -.->|"retrieves context"| node_rag
node_rag -->|"queries knowledge"| node_supabase
node_edge_chat -.->|"generates response"| node_gemini
node_ai_service -->|"fetches paper details"| node_semantic_scholar
node_chat_page -->|"shows atlas context"| node_atlas
node_chat_page -->|"opens citations"| node_citations
node_app -->|"routes to"| node_debate_lobby
node_app -->|"routes to"| node_debate_room
node_debate_room -->|"uses debate state"| node_debate_hook
node_debate_hook -->|"reads and writes"| node_supabase
node_debate_hook -->|"invokes"| node_fact_check
node_knowledge_embed -.->|"embeds knowledge"| node_supabase

click node_app "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/App.tsx"
click node_auth "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/lib/AuthContext.tsx"
click node_onboarding "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/OnboardingPage.tsx"
click node_modules "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/ModuleLibrary.tsx"
click node_module_detail "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/ModuleDetail.tsx"
click node_module_data "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/lib/database.ts"
click node_chat_page "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/ChatPage.tsx"
click node_chat_ui "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/components/ChatInput.tsx"
click node_atlas "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/components/BrainAtlas.tsx"
click node_citations "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/components/CitationPanel.tsx"
click node_chat_repo "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/lib/repositories/chat.repository.ts"
click node_ai_service "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/lib/services/ai.service.ts"
click node_edge_chat "https://github.com/pman369/neuralpeace-ai/blob/main/supabase/functions/chat/index.ts"
click node_rag "https://github.com/pman369/neuralpeace-ai/blob/main/supabase/functions/chat/rag.ts"
click node_debate_lobby "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/DebateLobby.tsx"
click node_debate_room "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/DebateRoom.tsx"
click node_debate_hook "https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/hooks/useDebateRoom.ts"
click node_fact_check "https://github.com/pman369/neuralpeace-ai/blob/main/supabase/functions/fact-check/index.ts"
click node_knowledge_embed "https://github.com/pman369/neuralpeace-ai/blob/main/supabase/functions/embed-knowledge/index.ts"

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_app,node_auth,node_onboarding toneBlue
class node_modules,node_module_detail,node_atlas,node_supabase toneAmber
class node_chat_page,node_chat_ui,node_citations,node_debate_lobby,node_debate_room,node_debate_hook toneMint
class node_module_data,node_chat_repo,node_ai_service,node_edge_chat,node_rag,node_fact_check,node_knowledge_embed toneRose
class node_user,node_gemini,node_semantic_scholar toneIndigo
```

## Components

### Application

- [App routing](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth context](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/lib/AuthContext.tsx): `frontend/src/lib/AuthContext.tsx`
- [Onboarding](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/OnboardingPage.tsx): `frontend/src/pages/OnboardingPage.tsx`

### Learning and Atlas

- [Module library](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/ModuleLibrary.tsx): `frontend/src/pages/ModuleLibrary.tsx`
- [Module detail](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/ModuleDetail.tsx): `frontend/src/pages/ModuleDetail.tsx`
- [Brain atlas](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/components/BrainAtlas.tsx): `frontend/src/components/BrainAtlas.tsx`

### Chat and Debate

- [Chat page](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/ChatPage.tsx): `frontend/src/pages/ChatPage.tsx`
- [Chat interface](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/components/ChatInput.tsx): `frontend/src/components/ChatInput.tsx`
- [Citation panel](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/components/CitationPanel.tsx): `frontend/src/components/CitationPanel.tsx`
- [Debate lobby](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/DebateLobby.tsx): `frontend/src/pages/DebateLobby.tsx`
- [Debate room](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/pages/DebateRoom.tsx): `frontend/src/pages/DebateRoom.tsx`
- [Debate state](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/hooks/useDebateRoom.ts): `frontend/src/hooks/useDebateRoom.ts`

### AI and Data Services

- [Module progress](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/lib/database.ts): `frontend/src/lib/database.ts`
- [Chat persistence](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/lib/repositories/chat.repository.ts): `frontend/src/lib/repositories/chat.repository.ts`
- [AI client](https://github.com/pman369/neuralpeace-ai/blob/main/frontend/src/lib/services/ai.service.ts): `frontend/src/lib/services/ai.service.ts`
- [Chat function](https://github.com/pman369/neuralpeace-ai/blob/main/supabase/functions/chat/index.ts): `supabase/functions/chat/index.ts`
- [Hybrid retrieval](https://github.com/pman369/neuralpeace-ai/blob/main/supabase/functions/chat/rag.ts): `supabase/functions/chat/rag.ts`
- [Fact check](https://github.com/pman369/neuralpeace-ai/blob/main/supabase/functions/fact-check/index.ts): `supabase/functions/fact-check/index.ts`
- [Knowledge embedding](https://github.com/pman369/neuralpeace-ai/blob/main/supabase/functions/embed-knowledge/index.ts): `supabase/functions/embed-knowledge/index.ts`

### Other components

- **Learner**
- **Gemini AI**
- **Semantic Scholar**
- **Supabase**

## Connections

- Learner → App routing: opens
- App routing → Auth context: provides auth (evidence: `frontend/src/App.tsx`)
- App routing → Onboarding: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Module library: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Module detail: routes to (evidence: `frontend/src/App.tsx`)
- Module library → Module progress: loads progress (evidence: `frontend/src/lib/database.ts`)
- Module detail → Supabase: reads module (evidence: `frontend/src/pages/ModuleDetail.tsx`)
- App routing → Chat page: routes to (evidence: `frontend/src/App.tsx`)
- Chat page → Chat interface: renders (evidence: `frontend/src/pages/ChatPage.tsx`)
- Chat page → Chat persistence: loads and saves (evidence: `frontend/src/pages/ChatPage.tsx`)
- Chat page → AI client: requests response
- AI client → Chat function: invokes (evidence: `frontend/src/lib/services/ai.service.ts`)
- Chat function → Hybrid retrieval: retrieves context
- Hybrid retrieval → Supabase: queries knowledge (evidence: `supabase/functions/chat/rag.ts`)
- Chat function → Gemini AI: generates response
- AI client → Semantic Scholar: fetches paper details (evidence: `frontend/src/lib/services/ai.service.ts`)
- Chat page → Brain atlas: shows atlas context (evidence: `frontend/src/pages/ChatPage.tsx`)
- Chat page → Citation panel: opens citations (evidence: `frontend/src/pages/ChatPage.tsx`)
- App routing → Debate lobby: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Debate room: routes to (evidence: `frontend/src/App.tsx`)
- Debate room → Debate state: uses debate state (evidence: `frontend/src/pages/DebateRoom.tsx`)
- Debate state → Supabase: reads and writes (evidence: `frontend/src/hooks/useDebateRoom.ts`)
- Debate state → Fact check: invokes (evidence: `frontend/src/hooks/useDebateRoom.ts`)
- Knowledge embedding → Supabase: embeds knowledge
