# prakharyadav2006/niveshsetufinal architecture

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

- Interactive diagram: https://gitdiagram.com/prakharyadav2006/niveshsetufinal
- Repository: https://github.com/prakharyadav2006/niveshsetufinal

## Overview

NiveshSetu is an investor-education product with a main fictional-market simulator and a separate scripted Telegram-tip demo. In the simulator, a player onboards, explores a deterministic market, and submits orders through a reasoning check; the app also provides coaching, alerts, lessons, and a behaviour report. The backend builds facts and applies safety checks around Sarvam AI, with offline fallbacks. The graph reflects documented workflows and indexed imports; some API and alert internals were not sampled, so uncertain links are omitted.

Main entry points: [`public/simulator/app.js`](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/simulator/app.js) (Simulator UI), [`public/demo-run/app.js`](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/demo-run/app.js) (Demo UI), [`lib/ai.js`](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/lib/ai.js) (AI Gateway), [`lib/safety.js`](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/lib/safety.js) (AI Safety)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sim["Market Simulator"]
  node_simapp["Simulator UI<br/>[app.js]"]
  node_marketdata["Market Data<br/>[data.js]"]
  node_engine["Market Engine<br/>[engine.js]"]
  node_alerts["Price Alerts<br/>[alerts.js]"]
  node_metrics["Behaviour Metrics<br/>[metrics.js]"]
end

subgraph group_demo["Tip Demo"]
  node_demoapp["Demo UI<br/>[app.js]"]
  node_democontent["Demo Scenarios<br/>[content.js]"]
  node_demoengine["Demo Story Engine<br/>[engine.js]"]
end

subgraph group_backend["AI Backend"]
  node_reasonapi["Order Reason API<br/>[reason.js]"]
  node_facts["Facts Builder<br/>[facts.js]"]
  node_safety["AI Safety<br/>[safety.js]"]
  node_aigateway["AI Gateway<br/>[ai.js]"]
  node_sarvam["Sarvam Service<br/>[sarvam.js]"]
  node_coach["Coach API<br/>[coach.js]"]
  node_report["Behaviour Report API<br/>[report.js]"]
  node_ask["Q&amp;A API<br/>[ask.js]"]
  node_explain["Explanation API<br/>[explain.js]"]
  node_debrief["Debrief API<br/>[debrief.js]"]
  node_speech["Speech APIs<br/>[tts.js]"]
end

subgraph group_shared["Shared Learning"]
  node_profile["Onboarding Profile<br/>[profile.js]"]
  node_gate["Reasoning Gate<br/>[gate.js]"]
  node_reasoning["Offline Reasoning<br/>[reasoning.js]"]
  node_lessons["Lessons and Resources<br/>[lessons.js]"]
  node_listen["Shared Listening<br/>[listen.js]"]
end

node_player(("Player"))

node_player -->|"uses"| node_simapp
node_simapp -->|"collects profile"| node_profile
node_simapp -->|"reads market"| node_marketdata
node_simapp -->|"runs market"| node_engine
node_simapp -->|"manages alerts"| node_alerts
node_simapp -->|"computes habits"| node_metrics
node_simapp -->|"checks orders"| node_gate
node_gate -->|"requests verdict"| node_reasonapi
node_gate -->|"uses offline check"| node_reasoning
node_reasonapi -->|"builds order facts"| node_facts
node_reasonapi -->|"checks and limits"| node_safety
node_reasonapi -->|"requests judgment"| node_aigateway
node_aigateway -->|"calls model"| node_sarvam
node_coach -->|"builds context"| node_facts
node_coach -->|"checks output"| node_safety
node_coach -->|"requests notes"| node_aigateway
node_report -->|"requests insights"| node_aigateway
node_report -->|"checks output"| node_safety
node_simapp -.->|"requests coaching"| node_coach
node_simapp -.->|"requests report"| node_report
node_simapp -->|"shows lessons"| node_lessons
node_player -->|"uses demo"| node_demoapp
node_demoapp -->|"renders scenarios"| node_democontent
node_demoapp -->|"runs story"| node_demoengine
node_demoapp -->|"requests debrief"| node_debrief
node_demoapp -->|"requests explanations"| node_explain
node_demoapp -.->|"requests answers"| node_ask
node_ask -->|"builds context"| node_facts
node_ask -->|"checks output"| node_safety
node_ask -->|"requests answers"| node_aigateway
node_explain -->|"builds context"| node_facts
node_explain -->|"checks output"| node_safety
node_explain -->|"requests explanations"| node_aigateway
node_debrief -->|"builds context"| node_facts
node_debrief -->|"checks output"| node_safety
node_debrief -->|"requests debrief"| node_aigateway
node_simapp -.->|"uses voice"| node_speech
node_demoapp -->|"uses listening"| node_listen

