# bikramkh07/raktadaan architecture

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

- Interactive diagram: https://gitdiagram.com/bikramkh07/raktadaan
- Repository: https://github.com/bikramkh07/raktadaan

## Overview

1. **Repository shape**
   - This repo is primarily a **React + Vite frontend** for RaktaDaan Nepal, plus **SQL schema files** that define the backend data model.
   - The README describes a separate **Laravel API** as the intended server-side boundary; that backend is not present in this tree, so the repo is best understood as a **frontend client + database contract + backend API spec**.

2. **Top-level architecture**
   - `index.html`, `src/main.jsx`, and `src/App.jsx` form the app shell.
   - `App.jsx` is the central composition point: it likely controls route/page selection, shared state, and UI-wide concerns such as language and notifications.
   - `src/index.css` provides global styling for the whole app.

3. **Page-level boundaries**
   - `src/pages/` contains the major user-facing screens:
     - `HomePage` for landing/marketing and primary CTAs
     - `FindDonorsPage` for donor search and request discovery
     - `CreateRequestPage` for submitting a blood request
     - `RegisterPage` for donor/seeker onboarding
     - `DonorDashboard` for donor availability/profile management
     - `SeekerDashboard` for active requests and donor lists
     - `HeroesPage` for the public “Blood Heroes” wall
   - These pages are the main architectural units for diagramming user journeys.

4. **Reusable UI components**
   - `src/components/` holds shared presentation and interaction pieces:
     - `Navbar` for global navigation and language toggle
     - `RequestCard` for request status/fulfillment display
     - `HeroCard` for donor hero profiles
     - `NotifPanel` for slide-in notifications
     - `Toast` for transient feedback
     - `WaBanner` for WhatsApp-driven CTA/alerts
   - These are cross-page UI boundaries rather than business-logic containers.

5. **Data and mock-driven frontend state**
   - `src/data/mockData.js` and `src/data/hospitalsData.js` provide seed/reference data for the UI.
   - The README explicitly says mock data is a stand-in for API calls, so the current frontend is likely **API-ready but not yet API-wired**.
   - `src/config.js` probably centralizes runtime constants such as API base URL or feature toggles.

6. **Internationalization is a first-class concern**
   - `src/translations.js` stores the UI text for **English and Nepali**.
   - The language switch is surfaced in `Navbar`, and the README notes translation of province/district dropdowns and the use of the **Mukta** font.
   - For architecture diagrams, treat language selection as a **global UI state** affecting most pages/components.

7. **Map and location dependency**
   - `src/components/MapView.jsx` plus `src/hooks/useGoogleMaps.js` indicate a dedicated **Google Maps integration layer**.
   - This is likely used to visualize hospitals, donor proximity, or request locations.
   - Location is also central to matching logic described in the README, which uses GPS distance filtering on the backend.

8. **Frontend-to-backend contract**
   - The README defines the API boundary around Laravel routes such as `/api/auth/*`, `/api/donors`, `/api/requests`, `/api/heroes`, and `/api/notifications`.
   - The frontend is expected to consume these endpoints for auth, donor discovery, request creation, fulfillment updates, and notification retrieval.
   - `src` contains the consumer-facing UI; the actual business rules are intended to live server-side.

9. **Database subsystems**
   - The `database/` folder contains three SQL modules:
     - `auth.sql` for users, OTP, and Sanctum tokens
     - `blood_requests.sql` for requests, fulfillments, and ratings
     - `notifications.sql` for notification logs and WhatsApp queueing
   - This split suggests three logical domains: **identity/authentication**, **request lifecycle**, and **messaging/notifications**.

10. **External service integration**
   - The architecture depends materially on two external services:
     - **Laravel Sanctum** for token-based API authentication
     - **Meta WhatsApp Business Cloud API** for OTPs and blood-match/life-saved notifications
   - Google Maps is the other major third-party dependency, used for location-aware donor matching and map display.

