Sequence Diagrams

1. User Registration & Onboarding

Flow for a new volunteer registering and setting their availability.

sequenceDiagram
    participant U as User (Volunteer)
    participant API as FastAPI Backend
    participant DB as Firestore
    participant Auth as Firebase Auth

    U->>Auth: Sign Up / Sign In
    Auth-->>U: ID Token
    U->>API: POST /users/register (Token)
    API->>Auth: Verify Token
    API->>DB: Create/Update User Profile
    DB-->>API: User Data
    API-->>U: 200 OK (User Profile)

    U->>API: PATCH /users/me/availability
    API->>DB: Update Availability ("available")
    API-->>U: 200 OK

2. Create Help Request Workflow

Flow for an affected individual submitting a help request.

sequenceDiagram
    participant U as User (Affected)
    participant API as FastAPI Backend
    participant DB as Firestore
    participant Q as Redis Queue
    participant W as Celery Worker

    U->>API: POST /requests (payload)
    API->>API: Validate Token
    API->>DB: Save Request (status="open")
    DB-->>API: Request ID
    API->>Q: Enqueue Agent Task (request_id)
    API-->>U: 201 Created

    Q->>W: Process Task
    W->>W: Analyze Request (AI Matching)
    W->>DB: Update Request (Potential Matches)

3. Task Assignment & Execution

Flow for assigning a task to a responder and tracking its progress.

sequenceDiagram
    participant Admin as Admin/Dispatcher
    participant API as FastAPI Backend
    participant DB as Firestore
    participant R as Responder

    Admin->>API: PATCH /tasks/{id}/assign (user_id)
    API->>DB: Update Task (assigned_to=user_id)
    API-->>Admin: 200 OK

    Note over R: Responder receives notification/update

    R->>API: PATCH /tasks/{id}/status (on_route)
    API->>DB: Update Task Status
    API-->>R: 200 OK

    R->>API: PATCH /tasks/{id}/status (completed)
    API->>DB: Update Task & Request Status
    API-->>R: 200 OK

4. Resource Allocation

Flow for allocating a resource to a task.

sequenceDiagram
    participant Admin as Admin/System
    participant API as FastAPI Backend
    participant DB as Firestore

    Admin->>API: POST /tasks (resource_ids=[R1, R2])
    API->>DB: Create Task
    API->>DB: Update Resources R1, R2 (status="in_use")
    API-->>Admin: 201 Created

    Note right of DB: When task is completed

    API->>DB: Update Task (completed)
    API->>DB: Update Resources R1, R2 (status="available")

5. Real-time Incident Chat

Flow for sending messages in a disaster chat room.

sequenceDiagram
    participant U as User
    participant API as FastAPI Backend
    participant DB as Firestore
    participant Listener as Other Users

    U->>API: POST /chat/{session_id}/messages
    API->>DB: Add Message to Sub-collection
    API-->>U: 200 OK

    DB-->>Listener: OnSnapshot (Real-time Update)
    Note right of Listener: Frontend updates UI automatically