Skip to content

Dataflow

This page describes the canonical data movement from user input to dispatch execution and updates.

Core Operational Entities

  • User: authenticated actor (admin, volunteer, responder, affected_individual)
  • Disaster: event context
  • Request: help request raised by affected user
  • WorkflowOutput: AI-generated plan artifacts for a request
  • Task: executable unit assigned to responders
  • Resource: physical assets/manpower tied to tasks
  • Message and Observation: communication and field intelligence

End-to-End Help Request Dataflow

sequenceDiagram
    autonumber
    participant U as User (Web/Mobile)
    participant API as FastAPI
    participant DB as Firestore
    participant Q as Redis
    participant W as Celery Agent Worker
    participant A as Admin/Dispatcher
    participant R as Responder

    U->>API: POST /requests
    API->>API: Verify Firebase token + validate payload
    API->>DB: Create Request(status=open)
    API->>Q: Enqueue workflow job(request_id)
    API-->>U: 201 Created

    Q->>W: Consume workflow job
    W->>DB: Read request/disaster/resources/users
    W->>W: Generate workflow tasks + resource suggestions
    W->>DB: Save WorkflowOutput (/workflow-outputs)

    A->>API: GET /workflow-outputs/{request_id}
    API->>DB: Fetch workflow output
    API-->>A: Suggested plan for review
    A->>API: POST/PATCH task + resource decisions
    API->>DB: Create/assign Task and update Resource statuses

    R->>API: PATCH /tasks/{task_id}/status (on_route/completed)
    API->>DB: Update task and related request status
    API-->>R: 200 OK

Read vs Write Paths

Write-heavy paths

  • Help creation (POST /requests)
  • Task lifecycle updates (PATCH /tasks/{id}/status)
  • Resource allocation updates (POST /tasks, PUT /resources/{id}/status)
  • Chat/observation submissions

Read-heavy paths

  • Dashboard views (/requests, /tasks, /resources, /disasters)
  • Agent output review (/workflow-outputs/*)
  • Chat history and map overlays

Consistency Model

  1. Operational truth lives in Firestore.
  2. Asynchronous AI planning runs out-of-band through Redis/Celery.
  3. User-facing flows receive immediate acknowledgment, then observe progressive updates as workflow outputs and assignments are persisted.