# nishadmahmud/queuestorm-api architecture

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

- Interactive diagram: https://gitdiagram.com/nishadmahmud/queuestorm-api
- Repository: https://github.com/nishadmahmud/queuestorm-api

## Overview

1. **What this service is**
   - QueueStorm Investigator is a single-purpose FastAPI backend for investigating support tickets about financial transactions.
   - The main business boundary is one HTTP request: a customer complaint plus optional recent `transaction_history` goes in, and a strict structured case assessment comes out.

2. **Public API surface**
   - `app/main.py` is the entry point and exposes three routes: `/`, `/health`, and `POST /analyze-ticket`.
   - `/analyze-ticket` is the only business endpoint; it returns a fixed JSON contract with fields like `case_type`, `severity`, `department`, `evidence_verdict`, and `customer_reply`.

3. **Request/response contract**
   - `app/schemas.py` defines the canonical request and response models.
   - The service is intentionally tolerant on optional context: unknown enum-like context values degrade to null, and malformed transaction entries are tolerated rather than blocking the whole request.
   - Invalid top-level structure returns `400`, empty complaints return `422`, and the successful path always returns a schema-valid response.

4. **Core request lifecycle**
   - The processing path is: validation → evidence matching → classification/routing → reply drafting → safety filtering → final response.
   - The complaint is treated as untrusted input throughout; the design assumes prompt injection may appear inside user text and must not alter system behavior.

5. **Reasoning subsystem**
   - `app/reasoning/` contains the decision logic split into evidence extraction, classification, escalation, and routing.
   - This layer decides whether the complaint is supported by the provided transactions, whether the evidence is inconsistent or insufficient, which case type applies, and whether human review is required.
   - Escalation is a separate concern: high-risk cases, especially phishing/social-engineering, are forced toward human review.

6. **Evidence-first transaction analysis**
   - The service does not classify from complaint text alone.
   - It tries to match a `relevant_transaction_id` using clues such as amount, time, transaction type, and counterparty, then labels the evidence as consistent, inconsistent, or insufficient.
   - Duplicate-payment detection is part of the reasoning boundary, not just a prompt instruction.

7. **LLM abstraction and provider fallback**
   - `app/llm/` abstracts model access behind a provider layer with Gemini, Groq, and NVIDIA clients plus shared prompt logic.
   - The model order is configurable, and the README shows a deliberate resilience chain: multiple Gemini Flash/Flash-Lite models first, then Groq, then NVIDIA.
   - This layer is outbound-only HTTPS to external AI services; the application itself does not embed models locally.

8. **Deterministic offline fallback**
   - If all providers fail or time out, the service falls back to a rules-only engine in `app/reasoning/classify.py`.
   - That fallback is important architecturally: it preserves availability, keeps the response schema valid, and ensures the service can still be tested offline with no API keys.
   - The fallback is conservative and lower-confidence by design.

9. **Safety and guardrail layer**
   - `app/safety/` is a final post-processing choke point that scans generated text fields for unsafe content.
   - It blocks credential requests, unauthorized refund/promises, suspicious external channels, and prompt-injection style misuse.
   - Safety is field-scoped: for example, `customer_reply` is more restricted than `agent_summary`, and violations force `human_review_required = true`.

10. **Configuration and runtime dependencies**
    - `app/config.py` centralizes environment-driven settings such as API keys, model names, provider order, and timeout budgets.
    - The runtime stack is FastAPI served by Uvicorn, typically behind Nginx in production.
    - The design is built around short per-attempt timeouts and a total budget, because latency and rate-limit resilience are part of the architecture.

11. **Deployment topology**
    - Production traffic flows through `deploy/nginx.conf`, which terminates HTTPS and reverse proxies to a local Uvicorn process on `127.0.0.1:8000`.
    - A systemd unit in `deploy/preli-api.service` keeps the API process supervised and restartable.
    - Deployment targets a DigitalOcean Droplet, with setup and redeploy automation in `deploy/setup-droplet.sh` and `deploy/redeploy.sh`.

12. **CI/CD and operational validation**
    - `.github/workflows/deploy.yml` runs tests on every push to `main` and only deploys if the offline test suite passes.
    - `tests/conftest.py` intentionally clears API keys so tests exercise the deterministic fallback path instead of depending on live LLM access.
    - `scripts/replay_samples.py` and `scripts/benchmark.py` are operational tools for validating the official sample cases and latency targets.