11. **Core data flows**
   - **Registration flow:** `RegisterPage` collects user data, then the backend validates identity/OTP and stores a donor or seeker profile in `auth`-related tables.
   - **Donor matching flow:** seekers create requests, the backend filters donors by blood group and proximity, and notifications/WhatsApp alerts are sent.
   - **Fulfillment flow:** donors accept requests; seekers later mark blood as received; this updates request status and may trigger a thank-you notification.
   - **Visibility flow:** fulfilled requests feed the public `HeroesPage`, which acts as a read-only achievements wall.

12. **Behavioral boundaries worth drawing**
   - **Public vs authenticated areas:** landing, heroes, and discovery pages are public-facing; dashboards and request actions are authenticated.
   - **Client UI vs server rules:** the frontend handles presentation and user interactions, while eligibility rules, throttling, OTP expiry, and availability checks are explicitly server-enforced.
   - **Notification rendering vs delivery:** `NotifPanel`/`Toast` are UI surfaces; actual WhatsApp delivery is a backend integration.

13. **What to show in an architecture diagram**
   - Place the **React frontend** as the presentation layer, with pages branching into shared components and data hooks.
   - Show a separate **Laravel API** boundary for auth, donors, requests, heroes, and notifications.
   - Under the backend, include the three SQL schema areas and the external integrations to **MySQL**, **WhatsApp Cloud API**, and **Google Maps**.

