Skip to content

CORE_LOGIC.md

Latest commit

 

History

History
199 lines (166 loc) · 7 KB

CORE_LOGIC.md

File metadata and controls

199 lines (166 loc) · 7 KB

🧬 Core Logic & Emergency Pipelines

Core pipelines, process flows, and operational fundamentals for LifeLine+.

🚨 Emergency Pipeline

flowchart TD
    A["User taps Emergency"] --> B["Check Firebase/local session"]
    B -->|No session| C["Open LoginModal"]
    C --> D["Google auth or email fallback"]
    B -->|Session exists| E["Read navigator.geolocation"]
    D --> E
    E --> F["GET /api/nearest-services type=hospital"]
    F --> G["Distance-first rank + 20km radius fallback"]
    G --> H["Pick nearest hospital"]
    H --> I["Rank Directions routes by traffic ETA"]
    I --> J["Render route cards + map polylines"]
    J --> K["Find nearby ambulances"]
    K --> L["POST /api/ambulance-request/request"]
    L --> M["Socket.io tracking"]
Loading

🚑 Ambulance Booking Logic

sequenceDiagram
    actor User
    participant FE as React Emergency Page
    participant BE as Express Ambulance Route
    participant WS as Socket.io
    participant Store as Memory + Firestore optional

    User->>FE: Select ambulance
    FE->>BE: POST /api/ambulance-request/request
    BE->>Store: Save request as searching
    BE->>WS: Emit new_ambulance_request to ambulance rooms
    BE-->>FE: Return requestId + 5-minute window
    FE->>WS: join_request(requestId)
    BE->>BE: Wait production window or dev simulation timeout
    BE->>Store: Mark accepted + assignedAmbulance
    BE->>WS: ambulance_assigned
    loop Every 3 seconds
        BE->>WS: location_update
        WS-->>FE: Move ambulance marker
    end
    BE->>WS: ambulance_arrived
Loading

🗺️ Route Ranking Logic

flowchart LR
    A["origin + destination"] --> B["Directions API alternatives=true"]
    B --> C["Normalize each route"]
    C --> D["duration_in_traffic or duration"]
    D --> E["Sort ascending"]
    E --> F["fastest=true for first route"]
    F --> G["MapView decodes polyline"]
    G --> H["Traffic layer visible"]
Loading

🚓 Police Alert Flow

sequenceDiagram
    participant FE as Emergency Page
    participant BE as Police Route
    participant Places as Google Places API
    participant WS as Socket.io

    FE->>BE: POST /api/police/alert
    BE->>BE: Extract route start/end points
    loop Up to 5 route points
        BE->>Places: Nearby Search type=police
        Places-->>BE: Stations
    end
    BE->>BE: Dedupe and rank by distance
    BE->>WS: police_alert
    BE-->>FE: stationsNotified + station list
Loading

🏥 Doctor Booking Flow

flowchart TD
    A["Doctors page opens"] --> B["Read user location"]
    B --> C["GET /api/booking/doctors"]
    C --> D["Google Places doctor/clinic search"]
    D --> E["Apply specialty, rating, availability filters"]
    E --> F["Render cards"]
    F --> G["User selects doctor"]
    G --> H["GET /api/booking/slots/:doctorId"]
    H --> I["User confirms slot"]
    I --> J["POST /api/booking/appointment"]
    J --> K["Store booking + show confirmation"]
Loading

🔐 Auth Logic

flowchart LR
    A["App mount"] --> B["Read lifeline_user from localStorage"]
    B --> C{"Firebase configured?"}
    C -->|Yes| D["onAuthStateChanged"]
    D --> E["Normalize Firebase user"]
    C -->|No| F["Use local fallback session"]
    E --> G["Persist normalized session"]
    F --> G
    H --> I["Expose user via AuthContext"]
    I --> J["Dashboard reads regional metrics"]
    J --> K["Calculate Response Index + Unit availability"]
Loading

🤖 AI Health Assistant v2.0 Logic

flowchart TD
    A["User enters HealthAI"] --> B["Restore messages from localStorage"]
    B --> C["Render chat interface"]
    C --> D["User sends message"]
    D --> E["POST /api/verify/chat"]
    E --> F["AI Analysis (Gemini 1.5 Flash)"]
    F -->|Failover| G["Groq Llama-3-70B fallback"]
    G --> H["Append AI response"]
    H --> I["Persist updated array to localStorage"]
    C --> I["Export Chat .txt"]
    I --> J["Blob generation + auto-download"]
    C --> K["Copy Chat"]
    K --> L["Clipboard API writeText"]
Loading

📊 Regional Network Hub Metrics

The dashboard performs real-time status aggregation to provide high-fidelity situational awareness:

Metric Calculation Logic
Response Index Aggregated average of Directions API duration_in_traffic across regional sectors
Active Units Live count of ambulances in ready state within a 15km radius of the user
Trauma Load Real-time capacity index based on hospital admissions and emergency bay throughput
Global Status Connectivity health check across Socket.io hubs and Maps API satellites

📡 Realtime Notification Rules

Trigger Room Event
User signs into emergency page user_{userId} User-specific status updates
Ambulance request created ambulance_{ambulanceId} new_ambulance_request
Request screen active request_{requestId} Tracking updates
Driver accepted user_{userId} and request_{requestId} ambulance_assigned
Driver GPS changes user_{userId} and request_{requestId} location_update
Police alert sent Global police_alert

🧯 Failure Handling

Failure Recovery
Geolocation denied Use Kolkata fallback coordinates and keep user informed
Google Places returns zero results Show empty state or doctor fallback where applicable
Directions API fails Keep destination selected and allow retry
Firebase Admin unavailable Continue with in-memory state
Socket disconnects Socket.io reconnects using websocket/polling transports

🏆 User Levels & Gamification

To encourage community engagement and reward frequent use of the platform's safety features, LifeLine+ implements an automated leveling system based on emergency service usage.

Level Requirement Status
Silver 0–9 Requests Standard access to all emergency services
Gold 10–19 Requests Recognized frequent responder status
Platinum 20+ Requests Verified emergency community leader status

How Levels are Calculated:

  • Triggers: Every time a user activates Ambulance Booking, their totalRequests count increases.
  • Logic:
    • Silver: Default starting level.
    • Gold: Reached at 10 cumulative requests.
    • Platinum: Reached at 20 cumulative requests.
  • Persistence: Levels are calculated on the backend (dashboard.js) and persisted in the userStats collection.
  • Visibility: The current level is displayed on the Profile page and the Dashboard.

🚀 Production Scaling Path

flowchart TD
    A["Current implementation"] --> B["Firestore persistence"]
    B --> C["Redis pub/sub for Socket.io scale-out"]
    C --> D["Dedicated ambulance driver app"]
    D --> E["Verified hospital/police partner dashboard"]
    E --> F["Audit logs + DPDP compliance controls"]
Loading

Connected docs: README.md, INSTRUCTIONS.md, ARCHITECTURE.md, and LICENSE.

License

This project is licensed under the LICENSE file.