13. **Documentation and diagram assets**
    - The repository includes a strong architecture-documentation track under `docs/diagrams/`, with separate diagrams for system layout, request lifecycle, AI fallback, safety, CI/CD, infrastructure, and data contract.
    - Those artifacts mirror the actual code boundaries and are useful for drawing a diagram that matches the implementation rather than just the README narrative.

14. **Primary external dependencies**
    - The only runtime dependencies that materially shape the architecture are the AI providers: Google Gemini, Groq, and NVIDIA NIM.
    - Everything else is internal infrastructure: FastAPI/Uvicorn for serving, Nginx/systemd for production hosting, and GitHub Actions for deployment automation.

Main entry points: [`app/main.py`](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/main.py) (Main API), [`app/llm/base.py`](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/base.py) (LLM Base), [`app/safety/filter.py`](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/safety/filter.py) (Safety Filter), [`.github/workflows/deploy.yml`](https://github.com/nishadmahmud/queuestorm-api/blob/main/.github/workflows/deploy.yml) (Deploy Workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Surface"]
  node_app_main["Main API<br/>FastAPI app<br/>[main.py]"]
  node_app_schemas["Schemas<br/>contract models<br/>[schemas.py]"]
end

subgraph group_core["Core Logic"]
  node_app_config["Config<br/>runtime settings<br/>[config.py]"]
  node_evidence["Evidence<br/>transaction matching<br/>[evidence.py]"]
  node_classify["Classify<br/>rules fallback<br/>[classify.py]"]
  node_routing["Routing<br/>[routing.py]"]
  node_escalate["Escalate<br/>risk escalation<br/>[escalate.py]"]
end

subgraph group_llm["LLM Providers"]
  node_prompts["Prompts<br/>prompt logic<br/>[prompts.py]"]
  node_llm_base["LLM Base<br/>provider interface<br/>[base.py]"]
  node_gemini["Gemini<br/>provider client<br/>[gemini.py]"]
  node_groq["Groq<br/>provider client<br/>[groq_client.py]"]
  node_nvidia["NVIDIA<br/>provider client<br/>[nvidia.py]"]
  node_compat["Compat<br/>provider adapter<br/>[_openai_compat.py]"]
end

subgraph group_safety["Safety"]
  node_safety_filter["Safety Filter<br/>guardrail<br/>[filter.py]"]
  node_cred["Credentials<br/>safety check<br/>[credentials.py]"]
  node_promise["Promises<br/>safety check<br/>[promises.py]"]
  node_channels["Channels<br/>safety check<br/>[channels.py]"]
end

subgraph group_ops["Operations"]
  node_nginx["Nginx<br/>deployment proxy<br/>[nginx.conf]"]
  node_service["Systemd<br/>service unit<br/>[preli-api.service]"]
  node_workflow["Deploy Workflow<br/>ci pipeline<br/>[deploy.yml]"]
  node_replay["Replay Samples<br/>validation tool<br/>[replay_samples.py]"]
  node_benchmark["Benchmark<br/>validation tool<br/>[benchmark.py]"]
end

subgraph group_docs["Docs"]
  node_diagrams["Diagrams<br/>docs assets"]
end

node_app_main -->|"uses contract"| node_app_schemas
node_app_main -->|"loads settings"| node_app_config
node_app_main -->|"analyzes complaint"| node_evidence
node_evidence -->|"feeds signals"| node_classify
node_classify -->|"assigns case"| node_routing
node_routing -->|"escalation check"| node_escalate
node_app_main -->|"LLM path"| node_llm_base
node_llm_base -->|"builds prompts"| node_prompts
node_llm_base -->|"tries first"| node_gemini
node_llm_base -->|"falls back"| node_groq
node_llm_base -->|"falls back"| node_nvidia
node_gemini -->|"uses transport"| node_compat
node_groq -->|"uses transport"| node_compat
node_nvidia -->|"uses transport"| node_compat
node_app_main -->|"post-processes"| node_safety_filter
node_safety_filter -->|"checks"| node_cred
node_safety_filter -->|"checks"| node_promise
node_safety_filter -->|"checks"| node_channels
node_app_main -->|"deployed by"| node_workflow
node_workflow -->|"validates"| node_replay
node_workflow -->|"measures"| node_benchmark
node_nginx -->|"fronts"| node_service
node_workflow -->|"deploys via"| node_nginx
node_diagrams -.->|"documents"| node_app_main
node_diagrams -.->|"documents"| node_evidence
node_diagrams -.->|"documents"| node_safety_filter

click node_app_main "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/main.py"
click node_app_schemas "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/schemas.py"
click node_app_config "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/config.py"
click node_evidence "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/reasoning/evidence.py"
click node_classify "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/reasoning/classify.py"
click node_routing "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/reasoning/routing.py"
click node_escalate "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/reasoning/escalate.py"
click node_prompts "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/prompts.py"
click node_llm_base "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/base.py"
click node_gemini "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/gemini.py"
click node_groq "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/groq_client.py"
click node_nvidia "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/nvidia.py"
click node_compat "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/_openai_compat.py"
click node_safety_filter "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/safety/filter.py"
click node_cred "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/safety/credentials.py"
click node_promise "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/safety/promises.py"
click node_channels "https://github.com/nishadmahmud/queuestorm-api/blob/main/app/safety/channels.py"
click node_nginx "https://github.com/nishadmahmud/queuestorm-api/blob/main/deploy/nginx.conf"
click node_service "https://github.com/nishadmahmud/queuestorm-api/blob/main/deploy/preli-api.service"
click node_workflow "https://github.com/nishadmahmud/queuestorm-api/blob/main/.github/workflows/deploy.yml"
click node_replay "https://github.com/nishadmahmud/queuestorm-api/blob/main/scripts/replay_samples.py"
click node_benchmark "https://github.com/nishadmahmud/queuestorm-api/blob/main/scripts/benchmark.py"
click node_diagrams "https://github.com/nishadmahmud/queuestorm-api/blob/main/docs/diagrams/01-architecture.mmd"

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_app_main,node_app_schemas toneBlue
class node_app_config,node_evidence,node_classify,node_routing,node_escalate toneAmber
class node_prompts,node_llm_base,node_gemini,node_groq,node_nvidia,node_compat toneMint
class node_safety_filter,node_cred,node_promise,node_channels toneRose
class node_nginx,node_service,node_workflow,node_replay,node_benchmark toneIndigo
class node_diagrams toneTeal
```

## Components

### API Surface

FastAPI entrypoint and request/response contract

- [Main API](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/main.py): FastAPI app · Entry point exposing health and analyze-ticket routes · `app/main.py`
- [Schemas](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/schemas.py): contract models · Canonical request and response structures · `app/schemas.py`

### Core Logic

Request lifecycle, reasoning, and fallback classification

- [Config](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/config.py): runtime settings · Environment-driven model, timeout, and provider configuration · `app/config.py`
- [Evidence](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/reasoning/evidence.py): transaction matching · Extracts relevant transaction signals and labels evidence quality · `app/reasoning/evidence.py`
- [Classify](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/reasoning/classify.py): rules fallback · Deterministic case type and severity decision path · `app/reasoning/classify.py`
- [Routing](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/reasoning/routing.py): review routing · Maps cases to department and human review need · `app/reasoning/routing.py`
- [Escalate](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/reasoning/escalate.py): risk escalation · Raises human review for high-risk or ambiguous cases · `app/reasoning/escalate.py`

### LLM Providers

Provider abstraction and external model clients

- [Prompts](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/prompts.py): prompt logic · Shared prompt assembly for model calls · `app/llm/prompts.py`
- [LLM Base](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/base.py): provider interface · Common model abstraction and provider orchestration · `app/llm/base.py`
- [Gemini](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/gemini.py): provider client · Gemini model client used in the fallback chain · `app/llm/gemini.py`
- [Groq](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/groq_client.py): provider client · Groq client used after Gemini in the provider order · `app/llm/groq_client.py`
- [NVIDIA](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/nvidia.py): provider client · NVIDIA NIM client used as a later fallback provider · `app/llm/nvidia.py`
- [Compat](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/llm/_openai_compat.py): provider adapter · OpenAI-compatible transport helpers shared by clients · `app/llm/_openai_compat.py`

### Safety

Post-processing guardrails for generated output

- [Safety Filter](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/safety/filter.py): guardrail · Scans generated fields for unsafe or disallowed content · `app/safety/filter.py`
- [Credentials](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/safety/credentials.py): safety check · Blocks credential requests and secret harvesting · `app/safety/credentials.py`
- [Promises](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/safety/promises.py): safety check · Blocks unauthorized refunds and payment promises · `app/safety/promises.py`
- [Channels](https://github.com/nishadmahmud/queuestorm-api/blob/main/app/safety/channels.py): safety check · Blocks suspicious external contact channels · `app/safety/channels.py`

### Operations

Deployment, CI, and validation tooling

- [Nginx](https://github.com/nishadmahmud/queuestorm-api/blob/main/deploy/nginx.conf): deployment proxy · Terminates HTTPS and reverse proxies to the app · `deploy/nginx.conf`
- [Systemd](https://github.com/nishadmahmud/queuestorm-api/blob/main/deploy/preli-api.service): service unit · Supervises the API process on the host · `deploy/preli-api.service`
- [Deploy Workflow](https://github.com/nishadmahmud/queuestorm-api/blob/main/.github/workflows/deploy.yml): ci pipeline · Runs tests and deploys from GitHub Actions · `.github/workflows/deploy.yml`
- [Replay Samples](https://github.com/nishadmahmud/queuestorm-api/blob/main/scripts/replay_samples.py): validation tool · Runs official sample cases through the service · `scripts/replay_samples.py`
- [Benchmark](https://github.com/nishadmahmud/queuestorm-api/blob/main/scripts/benchmark.py): validation tool · Checks latency and operational performance · `scripts/benchmark.py`

### Docs

Architecture diagrams and reference artifacts

- [Diagrams](https://github.com/nishadmahmud/queuestorm-api/blob/main/docs/diagrams/01-architecture.mmd): docs assets · Architecture diagrams matching the implemented boundaries · `docs/diagrams/01-architecture.mmd`

## Connections

- Main API → Schemas: uses contract · Validates requests and returns the structured response schema
- Main API → Config: loads settings · Reads runtime configuration for provider order and budgets
- Main API → Evidence: analyzes complaint · Starts the evidence-first request lifecycle
- Evidence → Classify: feeds signals · Hands matched evidence and transaction context to classification
- Classify → Routing: assigns case · Determines department and handling path
- Routing → Escalate: escalation check · Forces human review for high-risk or unclear cases
- Main API → LLM Base: LLM path · Uses model abstraction when provider-backed reasoning is available
- LLM Base → Prompts: builds prompts · Assembles shared prompts for external model calls
- LLM Base → Gemini: tries first · Primary provider in the configured fallback chain
- LLM Base → Groq: falls back · Secondary provider in the configured fallback chain
- LLM Base → NVIDIA: falls back · Later provider in the configured fallback chain
- Gemini → Compat: uses transport · Shares OpenAI-compatible client helpers
- Groq → Compat: uses transport · Shares OpenAI-compatible client helpers
- NVIDIA → Compat: uses transport · Shares OpenAI-compatible client helpers
- Main API → Safety Filter: post-processes · Applies final guardrails to generated output fields
- Safety Filter → Credentials: checks · Rejects credential-seeking text
- Safety Filter → Promises: checks · Rejects unauthorized refund or promise language
- Safety Filter → Channels: checks · Rejects suspicious external contact instructions
- Main API → Deploy Workflow: deployed by · CI validates main branch before deployment
- Deploy Workflow → Replay Samples: validates · Exercises sample cases in the offline path
- Deploy Workflow → Benchmark: measures · Checks latency and throughput targets
- Nginx → Systemd: fronts · Routes public traffic to the supervised app process
- Deploy Workflow → Nginx: deploys via · Operational deployment targets the Nginx-fronted host
- Diagrams → Main API: documents · Reference diagrams mirror the implemented architecture
- Diagrams → Evidence: documents · Request lifecycle and evidence flow are diagrammed
- Diagrams → Safety Filter: documents · Safety guardrail boundaries are diagrammed