Main entry points: [`src/App.jsx`](https://github.com/bikramkh07/raktadaan/blob/main/src/App.jsx) (App), [`src/components/MapView.jsx`](https://github.com/bikramkh07/raktadaan/blob/main/src/components/MapView.jsx) (MapView), [`src/pages/FindDonorsPage.jsx`](https://github.com/bikramkh07/raktadaan/blob/main/src/pages/FindDonorsPage.jsx) (Find Donors), [`src/main.jsx`](https://github.com/bikramkh07/raktadaan/blob/main/src/main.jsx) (main.jsx)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_index_html["index.html<br/>app shell<br/>[index.html]"]
  node_main_jsx["main.jsx<br/>bootstrap<br/>[main.jsx]"]
  node_app_jsx["App<br/>shell/router<br/>[App.jsx]"]
  node_global_css["Global CSS<br/>styles<br/>[index.css]"]
  node_navbar["Navbar<br/>shared ui<br/>[Navbar.jsx]"]
  node_notif_panel["NotifPanel<br/>shared ui<br/>[NotifPanel.jsx]"]
  node_toast["Toast<br/>shared ui<br/>[Toast.jsx]"]
  node_wa_banner["WaBanner<br/>shared ui<br/>[WaBanner.jsx]"]
  node_request_card["RequestCard<br/>shared ui<br/>[RequestCard.jsx]"]
  node_hero_card["HeroCard<br/>shared ui<br/>[HeroCard.jsx]"]
  node_map_view["MapView<br/>map widget<br/>[MapView.jsx]"]
  node_google_hook["useGoogleMaps<br/>hook<br/>[useGoogleMaps.js]"]
  node_translations["Translations<br/>i18n<br/>[translations.js]"]
  node_config["Config<br/>[config.js]"]
  node_mock_data["Mock Data<br/>seed data<br/>[mockData.js]"]
  node_hospitals_data["Hospitals Data<br/>reference data<br/>[hospitalsData.js]"]
  node_home_page["HomePage<br/>public page<br/>[HomePage.jsx]"]
  node_find_donors_page["Find Donors<br/>public page<br/>[FindDonorsPage.jsx]"]
  node_find_blood_page["Find Blood<br/>public page<br/>[FindBloodPage.jsx]"]
  node_create_request_page["Create Request<br/>authenticated page"]
  node_register_page["Register<br/>public page<br/>[RegisterPage.jsx]"]
  node_donor_dashboard["Donor Dashboard<br/>authenticated page<br/>[DonorDashboard.jsx]"]
  node_seeker_dashboard["Seeker Dashboard<br/>authenticated page"]
  node_heroes_page["Heroes Page<br/>public page<br/>[HeroesPage.jsx]"]
end

subgraph group_api["Laravel API boundary"]
  node_api_auth[("Auth API<br/>backend module")]
  node_api_donors[("Donors API<br/>backend module")]
  node_api_requests[("Requests API<br/>backend module")]
  node_api_heroes[("Heroes API<br/>backend module")]
  node_api_notifications[("Notifications API<br/>backend module")]
end

subgraph group_storage["Database schemas"]
  node_auth_sql["auth.sql<br/>schema<br/>[auth.sql]"]
  node_blood_requests_sql["blood_requests.sql<br/>schema<br/>[blood_requests.sql]"]
  node_notifications_sql["notifications.sql<br/>schema<br/>[notifications.sql]"]
end

subgraph group_external["External services"]
  node_mysql[("MySQL<br/>database")]
  node_whatsapp_api["WhatsApp Cloud API<br/>messaging service"]
end

node_index_html -->|"loads"| node_main_jsx
node_main_jsx -->|"mounts"| node_app_jsx
node_app_jsx -->|"styles"| node_global_css
node_app_jsx -->|"shares"| node_navbar
node_app_jsx -->|"shares"| node_notif_panel
node_app_jsx -->|"shares"| node_toast
node_app_jsx -->|"shares"| node_wa_banner
node_app_jsx -->|"uses"| node_translations
node_app_jsx -->|"uses"| node_config
node_app_jsx -->|"routes to"| node_home_page
node_app_jsx -->|"routes to"| node_find_donors_page
node_app_jsx -->|"routes to"| node_find_blood_page
node_app_jsx -->|"routes to"| node_create_request_page
node_app_jsx -->|"routes to"| node_register_page
node_app_jsx -->|"routes to"| node_donor_dashboard
node_app_jsx -->|"routes to"| node_seeker_dashboard
node_app_jsx -->|"routes to"| node_heroes_page
node_home_page -->|"reads"| node_mock_data
node_find_donors_page -->|"renders"| node_request_card
node_find_donors_page -->|"maps"| node_map_view
node_create_request_page -->|"uses"| node_hospitals_data
node_register_page -->|"submits to"| node_api_auth
node_donor_dashboard -->|"updates"| node_api_donors
node_seeker_dashboard -->|"manages"| node_api_requests
node_heroes_page -->|"reads"| node_api_heroes
node_app_jsx -->|"consumes"| node_api_notifications
node_api_auth -->|"persists"| node_auth_sql
node_api_requests -->|"persists"| node_blood_requests_sql
node_api_notifications -->|"persists"| node_notifications_sql
node_auth_sql -->|"runs on"| node_mysql
node_blood_requests_sql -->|"runs on"| node_mysql
node_notifications_sql -->|"runs on"| node_mysql
node_api_auth -->|"sends OTPs"| node_whatsapp_api
node_api_notifications -->|"delivers alerts"| node_whatsapp_api
node_google_hook -->|"powers"| node_map_view
node_map_view -->|"supports"| node_api_donors
node_map_view -->|"renders"| node_hospitals_data

click node_index_html "https://github.com/bikramkh07/raktadaan/blob/main/index.html"
click node_main_jsx "https://github.com/bikramkh07/raktadaan/blob/main/src/main.jsx"
click node_app_jsx "https://github.com/bikramkh07/raktadaan/blob/main/src/App.jsx"
click node_global_css "https://github.com/bikramkh07/raktadaan/blob/main/src/index.css"
click node_navbar "https://github.com/bikramkh07/raktadaan/blob/main/src/components/Navbar.jsx"
click node_notif_panel "https://github.com/bikramkh07/raktadaan/blob/main/src/components/NotifPanel.jsx"
click node_toast "https://github.com/bikramkh07/raktadaan/blob/main/src/components/Toast.jsx"
click node_wa_banner "https://github.com/bikramkh07/raktadaan/blob/main/src/components/WaBanner.jsx"
click node_request_card "https://github.com/bikramkh07/raktadaan/blob/main/src/components/RequestCard.jsx"
click node_hero_card "https://github.com/bikramkh07/raktadaan/blob/main/src/components/HeroCard.jsx"
click node_map_view "https://github.com/bikramkh07/raktadaan/blob/main/src/components/MapView.jsx"
click node_google_hook "https://github.com/bikramkh07/raktadaan/blob/main/src/hooks/useGoogleMaps.js"
click node_translations "https://github.com/bikramkh07/raktadaan/blob/main/src/translations.js"
click node_config "https://github.com/bikramkh07/raktadaan/blob/main/src/config.js"
click node_mock_data "https://github.com/bikramkh07/raktadaan/blob/main/src/data/mockData.js"
click node_hospitals_data "https://github.com/bikramkh07/raktadaan/blob/main/src/data/hospitalsData.js"
click node_home_page "https://github.com/bikramkh07/raktadaan/blob/main/src/pages/HomePage.jsx"
click node_find_donors_page "https://github.com/bikramkh07/raktadaan/blob/main/src/pages/FindDonorsPage.jsx"
click node_find_blood_page "https://github.com/bikramkh07/raktadaan/blob/main/src/pages/FindBloodPage.jsx"
click node_create_request_page "https://github.com/bikramkh07/raktadaan/blob/main/src/pages/CreateRequestPage.jsx"
click node_register_page "https://github.com/bikramkh07/raktadaan/blob/main/src/pages/RegisterPage.jsx"
click node_donor_dashboard "https://github.com/bikramkh07/raktadaan/blob/main/src/pages/DonorDashboard.jsx"
click node_seeker_dashboard "https://github.com/bikramkh07/raktadaan/blob/main/src/pages/SeekerDashboard.jsx"
click node_heroes_page "https://github.com/bikramkh07/raktadaan/blob/main/src/pages/HeroesPage.jsx"
click node_auth_sql "https://github.com/bikramkh07/raktadaan/blob/main/database/auth.sql"
click node_blood_requests_sql "https://github.com/bikramkh07/raktadaan/blob/main/database/blood_requests.sql"
click node_notifications_sql "https://github.com/bikramkh07/raktadaan/blob/main/database/notifications.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_index_html,node_main_jsx,node_app_jsx,node_global_css,node_navbar,node_notif_panel,node_toast,node_wa_banner,node_request_card,node_hero_card,node_map_view,node_google_hook,node_translations,node_config,node_mock_data,node_hospitals_data,node_home_page,node_find_donors_page,node_find_blood_page,node_create_request_page,node_register_page,node_donor_dashboard,node_seeker_dashboard,node_heroes_page toneBlue
class node_api_auth,node_api_donors,node_api_requests,node_api_heroes,node_api_notifications toneAmber
class node_auth_sql,node_blood_requests_sql,node_notifications_sql toneMint
class node_mysql,node_whatsapp_api toneRose
```

## Components

### React frontend

Vite app shell, pages, shared components, and client-side state.

- [index.html](https://github.com/bikramkh07/raktadaan/blob/main/index.html): app shell · HTML entry point for the Vite app. · `index.html`
- [main.jsx](https://github.com/bikramkh07/raktadaan/blob/main/src/main.jsx): bootstrap · Mounts the React application. · `src/main.jsx`
- [App](https://github.com/bikramkh07/raktadaan/blob/main/src/App.jsx): shell/router · Central composition point for app-wide state and screen selection. · `src/App.jsx`
- [Global CSS](https://github.com/bikramkh07/raktadaan/blob/main/src/index.css): styles · Application-wide styling. · `src/index.css`
- [Navbar](https://github.com/bikramkh07/raktadaan/blob/main/src/components/Navbar.jsx): shared ui · Global navigation and language toggle. · `src/components/Navbar.jsx`
- [NotifPanel](https://github.com/bikramkh07/raktadaan/blob/main/src/components/NotifPanel.jsx): shared ui · Slide-in notification surface. · `src/components/NotifPanel.jsx`
- [Toast](https://github.com/bikramkh07/raktadaan/blob/main/src/components/Toast.jsx): shared ui · Transient feedback messages. · `src/components/Toast.jsx`
- [WaBanner](https://github.com/bikramkh07/raktadaan/blob/main/src/components/WaBanner.jsx): shared ui · WhatsApp-focused call-to-action and alerts. · `src/components/WaBanner.jsx`
- [RequestCard](https://github.com/bikramkh07/raktadaan/blob/main/src/components/RequestCard.jsx): shared ui · Request status and fulfillment card. · `src/components/RequestCard.jsx`
- [HeroCard](https://github.com/bikramkh07/raktadaan/blob/main/src/components/HeroCard.jsx): shared ui · Public donor hero profile card. · `src/components/HeroCard.jsx`
- [MapView](https://github.com/bikramkh07/raktadaan/blob/main/src/components/MapView.jsx): map widget · Google Maps-backed location display. · `src/components/MapView.jsx`
- [useGoogleMaps](https://github.com/bikramkh07/raktadaan/blob/main/src/hooks/useGoogleMaps.js): hook · Loads and manages Google Maps integration. · `src/hooks/useGoogleMaps.js`
- [Translations](https://github.com/bikramkh07/raktadaan/blob/main/src/translations.js): i18n · English and Nepali UI text resources. · `src/translations.js`
- [Config](https://github.com/bikramkh07/raktadaan/blob/main/src/config.js): runtime config · Client runtime constants and API settings. · `src/config.js`
- [Mock Data](https://github.com/bikramkh07/raktadaan/blob/main/src/data/mockData.js): seed data · Frontend stand-in for API responses. · `src/data/mockData.js`
- [Hospitals Data](https://github.com/bikramkh07/raktadaan/blob/main/src/data/hospitalsData.js): reference data · Hospital/location reference data for the UI. · `src/data/hospitalsData.js`
- [HomePage](https://github.com/bikramkh07/raktadaan/blob/main/src/pages/HomePage.jsx): public page · Landing page and primary calls to action. · `src/pages/HomePage.jsx`
- [Find Donors](https://github.com/bikramkh07/raktadaan/blob/main/src/pages/FindDonorsPage.jsx): public page · Donor search and request discovery screen. · `src/pages/FindDonorsPage.jsx`
- [Find Blood](https://github.com/bikramkh07/raktadaan/blob/main/src/pages/FindBloodPage.jsx): public page · Blood lookup and search-oriented screen. · `src/pages/FindBloodPage.jsx`
- [Create Request](https://github.com/bikramkh07/raktadaan/blob/main/src/pages/CreateRequestPage.jsx): authenticated page · Blood request submission flow. · `src/pages/CreateRequestPage.jsx`
- [Register](https://github.com/bikramkh07/raktadaan/blob/main/src/pages/RegisterPage.jsx): public page · Donor and seeker onboarding. · `src/pages/RegisterPage.jsx`
- [Donor Dashboard](https://github.com/bikramkh07/raktadaan/blob/main/src/pages/DonorDashboard.jsx): authenticated page · Donor availability and profile management. · `src/pages/DonorDashboard.jsx`
- [Seeker Dashboard](https://github.com/bikramkh07/raktadaan/blob/main/src/pages/SeekerDashboard.jsx): authenticated page · Active requests and donor list management. · `src/pages/SeekerDashboard.jsx`
- [Heroes Page](https://github.com/bikramkh07/raktadaan/blob/main/src/pages/HeroesPage.jsx): public page · Read-only wall of fulfilled blood heroes. · `src/pages/HeroesPage.jsx`

### Laravel API boundary

Backend contract described in README; not present in the repository tree.

- **Auth API**: backend module · Authentication, OTP, and token issuance boundary.
- **Donors API**: backend module · Donor profiles, availability, and matching endpoints.
- **Requests API**: backend module · Blood request lifecycle and fulfillment endpoints.
- **Heroes API**: backend module · Public achievement/feed endpoints for fulfilled requests.
- **Notifications API**: backend module · Notification retrieval and delivery coordination.

### Database schemas

SQL modules defining the backend data model.

- [auth.sql](https://github.com/bikramkh07/raktadaan/blob/main/database/auth.sql): schema · Users, OTP, and Sanctum token tables. · `database/auth.sql`
- [blood_requests.sql](https://github.com/bikramkh07/raktadaan/blob/main/database/blood_requests.sql): schema · Requests, fulfillments, and ratings tables. · `database/blood_requests.sql`
- [notifications.sql](https://github.com/bikramkh07/raktadaan/blob/main/database/notifications.sql): schema · Notification logs and WhatsApp queue tables. · `database/notifications.sql`

### External services

Third-party services used by the system.

- **MySQL**: database · Primary relational store implied by the SQL schemas.
- **WhatsApp Cloud API**: messaging service · Used for OTP and blood-match notifications.

## Connections

- index.html → main.jsx: loads · HTML entry bootstraps the React runtime.
- main.jsx → App: mounts · Application root renders the main composition shell.
- App → Global CSS: styles · Global styles affect the whole app.
- App → Navbar: shares · Top-level navigation is used across screens.
- App → NotifPanel: shares · Global notification surface.
- App → Toast: shares · Transient feedback used by multiple flows.
- App → WaBanner: shares · WhatsApp CTA/banner is app-wide.
- App → Translations: uses · Language state feeds translated UI text.
- App → Config: uses · Reads runtime configuration such as API base settings.
- App → HomePage: routes to · Landing experience.
- App → Find Donors: routes to · Donor discovery flow.
- App → Find Blood: routes to · Blood search flow.
- App → Create Request: routes to · Request submission flow.
- App → Register: routes to · Onboarding flow.
- App → Donor Dashboard: routes to · Authenticated donor area.
- App → Seeker Dashboard: routes to · Authenticated seeker area.
- App → Heroes Page: routes to · Public hero wall.
- HomePage → Mock Data: reads · Landing content and samples use seed data.
- Find Donors → RequestCard: renders · Shows request and donor discovery cards.
- Find Donors → MapView: maps · Displays nearby donors or hospitals on a map.
- Create Request → Hospitals Data: uses · Hospital options and location references.
- Register → Auth API: submits to · Registration and OTP verification flow.
- Donor Dashboard → Donors API: updates · Availability and profile management.
- Seeker Dashboard → Requests API: manages · Creates and tracks requests.
- Heroes Page → Heroes API: reads · Loads fulfilled requests for the public wall.
- App → Notifications API: consumes · Notification retrieval and alert state.
- Auth API → auth.sql: persists · Auth records and tokens are stored in schema tables.
- Requests API → blood_requests.sql: persists · Request lifecycle data is stored here.
- Notifications API → notifications.sql: persists · Notification events and queues are stored here.
- auth.sql → MySQL: runs on · Schemas are implemented in MySQL.
- blood_requests.sql → MySQL: runs on · Schemas are implemented in MySQL.
- notifications.sql → MySQL: runs on · Schemas are implemented in MySQL.
- Auth API → WhatsApp Cloud API: sends OTPs · OTP delivery is delegated to WhatsApp.
- Notifications API → WhatsApp Cloud API: delivers alerts · Match and thank-you notifications use WhatsApp.
- useGoogleMaps → MapView: powers · Hook manages map loading and usage.
- MapView → Donors API: supports · Map visualization complements location-aware donor discovery.
- MapView → Hospitals Data: renders · Reference locations can be shown on the map.
