sifatul-islam-onik/fableflash-preli

1. What this repository is

QueueStorm Investigator is a stateless FastAPI service for analyzing digital-finance support tickets. Its main job is to turn a complaint plus recent transaction history into a structured investigation result and a safe customer reply.

2. Top-level runtime boundary

The runtime entrypoint is app/main.py, which wires the API routers into a FastAPI app. There are two public endpoints: GET /health for liveness and POST /analyze-ticket for the ticket-analysis workflow.

3. Request/response contract

Input and output are modeled with Pydantic schemas under app/models. This is the main boundary between external clients and internal logic: requests are strictly validated before any analysis runs, and the response is normalized into a structured API payload.

4. Core deterministic engine

Most business reasoning lives in app/core. This layer is intentionally rule-based and deterministic:

- transaction_matcher.py identifies the most relevant transaction from user history.

- evidence_analyzer.py judges whether the complaint is supported by the transaction data.

- case_classifier.py maps the ticket to a case type and support department.

- severity_scorer.py assigns severity.

- escalation.py decides whether human review is required.

This is the main domain logic and the most important subsystem for an architecture diagram.

5. Primary data flow for analysis

The /analyze-ticket flow is: validate request → match transaction context → analyze evidence consistency → classify case and route department → score severity → decide escalation → generate customer-facing text. The core decision fields are produced before any LLM call, so the model is used for language generation rather than business judgment.

6. LLM layer and external dependency

The app/llm package isolates all model-facing behavior. groq_client.py is the only external AI dependency and talks to Groq using API keys from environment variables. prompts.py prepares the prompt context, parser.py extracts structured output from the model response, and fallback.py provides a deterministic template-based response when the model is unavailable or rate-limited.

7. Failover behavior

The LLM client is designed to degrade gracefully: it can iterate through multiple GROQ_API_KEY_* keys and falls back to local template generation if calls fail. That means the service does not depend on the LLM for correctness, only for better natural-language output.

8. Safety boundary

app/safety/guardrails.py is a post-processing safety layer applied to generated replies. It scans for unsafe content such as credential requests, unauthorized refund promises, or off-channel contact instructions, and it also normalizes text formatting into single-line outputs. This is the final gate before a response is returned to clients.

9. Configuration and deployment

app/config.py centralizes runtime configuration from environment variables. The repo includes Docker support (Dockerfile, docker-compose.yml) and environment templates (.env.example), so the application is intended to run as a containerized API service without any database or persistent storage.

10. Operational and verification surface

Tests under tests/ cover health checks, analyze behavior, safety rules, and sample-case regressions. CI is handled by GitHub Actions in .github/workflows/ci.yml, which runs the test suite and builds the Docker image. The sample cases and output files in the repo are evaluation artifacts, not runtime dependencies.

11. Important architectural takeaway

The overall architecture is a layered pipeline: API boundary → deterministic finance-ops reasoning → optional LLM text generation → safety sanitization → response. The important separation is that domain decisions stay local and rule-based, while the LLM is treated as a constrained text service behind a failover and guardrail boundary.