# lakshan2906/nexusaid---project architecture

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

- Interactive diagram: https://gitdiagram.com/lakshan2906/nexusaid---project
- Repository: https://github.com/lakshan2906/nexusaid---project

## Overview

1. **Overall system shape**
   - NexusAid is a **single-page React application** with a thin client-side architecture.
   - There is **no custom server code** in the repo; the main runtime boundaries are the browser UI, Firebase services, and the external Gemini API.
   - The repo also contains a built `dist/` bundle, confirming it is deployed as a static web app.

2. **Application bootstrap**
   - `src/main.tsx` is the entry point and mounts `App.tsx`.
   - `App.tsx` is the top-level composition layer that likely coordinates the main experience and switches between the three role-specific views.

3. **Role-based UI partitioning**
   - The main user-facing boundary is split into:
     - `VictimView.tsx` for emergency request submission,
     - `NgoView.tsx` for response/coordination,
     - `DeveloperView.tsx` for oversight, analytics, or system administration.
   - This suggests a **single app with multiple operational consoles**, not separate apps.

4. **Emergency intake and AI processing**
   - The core workflow starts in the victim-facing view where unstructured distress text is entered.
   - `src/services/geminiService.ts` is the AI boundary: it sends that raw text to **Google Gemini** and converts it into structured emergency data.
   - The README’s example output shows the AI extracting fields such as resources, people count, injured count, urgency, category, and a recommended NGO.

5. **Shared state and persistence**
   - `src/lib/firebase.ts` is the Firebase initialization layer.
   - `src/lib/firestoreUtils.ts` likely wraps Firestore reads/writes used by all views.
   - Firestore is the main shared datastore for requests and response coordination, enabling the NGO and developer views to see the same operational data.

6. **Security boundary**
   - `firestore.rules` is the main enforcement point for data access control.
   - `security_spec.md` indicates the repo includes an explicit security model/documentation layer, which is important because the app handles emergency and potentially sensitive data.
   - If Firebase Auth is used, it would be configured through `firebase.ts`, but there is no separate backend auth service in the tree.

7. **Mapping and routing subsystem**
   - `src/components/RoutingMachine.tsx` is a dedicated geospatial component.
   - The README and tech stack indicate **Leaflet / React-Leaflet / Leaflet Routing Machine** are used to visualize and compute relief routes between NGO resources and victims.
   - This subsystem is likely embedded in operational dashboards rather than being a standalone feature.

8. **Location acquisition**
   - `src/services/locationService.ts` is the boundary for browser/location input.
   - It likely abstracts geolocation access and converts the device position into coordinates used by the mapping and routing layer.
   - This is a separate concern from AI parsing: one service interprets text, the other gets physical location.

9. **Frontend structure and styling**
   - `src/index.css` contains global styling; the app is a client-rendered UI.
   - The presence of a Vite config and TypeScript config indicates a modern frontend build pipeline, but they do not introduce server-side runtime layers.
   - The screenshots and README imply a dashboard-style UX with role-specific operational screens.

10. **Deployment and hosting**
   - `firebase.json`, `.firebaserc`, and the presence of `dist/` show the app is deployed through **Firebase Hosting**.
   - The hosting layer serves the static SPA, while Firestore provides the shared backend data plane.
   - Any real-time behavior comes from client-to-Firestore updates rather than a custom API server in this repository.

11. **Key data flow to show in an architecture diagram**
   - Victim input → `VictimView` → `geminiService` → structured emergency payload → Firestore.
   - NGO dashboard → Firestore subscription/read path → prioritized request list and coordination state.
   - Location service → mapping/routing component → route visualization for response planning.
   - Developer view → Firestore/aggregated app data for oversight.

12. **Important architectural note**
   - The product vision emphasizes low-connectivity and decentralized disaster response, but the code surface in this repo is primarily a **Firebase-backed web client**.
   - So the most accurate diagram should center on **browser SPA + Gemini API + Firestore + Firebase Hosting**, with offline/decentralized behavior treated as a goal unless additional implementation exists outside this tree.

