ahosanforazi/hackathon-preli01

1. What this repository is

QueueStorm Investigator is a small FastAPI service that turns a customer complaint plus recent transaction history into a structured JSON assessment for support agents. It is a support copilot, not a transaction executor or financial decision engine.

2. External interface boundary

The only runtime API surface is in app/main.py: a health check and an analysis endpoint (/analyze-ticket). The service receives a validated request payload and returns a normalized case verdict, severity, department routing, evidence status, and human-review flag.

3. Schema and contract layer

app/schemas.py defines the request/response shapes and is the contract boundary for the whole system. It enforces the complaint text, ticket metadata, and transaction history structure before any analysis runs, which keeps the downstream logic deterministic and predictable.

4. Orchestration layer

app/analyzer.py is the central pipeline coordinator. It takes validated input and sequences the main steps: complaint classification, transaction evidence evaluation, risk/severity assignment, routing, confidence calculation, and final response assembly.

5. Rules engine

app/rules.py contains the core complaint taxonomy and keyword/regex-based classification logic. This is where the system maps free-form English and Bangla complaint text into supported case types such as wrong transfer, failed payment, duplicate payment, refund request, phishing, settlement delay, and cash-in issues.

6. Transaction evidence subsystem

The analyzer also checks the complaint against transaction_history to decide whether evidence is consistent, inconsistent, or insufficient_data. This is a local correlation step: it is not connected to a payment gateway or ledger, and it only reasons over the request payload.

7. Reasoning/model abstraction

app/ai_model.py provides the “AI reasoning” abstraction, but in this repository it is implemented as a local deterministic heuristic layer, not a remote LLM. That means the architecture is single-process, CPU-local, and has no dependency on external model APIs.

8. Safety and policy enforcement

app/safety.py is a hard safety boundary after analysis. It blocks unsafe or non-compliant outputs such as requests for OTP/PIN/password, refund promises, or other risky wording, and it escalates phishing/social-engineering cases to critical/manual review.

9. End-to-end data flow

The flow is: client request → FastAPI endpoint → Pydantic validation → analyzer orchestration → rules/evidence checks → safety rewrite/validation → structured JSON response. The design is intentionally linear and layered so that classification, evidence analysis, and safety checks are separable.

10. Testing and synthetic data

sample_data/test_cases.json and test_runner.py provide offline scenario validation using synthetic complaints. This is a repository-level test harness, not a live integration test against external systems.

11. Deployment/runtime shape

The app runs with Uvicorn and is packaged with a Dockerfile, which indicates a simple containerized Python service deployment. There are no databases, queues, or third-party payment integrations in the current architecture.

12. Architectural takeaway

The key boundary to draw is a single FastAPI service with an internal deterministic analysis pipeline and a post-processing safety gate. Everything else in the repo supports that pipeline: schemas define the contract, rules/model modules perform the reasoning, and the test assets validate behavior with synthetic data.