# devesh-chandan/neural_nexus architecture

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

- Interactive diagram: https://gitdiagram.com/devesh-chandan/neural_nexus
- Repository: https://github.com/devesh-chandan/neural_nexus

## Overview

This is a suitability-aware structured-products decision-support application for clients and relationship managers. Clients register or provide a profile; RMs configure products, while both can review analysis. The backend obtains market history, evaluates payoff metrics and deterministic suitability, and can generate a plain-language explanation and audit record. Recommendations compare candidate products. The README documents ELN, CPN, and DCD support, authentication, offline market-data fallback, and simulation. Source excerpts confirm the analysis, market-data, suitability, and registration paths; some unsampled integrations are shown only where documented.

Main entry points: [`backend/app/main.py`](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/App.tsx`](https://github.com/devesh-chandan/neural_nexus/blob/main/frontend/src/App.tsx) (Web application), [`backend/app/market/service.py`](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/market/service.py) (Market history), [`backend/app/recommend/engine.py`](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/recommend/engine.py) (Candidate ranking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User surfaces"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_clientflow["Client questionnaire<br/>[ClientPage.tsx]"]
  node_rmflow["RM configurator<br/>[RMPage.tsx]"]
  node_registrationui["Registration forms"]
  node_authui["Session state<br/>[useAuth.tsx]"]
end

subgraph group_onboarding["Identity and onboarding"]
  node_api["FastAPI application<br/>[main.py]"]
  node_registration["Registration service<br/>[service.py]"]
  node_kyc["KYC providers<br/>[providers.py]"]
  node_auth["Supabase auth<br/>[supabase.py]"]
end

subgraph group_analysis["Product analysis"]
  node_product["Product payoff models<br/>[registry.py]"]
  node_market["Market history<br/>[service.py]"]
  node_simulation["Historical simulation<br/>[service.py]"]
  node_analytics["Payoff analytics<br/>[metrics.py]"]
end

subgraph group_decision["Decision support"]
  node_recommend["Candidate ranking<br/>[engine.py]"]
  node_suitability["Suitability rules<br/>[engine.py]"]
  node_explanation["Result explanation<br/>[service.py]"]
end

subgraph group_persistence["Records and data"]
  node_cases[("Client cases<br/>[cases.py]")]
  node_runs[("Analysis runs<br/>[runs.py]")]
  node_audit[("Audit trail<br/>[audit.py]")]
end

node_users(("Client / RM"))
node_supabase["Supabase service"]
node_llm["LLM provider"]
node_marketprovider["Market data provider"]

node_users -->|"use"| node_webapp
node_webapp -->|"routes to"| node_clientflow
node_webapp -->|"routes to"| node_rmflow
node_webapp -->|"routes to"| node_registrationui
node_webapp -->|"provides session"| node_authui
node_clientflow -.->|"submits profile"| node_api
node_rmflow -.->|"submits configuration"| node_api
node_registrationui -.->|"submits registration"| node_api
node_authui -->|"manages session"| node_supabase
node_api -->|"routes registration"| node_registration
node_api -->|"validates tokens"| node_auth
node_registration -->|"uses providers"| node_kyc
node_registration -->|"stores client cases"| node_cases
node_api -->|"routes market access"| node_market
node_market -->|"fetches history"| node_marketprovider
node_api -->|"requests analysis"| node_analytics
node_analytics -->|"loads history"| node_market
node_analytics -->|"uses payoff models"| node_product
node_api -->|"evaluates profile"| node_suitability
node_api -->|"requests narration"| node_explanation
node_api -->|"records analysis"| node_runs
node_api -->|"appends audit"| node_audit
node_api -->|"routes recommendations"| node_recommend
node_recommend -->|"scores candidates"| node_analytics
node_recommend -->|"loads history"| node_market
node_recommend -->|"checks suitability"| node_suitability
node_api -->|"routes simulation"| node_simulation
node_simulation -.->|"uses market history"| node_market
node_explanation -.->|"optionally narrates"| node_llm

click node_webapp "https://github.com/devesh-chandan/neural_nexus/blob/main/frontend/src/App.tsx"
click node_clientflow "https://github.com/devesh-chandan/neural_nexus/blob/main/frontend/src/pages/ClientPage.tsx"
click node_rmflow "https://github.com/devesh-chandan/neural_nexus/blob/main/frontend/src/pages/RMPage.tsx"
click node_registrationui "https://github.com/devesh-chandan/neural_nexus/blob/main/frontend/src/pages/ClientRegisterPage.tsx"
click node_authui "https://github.com/devesh-chandan/neural_nexus/blob/main/frontend/src/hooks/useAuth.tsx"
click node_api "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/main.py"
click node_registration "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/registration/service.py"
click node_kyc "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/kyc/providers.py"
click node_auth "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/core/supabase.py"
click node_product "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/payoff/registry.py"
click node_market "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/market/service.py"
click node_simulation "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/simulation/service.py"
click node_analytics "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/analytics/metrics.py"
click node_recommend "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/recommend/engine.py"
click node_suitability "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/suitability/engine.py"
click node_explanation "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/explain/service.py"
click node_cases "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/store/cases.py"
click node_runs "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/store/runs.py"
click node_audit "https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/store/audit.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_webapp,node_clientflow,node_rmflow,node_registrationui,node_authui,node_users toneBlue
class node_api,node_registration,node_kyc,node_auth toneAmber
class node_product,node_market,node_simulation,node_analytics toneMint
class node_recommend,node_suitability,node_explanation toneRose
class node_cases,node_runs,node_audit,node_supabase,node_llm,node_marketprovider toneIndigo
```

## Components

### User surfaces

- [Web application](https://github.com/devesh-chandan/neural_nexus/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Client questionnaire](https://github.com/devesh-chandan/neural_nexus/blob/main/frontend/src/pages/ClientPage.tsx): `frontend/src/pages/ClientPage.tsx`
- [RM configurator](https://github.com/devesh-chandan/neural_nexus/blob/main/frontend/src/pages/RMPage.tsx): `frontend/src/pages/RMPage.tsx`
- [Registration forms](https://github.com/devesh-chandan/neural_nexus/blob/main/frontend/src/pages/ClientRegisterPage.tsx): `frontend/src/pages/ClientRegisterPage.tsx`
- [Session state](https://github.com/devesh-chandan/neural_nexus/blob/main/frontend/src/hooks/useAuth.tsx): `frontend/src/hooks/useAuth.tsx`

### Identity and onboarding

- [FastAPI application](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/main.py): `backend/app/main.py`
- [Registration service](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/registration/service.py): `backend/app/registration/service.py`
- [KYC providers](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/kyc/providers.py): `backend/app/kyc/providers.py`
- [Supabase auth](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/core/supabase.py): `backend/app/core/supabase.py`

### Product analysis

- [Product payoff models](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/payoff/registry.py): `backend/app/payoff/registry.py`
- [Market history](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/market/service.py): `backend/app/market/service.py`
- [Historical simulation](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/simulation/service.py): `backend/app/simulation/service.py`
- [Payoff analytics](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/analytics/metrics.py): `backend/app/analytics/metrics.py`

### Decision support

- [Candidate ranking](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/recommend/engine.py): `backend/app/recommend/engine.py`
- [Suitability rules](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/suitability/engine.py): `backend/app/suitability/engine.py`
- [Result explanation](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/explain/service.py): `backend/app/explain/service.py`

### Records and data

- [Client cases](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/store/cases.py): `backend/app/store/cases.py`
- [Analysis runs](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/store/runs.py): `backend/app/store/runs.py`
- [Audit trail](https://github.com/devesh-chandan/neural_nexus/blob/main/backend/app/store/audit.py): `backend/app/store/audit.py`

### Other components

- **Client / RM**
- **Supabase service**
- **LLM provider**
- **Market data provider**

## Connections

- Client / RM → Web application: use (evidence: `README.md`)
- Web application → Client questionnaire: routes to (evidence: `frontend/src/App.tsx`)
- Web application → RM configurator: routes to (evidence: `frontend/src/App.tsx`)
- Web application → Registration forms: routes to (evidence: `frontend/src/App.tsx`)
- Web application → Session state: provides session (evidence: `frontend/src/App.tsx`)
- Client questionnaire → FastAPI application: submits profile
- RM configurator → FastAPI application: submits configuration
- Registration forms → FastAPI application: submits registration
- Session state → Supabase service: manages session (evidence: `frontend/src/hooks/useAuth.tsx`)
- FastAPI application → Registration service: routes registration
- FastAPI application → Supabase auth: validates tokens (evidence: `backend/app/main.py`)
- Registration service → KYC providers: uses providers (evidence: `backend/app/api/routes_registration.py`)
- Registration service → Client cases: stores client cases (evidence: `backend/app/api/routes_registration.py`)
- FastAPI application → Market history: routes market access (evidence: `backend/app/main.py`)
- Market history → Market data provider: fetches history (evidence: `backend/app/market/service.py`)
- FastAPI application → Payoff analytics: requests analysis
- Payoff analytics → Market history: loads history (evidence: `backend/app/analytics/metrics.py`)
- Payoff analytics → Product payoff models: uses payoff models (evidence: `backend/app/analytics/metrics.py`)
- FastAPI application → Suitability rules: evaluates profile
- FastAPI application → Result explanation: requests narration
- FastAPI application → Analysis runs: records analysis
- FastAPI application → Audit trail: appends audit
- FastAPI application → Candidate ranking: routes recommendations (evidence: `backend/app/main.py`)
- Candidate ranking → Payoff analytics: scores candidates (evidence: `backend/app/recommend/engine.py`)
- Candidate ranking → Market history: loads history (evidence: `backend/app/recommend/engine.py`)
- Candidate ranking → Suitability rules: checks suitability (evidence: `backend/app/recommend/engine.py`)
- FastAPI application → Historical simulation: routes simulation (evidence: `backend/app/main.py`)
- Historical simulation → Market history: uses market history
- Result explanation → LLM provider: optionally narrates (evidence: `README.md`)
