# kajjayamadithya/wavereach architecture

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

- Interactive diagram: https://gitdiagram.com/kajjayamadithya/wavereach
- Repository: https://github.com/kajjayamadithya/wavereach

## Overview

NxtWave’s product is a student workshop registration and growth platform. Students register through the portal; the backend validates the submission, records attribution and referral details, and returns a referral pass. Students can then track referrals and view the leaderboard, while campaign operators inspect analytics and export results. The React app also offers a strategy guide and seed/reset controls. The README documents Supabase with persistent local fallback. Some route and UI implementations were only partially sampled, so the graph omits uncertain internal links.

Main entry points: [`frontend/src/App.jsx`](https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/App.jsx) (App navigation), [`backend/app/database.py`](https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/database.py) (Persistence client), [`backend/app/routes/analytics.py`](https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/routes/analytics.py) (Analytics and export), [`frontend/src/api.js`](https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/api.js) (REST API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_react_root["React entry<br/>[main.jsx]"]
  node_app["App navigation<br/>[App.jsx]"]
  node_strategy["Strategy guide<br/>[StrategyGuide.jsx]"]
  node_navbar["Navigation and controls<br/>[Navbar.jsx]"]
end

subgraph group_growth["Registration and referrals"]
  node_registration_ui["Registration portal"]
  node_referral_ui["Referral tracker"]
  node_registration_api["Registration and referrals<br/>[registrations.py]"]
end

subgraph group_insights["Campaign analytics"]
  node_analytics_ui["Analytics dashboard"]
  node_analytics_api["Analytics and export<br/>[analytics.py]"]
  node_seed_generator["Seed generator<br/>[seed_data.py]"]
end

subgraph group_platform["API and persistence"]
  node_api_client["REST API client<br/>[api.js]"]
  node_api_entry["FastAPI application<br/>[main.py]"]
  node_schemas["Request and response schemas<br/>[models.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_data_layer["Persistence client<br/>[database.py]"]
  node_registration_store[("Registrations store<br/>[schema.sql]")]
end

node_student(("Student"))
node_operator(("Campaign operator"))
node_supabase[("Supabase")]

node_student -->|"opens portal"| node_react_root
node_operator -->|"opens dashboard"| node_react_root
node_react_root -->|"mounts"| node_app
node_app -->|"renders"| node_navbar
node_app -->|"renders"| node_registration_ui
node_app -->|"renders"| node_referral_ui
node_app -->|"renders"| node_analytics_ui
node_app -->|"renders"| node_strategy
node_app -->|"loads status"| node_api_client
node_registration_ui -->|"submits registration"| node_api_client
node_referral_ui -->|"fetches referral data"| node_api_client
node_analytics_ui -->|"fetches metrics"| node_api_client
node_api_client -->|"calls REST API"| node_api_entry
node_api_entry -->|"routes requests"| node_registration_api
node_api_entry -->|"routes requests"| node_analytics_api
node_registration_api -->|"validates and shapes"| node_schemas
node_analytics_api -->|"shapes metrics"| node_schemas
node_registration_api -->|"reads and writes"| node_data_layer
node_analytics_api -->|"reads and clears"| node_data_layer
node_analytics_api -->|"generates sample records"| node_seed_generator
node_api_entry -->|"checks health"| node_data_layer
node_data_layer -->|"loads connection config"| node_settings
node_data_layer -.->|"queries when configured"| node_supabase
node_data_layer -.->|"persists registration data"| node_registration_store
node_analytics_api -->|"exports CSV"| node_operator

click node_react_root "https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/main.jsx"
click node_app "https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/App.jsx"
click node_registration_ui "https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/components/RegistrationForm.jsx"
click node_referral_ui "https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/components/ReferralTracker.jsx"
click node_analytics_ui "https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/components/AnalyticsDashboard.jsx"
click node_strategy "https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/components/StrategyGuide.jsx"
click node_navbar "https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/components/Navbar.jsx"
click node_api_client "https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/api.js"
click node_api_entry "https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/main.py"
click node_registration_api "https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/routes/registrations.py"
click node_analytics_api "https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/routes/analytics.py"
click node_seed_generator "https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/routes/seed_data.py"
click node_schemas "https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/models.py"
click node_settings "https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/config.py"
click node_data_layer "https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/database.py"
click node_registration_store "https://github.com/kajjayamadithya/wavereach/blob/main/backend/schema.sql"

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_react_root,node_app,node_strategy,node_navbar toneBlue
class node_registration_ui,node_referral_ui,node_registration_api,node_supabase toneAmber
class node_analytics_ui,node_analytics_api,node_seed_generator toneMint
class node_api_client,node_api_entry,node_schemas,node_settings,node_data_layer,node_registration_store toneRose
class node_student,node_operator toneIndigo
```

## Components

### Web experience

- [React entry](https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [App navigation](https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Strategy guide](https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/components/StrategyGuide.jsx): `frontend/src/components/StrategyGuide.jsx`
- [Navigation and controls](https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/components/Navbar.jsx): `frontend/src/components/Navbar.jsx`

### Registration and referrals

- [Registration portal](https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/components/RegistrationForm.jsx): `frontend/src/components/RegistrationForm.jsx`
- [Referral tracker](https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/components/ReferralTracker.jsx): `frontend/src/components/ReferralTracker.jsx`
- [Registration and referrals](https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/routes/registrations.py): `backend/app/routes/registrations.py`

### Campaign analytics

- [Analytics dashboard](https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/components/AnalyticsDashboard.jsx): `frontend/src/components/AnalyticsDashboard.jsx`
- [Analytics and export](https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/routes/analytics.py): `backend/app/routes/analytics.py`
- [Seed generator](https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/routes/seed_data.py): `backend/app/routes/seed_data.py`

### API and persistence

- [REST API client](https://github.com/kajjayamadithya/wavereach/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [FastAPI application](https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/main.py): `backend/app/main.py`
- [Request and response schemas](https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/models.py): `backend/app/models.py`
- [Runtime settings](https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/config.py): `backend/app/config.py`
- [Persistence client](https://github.com/kajjayamadithya/wavereach/blob/main/backend/app/database.py): `backend/app/database.py`
- [Registrations store](https://github.com/kajjayamadithya/wavereach/blob/main/backend/schema.sql): `backend/schema.sql`

### Other components

- **Student**
- **Campaign operator**
- **Supabase**

## Connections

- Student → React entry: opens portal (evidence: `README.md`)
- Campaign operator → React entry: opens dashboard (evidence: `README.md`)
- React entry → App navigation: mounts (evidence: `frontend/src/main.jsx`)
- App navigation → Navigation and controls: renders (evidence: `frontend/src/App.jsx`)
- App navigation → Registration portal: renders (evidence: `frontend/src/App.jsx`)
- App navigation → Referral tracker: renders (evidence: `frontend/src/App.jsx`)
- App navigation → Analytics dashboard: renders (evidence: `frontend/src/App.jsx`)
- App navigation → Strategy guide: renders (evidence: `frontend/src/App.jsx`)
- App navigation → REST API client: loads status (evidence: `frontend/src/App.jsx`)
- Registration portal → REST API client: submits registration (evidence: `frontend/src/components/RegistrationForm.jsx`)
- Referral tracker → REST API client: fetches referral data (evidence: `frontend/src/components/ReferralTracker.jsx`)
- Analytics dashboard → REST API client: fetches metrics (evidence: `frontend/src/components/AnalyticsDashboard.jsx`)
- REST API client → FastAPI application: calls REST API (evidence: `README.md`)
- FastAPI application → Registration and referrals: routes requests (evidence: `backend/app/main.py`)
- FastAPI application → Analytics and export: routes requests (evidence: `backend/app/main.py`)
- Registration and referrals → Request and response schemas: validates and shapes (evidence: `backend/app/routes/registrations.py`)
- Analytics and export → Request and response schemas: shapes metrics (evidence: `backend/app/routes/analytics.py`)
- Registration and referrals → Persistence client: reads and writes (evidence: `backend/app/routes/registrations.py`)
- Analytics and export → Persistence client: reads and clears (evidence: `backend/app/routes/analytics.py`)
- Analytics and export → Seed generator: generates sample records (evidence: `backend/app/routes/analytics.py`)
- FastAPI application → Persistence client: checks health (evidence: `backend/app/main.py`)
- Persistence client → Runtime settings: loads connection config (evidence: `backend/app/database.py`)
- Persistence client → Supabase: queries when configured (evidence: `README.md`)
- Persistence client → Registrations store: persists registration data (evidence: `README.md`)
- Analytics and export → Campaign operator: exports CSV (evidence: `README.md`)