Main entry points: [`src/lib/firestoreUtils.ts`](https://github.com/lakshan2906/nexusaid---project/blob/main/src/lib/firestoreUtils.ts) (Firestore utils), [`src/App.tsx`](https://github.com/lakshan2906/nexusaid---project/blob/main/src/App.tsx) (App shell), [`src/views/VictimView.tsx`](https://github.com/lakshan2906/nexusaid---project/blob/main/src/views/VictimView.tsx) (Victim view), [`src/services/geminiService.ts`](https://github.com/lakshan2906/nexusaid---project/blob/main/src/services/geminiService.ts) (Gemini service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Browser SPA"]
  node_node_main["Entry point<br/>bootstrap<br/>[main.tsx]"]
  node_node_app["App shell<br/>composition<br/>[App.tsx]"]
  node_node_victim["Victim view<br/>intake console<br/>[VictimView.tsx]"]
  node_node_ngo["NGO view<br/>response console<br/>[NgoView.tsx]"]
  node_node_dev["Developer view<br/>oversight console<br/>[DeveloperView.tsx]"]
  node_node_location["Location service<br/>geolocation<br/>[locationService.ts]"]
  node_node_routing["Routing machine<br/>mapping<br/>[RoutingMachine.tsx]"]
  node_node_gemini["Gemini service<br/>ai parser<br/>[geminiService.ts]"]
  node_node_firestore_utils["Firestore utils<br/>data access<br/>[firestoreUtils.ts]"]
end

subgraph group_group_services["External Services"]
  node_node_firebase["Firebase init<br/>cloud client<br/>[firebase.ts]"]
  node_node_firestore[("Firestore<br/>shared datastore")]
  node_node_gemini_api(("Gemini API<br/>external ai"))
end

subgraph group_group_delivery["Delivery & Security"]
  node_node_hosting["Firebase Hosting<br/>static hosting<br/>[firebase.json]"]
  node_node_rules["Firestore rules<br/>security policy<br/>[firestore.rules]"]
  node_node_security["Security spec<br/>security docs<br/>[security_spec.md]"]
  node_node_dist["Built app<br/>deploy artifact<br/>[index.html]"]
end

node_node_hosting -->|"serves"| node_node_dist
node_node_main -->|"boots"| node_node_app
node_node_app -->|"shows"| node_node_victim
node_node_app -->|"shows"| node_node_ngo
node_node_app -->|"shows"| node_node_dev
node_node_victim -->|"parses"| node_node_gemini
node_node_gemini -->|"calls"| node_node_gemini_api
node_node_victim -->|"requests"| node_node_location
node_node_location -->|"feeds"| node_node_routing
node_node_routing -->|"embeds"| node_node_ngo
node_node_gemini -->|"writes"| node_node_firestore_utils
node_node_firestore_utils -->|"uses"| node_node_firebase
node_node_firebase -->|"connects"| node_node_firestore
node_node_firestore_utils -->|"reads/writes"| node_node_firestore
node_node_ngo -->|"reads"| node_node_firestore_utils
node_node_dev -->|"reads"| node_node_firestore_utils
node_node_rules -->|"guards"| node_node_firestore
node_node_security -->|"documents"| node_node_rules

click node_node_main "https://github.com/lakshan2906/nexusaid---project/blob/main/src/main.tsx"
click node_node_app "https://github.com/lakshan2906/nexusaid---project/blob/main/src/App.tsx"
click node_node_victim "https://github.com/lakshan2906/nexusaid---project/blob/main/src/views/VictimView.tsx"
click node_node_ngo "https://github.com/lakshan2906/nexusaid---project/blob/main/src/views/NgoView.tsx"
click node_node_dev "https://github.com/lakshan2906/nexusaid---project/blob/main/src/views/DeveloperView.tsx"
click node_node_location "https://github.com/lakshan2906/nexusaid---project/blob/main/src/services/locationService.ts"
click node_node_routing "https://github.com/lakshan2906/nexusaid---project/blob/main/src/components/RoutingMachine.tsx"
click node_node_gemini "https://github.com/lakshan2906/nexusaid---project/blob/main/src/services/geminiService.ts"
click node_node_firestore_utils "https://github.com/lakshan2906/nexusaid---project/blob/main/src/lib/firestoreUtils.ts"
click node_node_firebase "https://github.com/lakshan2906/nexusaid---project/blob/main/src/lib/firebase.ts"
click node_node_hosting "https://github.com/lakshan2906/nexusaid---project/blob/main/firebase.json"
click node_node_rules "https://github.com/lakshan2906/nexusaid---project/blob/main/firestore.rules"
click node_node_security "https://github.com/lakshan2906/nexusaid---project/blob/main/security_spec.md"
click node_node_dist "https://github.com/lakshan2906/nexusaid---project/blob/main/dist/index.html"

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_node_main,node_node_app,node_node_victim,node_node_ngo,node_node_dev,node_node_location,node_node_routing,node_node_gemini,node_node_firestore_utils toneBlue
class node_node_firebase,node_node_firestore,node_node_gemini_api toneAmber
class node_node_hosting,node_node_rules,node_node_security,node_node_dist toneMint
```

## Components

### Browser SPA

Client-side React application and UI consoles.

- [Entry point](https://github.com/lakshan2906/nexusaid---project/blob/main/src/main.tsx): bootstrap · Mounts the React application. · `src/main.tsx`
- [App shell](https://github.com/lakshan2906/nexusaid---project/blob/main/src/App.tsx): composition · Top-level UI composition and role switching. · `src/App.tsx`
- [Victim view](https://github.com/lakshan2906/nexusaid---project/blob/main/src/views/VictimView.tsx): intake console · Collects emergency requests from affected users. · `src/views/VictimView.tsx`
- [NGO view](https://github.com/lakshan2906/nexusaid---project/blob/main/src/views/NgoView.tsx): response console · Coordinates response, prioritization, and operations. · `src/views/NgoView.tsx`
- [Developer view](https://github.com/lakshan2906/nexusaid---project/blob/main/src/views/DeveloperView.tsx): oversight console · Provides system visibility and administrative oversight. · `src/views/DeveloperView.tsx`
- [Location service](https://github.com/lakshan2906/nexusaid---project/blob/main/src/services/locationService.ts): geolocation · Reads browser/device location for response workflows. · `src/services/locationService.ts`
- [Routing machine](https://github.com/lakshan2906/nexusaid---project/blob/main/src/components/RoutingMachine.tsx): mapping · Renders and computes relief routes on the map. · `src/components/RoutingMachine.tsx`
- [Gemini service](https://github.com/lakshan2906/nexusaid---project/blob/main/src/services/geminiService.ts): ai parser · Transforms distress text into structured emergency data. · `src/services/geminiService.ts`
- [Firestore utils](https://github.com/lakshan2906/nexusaid---project/blob/main/src/lib/firestoreUtils.ts): data access · Shared reads and writes against the operational datastore. · `src/lib/firestoreUtils.ts`

### External Services

Third-party APIs and shared cloud data services used by the app.

- [Firebase init](https://github.com/lakshan2906/nexusaid---project/blob/main/src/lib/firebase.ts): cloud client · Initializes Firebase client services used by the SPA. · `src/lib/firebase.ts`
- **Firestore**: shared datastore · Primary store for requests, coordination state, and views.
- **Gemini API**: external ai · External model endpoint used for emergency text structuring.

### Delivery & Security

Static hosting, build artifacts, and access control boundaries.

- [Firebase Hosting](https://github.com/lakshan2906/nexusaid---project/blob/main/firebase.json): static hosting · Serves the built single-page app. · `firebase.json`
- [Firestore rules](https://github.com/lakshan2906/nexusaid---project/blob/main/firestore.rules): security policy · Enforces data access control for the shared datastore. · `firestore.rules`
- [Security spec](https://github.com/lakshan2906/nexusaid---project/blob/main/security_spec.md): security docs · Documents the app's security model and constraints. · `security_spec.md`
- [Built app](https://github.com/lakshan2906/nexusaid---project/blob/main/dist/index.html): deploy artifact · Compiled static bundle deployed as the hosted SPA. · `dist/index.html`

## Connections

- Firebase Hosting → Built app: serves · Hosting delivers the compiled web app.
- Entry point → App shell: boots · Entry point mounts the root application shell.
- App shell → Victim view: shows · App shell routes to the victim-facing workflow.
- App shell → NGO view: shows · App shell routes to the NGO operations view.
- App shell → Developer view: shows · App shell routes to the developer oversight view.
- Victim view → Gemini service: parses · Emergency text is structured through the AI boundary.
- Gemini service → Gemini API: calls · Service forwards text to the external Gemini endpoint.
- Victim view → Location service: requests · Victim workflow can capture device location.
- Location service → Routing machine: feeds · Coordinates support route visualization and planning.
- Routing machine → NGO view: embeds · Routing UI is used inside operational response screens.
- Gemini service → Firestore utils: writes · Structured emergency payloads are persisted through shared data access.
- Firestore utils → Firebase init: uses · Data access layer relies on Firebase client initialization.
- Firebase init → Firestore: connects · Firebase client reaches the shared Firestore backend.
- Firestore utils → Firestore: reads/writes · Operational data is stored and retrieved from Firestore.
- NGO view → Firestore utils: reads · NGO dashboard consumes shared request and coordination data.
- Developer view → Firestore utils: reads · Developer view uses the same operational datastore for oversight.
- Firestore rules → Firestore: guards · Security rules constrain access to Firestore data.
- Security spec → Firestore rules: documents · Security documentation describes the access model.