Skip to content

Chatbot Architecture

The chatbot is a cross-channel assistant exposed by the backend endpoint POST /chatbot/ask.

Functional Goals

  • Provide context-aware guidance for citizens/responders/admins.
  • Use role, location, disaster context, and chat history to produce actionable responses.
  • Keep responses aligned with operational constraints and available resources.

Request Lifecycle

sequenceDiagram
    autonumber
    participant C as Client (Web/Mobile)
    participant API as FastAPI /chatbot/ask
    participant DB as Firestore
    participant S as ChatbotService
    participant LLM as OpenAI
    participant O as Langfuse

    C->>API: POST /chatbot/ask {user, prompt, chat_history}
    API->>API: Verify token + validate payload
    API->>S: Forward normalized request
    S->>DB: Fetch relevant context (disaster, tasks, requests, resources)
    S->>S: Build system + role + context prompt
    S->>LLM: Generate response
    LLM-->>S: Assistant output
    S->>O: Trace tokens/latency/outcome
    S-->>API: Final response payload
    API-->>C: 200 OK

Context Inputs Used By The Bot

  1. User profile and role (admin, responder, volunteer, affected_individual)
  2. Current disaster or location context
  3. Active requests, tasks, and resource availability snapshots
  4. Conversation memory (chat_history)

Chatbot Safety And Control Layer

  • Authentication required for protected contexts.
  • Request validation via backend schemas before prompt assembly.
  • Role-aware prompting to avoid giving privileged instructions to unauthorized users.
  • Human decision authority retained for final dispatch/resource authorization.

Integration Points

  • Web UI: floating chatbot component in frontend.
  • Mobile UI: can call same backend endpoint when online.
  • Agentic workflow: chatbot can surface workflow-derived status and guidance, while task/resource actions remain API-driven and auditable.