click node_simapp "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/simulator/app.js"
click node_profile "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/shared/profile.js"
click node_marketdata "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/simulator/data.js"
click node_engine "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/simulator/engine.js"
click node_alerts "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/simulator/alerts.js"
click node_metrics "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/simulator/metrics.js"
click node_gate "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/shared/gate.js"
click node_reasoning "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/shared/reasoning.js"
click node_reasonapi "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/reason.js"
click node_facts "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/lib/facts.js"
click node_safety "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/lib/safety.js"
click node_aigateway "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/lib/ai.js"
click node_sarvam "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/lib/sarvam.js"
click node_coach "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/coach.js"
click node_report "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/report.js"
click node_lessons "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/shared/lessons.js"
click node_demoapp "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/demo-run/app.js"
click node_democontent "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/demo-run/content.js"
click node_demoengine "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/demo-run/engine.js"
click node_ask "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/ask.js"
click node_explain "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/explain.js"
click node_debrief "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/debrief.js"
click node_speech "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/tts.js"
click node_listen "https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/shared/listen.js"

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_simapp,node_marketdata,node_engine,node_alerts,node_metrics toneBlue
class node_demoapp,node_democontent,node_demoengine toneAmber
class node_reasonapi,node_facts,node_safety,node_aigateway,node_sarvam,node_coach,node_report,node_ask,node_explain,node_debrief,node_speech toneMint
class node_profile,node_gate,node_reasoning,node_lessons,node_listen toneRose
class node_player toneIndigo
```

## Components

### Market Simulator

- [Simulator UI](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/simulator/app.js): `public/simulator/app.js`
- [Market Data](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/simulator/data.js): `public/simulator/data.js`
- [Market Engine](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/simulator/engine.js): `public/simulator/engine.js`
- [Price Alerts](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/simulator/alerts.js): `public/simulator/alerts.js`
- [Behaviour Metrics](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/simulator/metrics.js): `public/simulator/metrics.js`

### Tip Demo

- [Demo UI](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/demo-run/app.js): `public/demo-run/app.js`
- [Demo Scenarios](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/demo-run/content.js): `public/demo-run/content.js`
- [Demo Story Engine](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/demo-run/engine.js): `public/demo-run/engine.js`

### AI Backend

- [Order Reason API](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/reason.js): `api/reason.js`
- [Facts Builder](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/lib/facts.js): `lib/facts.js`
- [AI Safety](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/lib/safety.js): `lib/safety.js`
- [AI Gateway](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/lib/ai.js): `lib/ai.js`
- [Sarvam Service](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/lib/sarvam.js): `lib/sarvam.js`
- [Coach API](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/coach.js): `api/coach.js`
- [Behaviour Report API](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/report.js): `api/report.js`
- [Q&A API](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/ask.js): `api/ask.js`
- [Explanation API](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/explain.js): `api/explain.js`
- [Debrief API](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/debrief.js): `api/debrief.js`
- [Speech APIs](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/api/tts.js): `api/tts.js`

### Shared Learning

- [Onboarding Profile](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/shared/profile.js): `public/shared/profile.js`
- [Reasoning Gate](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/shared/gate.js): `public/shared/gate.js`
- [Offline Reasoning](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/shared/reasoning.js): `public/shared/reasoning.js`
- [Lessons and Resources](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/shared/lessons.js): `public/shared/lessons.js`
- [Shared Listening](https://github.com/prakharyadav2006/niveshsetufinal/blob/main/public/shared/listen.js): `public/shared/listen.js`

### Other components

- **Player**

## Connections

- Player → Simulator UI: uses
- Simulator UI → Onboarding Profile: collects profile (evidence: `public/simulator/app.js`)
- Simulator UI → Market Data: reads market (evidence: `public/simulator/app.js`)
- Simulator UI → Market Engine: runs market (evidence: `public/simulator/app.js`)
- Simulator UI → Price Alerts: manages alerts (evidence: `public/simulator/app.js`)
- Simulator UI → Behaviour Metrics: computes habits (evidence: `public/simulator/app.js`)
- Simulator UI → Reasoning Gate: checks orders (evidence: `public/simulator/app.js`)
- Reasoning Gate → Order Reason API: requests verdict
- Reasoning Gate → Offline Reasoning: uses offline check (evidence: `public/shared/gate.js`)
- Order Reason API → Facts Builder: builds order facts (evidence: `api/reason.js`)
- Order Reason API → AI Safety: checks and limits (evidence: `api/reason.js`)
- Order Reason API → AI Gateway: requests judgment (evidence: `api/reason.js`)
- AI Gateway → Sarvam Service: calls model (evidence: `lib/ai.js`)
- Coach API → Facts Builder: builds context (evidence: `api/coach.js`)
- Coach API → AI Safety: checks output (evidence: `api/coach.js`)
- Coach API → AI Gateway: requests notes (evidence: `api/coach.js`)
- Behaviour Report API → AI Gateway: requests insights (evidence: `api/report.js`)
- Behaviour Report API → AI Safety: checks output (evidence: `api/report.js`)
- Simulator UI → Coach API: requests coaching
- Simulator UI → Behaviour Report API: requests report
- Simulator UI → Lessons and Resources: shows lessons (evidence: `public/simulator/app.js`)
- Player → Demo UI: uses demo
- Demo UI → Demo Scenarios: renders scenarios (evidence: `public/demo-run/app.js`)
- Demo UI → Demo Story Engine: runs story (evidence: `public/demo-run/app.js`)
- Demo UI → Debrief API: requests debrief (evidence: `public/demo-run/app.js`)
- Demo UI → Explanation API: requests explanations (evidence: `public/demo-run/app.js`)
- Demo UI → Q&A API: requests answers
- Q&A API → Facts Builder: builds context (evidence: `api/ask.js`)
- Q&A API → AI Safety: checks output (evidence: `api/ask.js`)
- Q&A API → AI Gateway: requests answers (evidence: `api/ask.js`)
- Explanation API → Facts Builder: builds context (evidence: `api/explain.js`)
- Explanation API → AI Safety: checks output (evidence: `api/explain.js`)
- Explanation API → AI Gateway: requests explanations (evidence: `api/explain.js`)
- Debrief API → Facts Builder: builds context (evidence: `api/debrief.js`)
- Debrief API → AI Safety: checks output (evidence: `api/debrief.js`)
- Debrief API → AI Gateway: requests debrief (evidence: `api/debrief.js`)
- Simulator UI → Speech APIs: uses voice
- Demo UI → Shared Listening: uses listening (evidence: `public/demo-run/app.js`)
