# ahosanforazi/hackathon-preli01 architecture

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

- Interactive diagram: https://gitdiagram.com/ahosanforazi/hackathon-preli01
- Repository: https://github.com/ahosanforazi/hackathon-preli01

## Overview

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.

Main entry points: [`app/analyzer.py`](https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/analyzer.py) (Orchestrator), [`app/main.py`](https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/main.py) (API entry), [`app/rules.py`](https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/rules.py) (Complaint rules), [`app/ai_model.py`](https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/ai_model.py) (Reasoning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Service runtime"]
  node_main["API entry<br/>fastapi app<br/>[main.py]"]
  node_schemas["Contracts<br/>pydantic schemas<br/>[schemas.py]"]
  node_analyzer["Orchestrator<br/>analysis pipeline<br/>[analyzer.py]"]
  node_rules["Complaint rules<br/>taxonomy engine<br/>[rules.py]"]
  node_ai_model["Reasoning<br/>deterministic heuristic<br/>[ai_model.py]"]
  node_safety["Safety gate<br/>policy filter<br/>[safety.py]"]
  node_request["Complaint input<br/>ticket payload"]
  node_classification{{"Case type<br/>complaint classification"}}
  node_evidence["Evidence check<br/>transaction correlation"]
  node_severity(("Severity<br/>risk scoring"))
  node_routing{{"Routing<br/>department mapping"}}
  node_response["JSON verdict<br/>structured output"]
  node_container["Container<br/>docker runtime"]
end

subgraph group_support["Support assets"]
  node_sample_data["Scenario set<br/>synthetic cases<br/>[test_cases.json]"]
  node_runner["Test runner<br/>local harness<br/>[test_runner.py]"]
  node_output["Sample output<br/>reference result<br/>[sample_output.json]"]
end

node_request -->|"POST analyze"| node_main
node_main -->|"validate"| node_schemas
node_main -->|"dispatch"| node_analyzer
node_analyzer -->|"classify"| node_rules
node_analyzer -->|"correlate"| node_evidence
node_analyzer -->|"score"| node_ai_model
node_analyzer -->|"assign"| node_severity
node_analyzer -->|"route"| node_routing
node_rules -->|"emit"| node_classification
node_evidence -->|"support"| node_classification
node_ai_model -->|"influence"| node_severity
node_severity -->|"embed"| node_response
node_routing -->|"embed"| node_response
node_classification -->|"embed"| node_response
node_evidence -->|"embed"| node_response
node_analyzer -->|"post-process"| node_safety
node_safety -->|"approve"| node_response
node_sample_data -->|"feed"| node_runner
node_runner -->|"exercise"| node_analyzer
node_container -->|"run"| node_main

click node_main "https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/main.py"
click node_schemas "https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/schemas.py"
click node_analyzer "https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/analyzer.py"
click node_rules "https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/rules.py"
click node_ai_model "https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/ai_model.py"
click node_safety "https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/safety.py"
click node_sample_data "https://github.com/ahosanforazi/hackathon-preli01/blob/main/sample_data/test_cases.json"
click node_runner "https://github.com/ahosanforazi/hackathon-preli01/blob/main/test_runner.py"
click node_output "https://github.com/ahosanforazi/hackathon-preli01/blob/main/sample_output.json"
click node_container "https://github.com/ahosanforazi/hackathon-preli01/tree/main/Dockerfile"

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_main,node_schemas,node_analyzer,node_rules,node_ai_model,node_safety,node_request,node_classification,node_evidence,node_severity,node_routing,node_response,node_container toneBlue
class node_sample_data,node_runner,node_output toneAmber
```

## Components

### Service runtime

FastAPI service and its internal analysis pipeline.

- [API entry](https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/main.py): fastapi app · Exposes health and analyze-ticket endpoints. · `app/main.py`
- [Contracts](https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/schemas.py): pydantic schemas · Validates request and response payloads for the service. · `app/schemas.py`
- [Orchestrator](https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/analyzer.py): analysis pipeline · Coordinates classification, evidence checks, risk scoring, routing, and response assembly. · `app/analyzer.py`
- [Complaint rules](https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/rules.py): taxonomy engine · Maps free-form complaint text to supported case types using keywords and regex. · `app/rules.py`
- [Reasoning](https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/ai_model.py): deterministic heuristic · Provides local AI-like scoring and reasoning without external model APIs. · `app/ai_model.py`
- [Safety gate](https://github.com/ahosanforazi/hackathon-preli01/blob/main/app/safety.py): policy filter · Blocks unsafe wording and escalates risky or phishing-related outputs. · `app/safety.py`
- **Complaint input**: ticket payload · Customer complaint, ticket metadata, and transaction history submitted by the client.
- **Case type**: complaint classification · Normalized complaint category such as wrong transfer, failed payment, or refund request.
- **Evidence check**: transaction correlation · Compares complaint details with transaction history for consistency.
- **Severity**: risk scoring · Assigns urgency and review priority for the case.
- **Routing**: department mapping · Selects the support team or department for the case.
- **JSON verdict**: structured output · Final structured assessment returned to support agents.
- [Container](https://github.com/ahosanforazi/hackathon-preli01/tree/main/Dockerfile): docker runtime · Package for running the service in a containerized Python environment. · `Dockerfile`

### Support assets

Offline scenario data and local validation harness.

- [Scenario set](https://github.com/ahosanforazi/hackathon-preli01/blob/main/sample_data/test_cases.json): synthetic cases · Offline complaint scenarios used to exercise the analyzer. · `sample_data/test_cases.json`
- [Test runner](https://github.com/ahosanforazi/hackathon-preli01/blob/main/test_runner.py): local harness · Executes offline scenario validation against the service logic. · `test_runner.py`
- [Sample output](https://github.com/ahosanforazi/hackathon-preli01/blob/main/sample_output.json): reference result · Example generated result from local scenario runs. · `sample_output.json`

## Connections

- Complaint input → API entry: POST analyze · Client submits a validated complaint request to the API.
- API entry → Contracts: validate · Endpoint relies on the schema boundary before analysis begins.
- API entry → Orchestrator: dispatch · API hands the validated payload to the analysis pipeline.
- Orchestrator → Complaint rules: classify · Pipeline uses taxonomy rules to detect the complaint type.
- Orchestrator → Evidence check: correlate · Pipeline compares complaint claims with transaction history.
- Orchestrator → Reasoning: score · Pipeline uses local heuristic reasoning for severity and confidence.
- Orchestrator → Severity: assign · Pipeline derives urgency from rule and evidence signals.
- Orchestrator → Routing: route · Pipeline maps the case to the appropriate support department.
- Complaint rules → Case type: emit · Rules engine produces the normalized case type.
- Evidence check → Case type: support · Evidence results inform whether the detected case is consistent.
- Reasoning → Severity: influence · Heuristic reasoning contributes to severity and confidence.
- Severity → JSON verdict: embed · Final response includes the severity level.
- Routing → JSON verdict: embed · Final response includes department routing.
- Case type → JSON verdict: embed · Final response includes the normalized verdict.
- Evidence check → JSON verdict: embed · Final response includes evidence status.
- Orchestrator → Safety gate: post-process · Safety layer reviews and rewrites unsafe outputs after analysis.
- Safety gate → JSON verdict: approve · Safe output is returned as the structured JSON response.
- Scenario set → Test runner: feed · Offline scenarios are loaded into the local harness.
- Test runner → Orchestrator: exercise · Harness validates analyzer behavior with synthetic cases.
- Container → API entry: run · Docker image packages the FastAPI service for deployment.