# sifatul-islam-onik/fableflash-preli architecture

> Architecture diagram of the GitHub repository sifatul-islam-onik/fableflash-preli, 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/sifatul-islam-onik/fableflash-preli
- Repository: https://github.com/sifatul-islam-onik/fableflash-preli

## Overview

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.

Main entry points: [`app/routers/analyze.py`](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/routers/analyze.py) (Analyze API), [`app/main.py`](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/main.py) (App entry), [`app/safety/guardrails.py`](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/safety/guardrails.py) (Guardrails), [`app/llm/groq_client.py`](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/llm/groq_client.py) (Groq client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["App entry<br/>FastAPI app<br/>[main.py]"]
  node_health_router["Health API<br/>route<br/>[health.py]"]
  node_analyze_router["Analyze API<br/>route<br/>[analyze.py]"]
  node_request_model["Request schema<br/>pydantic model<br/>[request.py]"]
  node_response_model["Response schema<br/>pydantic model<br/>[response.py]"]
  node_config["Config<br/>[config.py]"]
  node_guardrails{{"Guardrails<br/>safety filter<br/>[guardrails.py]"}}
end

subgraph group_logic["Domain Logic"]
  node_matcher{{"Txn matcher<br/>rule engine"}}
  node_evidence{{"Evidence check<br/>rule engine"}}
  node_classifier{{"Case class<br/>rule engine<br/>[case_classifier.py]"}}
  node_severity{{"Severity<br/>scorer<br/>[severity_scorer.py]"}}
  node_escalation{{"Escalation<br/>decision<br/>[escalation.py]"}}
end

subgraph group_llm["LLM Layer"]
  node_prompts["Prompt prep<br/>llm prompt<br/>[prompts.py]"]
  node_groq["Groq client<br/>external ai client<br/>[groq_client.py]"]
  node_parser["LLM parser<br/>response parser<br/>[parser.py]"]
  node_fallback["Fallback reply<br/>template generator<br/>[fallback.py]"]
end

subgraph group_ops["Operations"]
  node_tests["Test suite<br/>pytest"]
  node_ci["CI workflow<br/>github actions<br/>[ci.yml]"]
  node_dockerfile["Docker build<br/>container spec"]
  node_compose["Compose setup<br/>container config<br/>[docker-compose.yml]"]
end

node_main -->|"mounts"| node_health_router
node_main -->|"mounts"| node_analyze_router
node_main -->|"loads"| node_config
node_health_router -->|"returns"| node_response_model
node_analyze_router -->|"validates"| node_request_model
node_analyze_router -->|"starts"| node_matcher
node_matcher -->|"feeds"| node_evidence
node_evidence -->|"routes"| node_classifier
node_classifier -->|"refines"| node_severity
node_severity -->|"decides"| node_escalation
node_escalation -->|"summarizes"| node_prompts
node_prompts -->|"invokes"| node_groq
node_groq -->|"returns"| node_parser
node_groq -.->|"fails over"| node_fallback
node_fallback -->|"sanitizes"| node_guardrails
node_parser -->|"sanitizes"| node_guardrails
node_guardrails -->|"formats"| node_response_model
node_analyze_router -->|"returns"| node_response_model
node_tests -.->|"covers"| node_main
node_tests -.->|"covers"| node_guardrails
node_ci -->|"runs"| node_tests
node_ci -->|"builds"| node_dockerfile
node_compose -->|"uses"| node_dockerfile

click node_main "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/main.py"
click node_health_router "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/routers/health.py"
click node_analyze_router "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/routers/analyze.py"
click node_request_model "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/models/request.py"
click node_response_model "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/models/response.py"
click node_config "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/config.py"
click node_matcher "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/core/transaction_matcher.py"
click node_evidence "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/core/evidence_analyzer.py"
click node_classifier "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/core/case_classifier.py"
click node_severity "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/core/severity_scorer.py"
click node_escalation "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/core/escalation.py"
click node_prompts "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/llm/prompts.py"
click node_groq "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/llm/groq_client.py"
click node_parser "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/llm/parser.py"
click node_fallback "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/llm/fallback.py"
click node_guardrails "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/safety/guardrails.py"
click node_tests "https://github.com/sifatul-islam-onik/fableflash-preli/tree/main/tests"
click node_ci "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/.github/workflows/ci.yml"
click node_dockerfile "https://github.com/sifatul-islam-onik/fableflash-preli/tree/main/Dockerfile"
click node_compose "https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/docker-compose.yml"

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_health_router,node_analyze_router,node_request_model,node_response_model,node_config,node_guardrails toneBlue
class node_matcher,node_evidence,node_classifier,node_severity,node_escalation toneAmber
class node_prompts,node_groq,node_parser,node_fallback toneMint
class node_tests,node_ci,node_dockerfile,node_compose toneRose
```

## Components

### Application

FastAPI runtime and request-processing layers

- [App entry](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/main.py): FastAPI app · Builds the service and mounts routers · `app/main.py`
- [Health API](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/routers/health.py): route · Liveness endpoint · `app/routers/health.py`
- [Analyze API](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/routers/analyze.py): route · Ticket analysis endpoint · `app/routers/analyze.py`
- [Request schema](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/models/request.py): pydantic model · Validates ticket input · `app/models/request.py`
- [Response schema](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/models/response.py): pydantic model · Normalizes investigation output · `app/models/response.py`
- [Config](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/config.py): env config · Loads runtime settings from environment · `app/config.py`
- [Guardrails](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/safety/guardrails.py): safety filter · Removes unsafe content and normalizes output · `app/safety/guardrails.py`

### Domain Logic

Deterministic ticket investigation and decisioning

- [Txn matcher](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/core/transaction_matcher.py): rule engine · Finds the most relevant transaction · `app/core/transaction_matcher.py`
- [Evidence check](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/core/evidence_analyzer.py): rule engine · Compares complaint with transaction data · `app/core/evidence_analyzer.py`
- [Case class](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/core/case_classifier.py): rule engine · Assigns case type and department · `app/core/case_classifier.py`
- [Severity](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/core/severity_scorer.py): scorer · Rates urgency and impact · `app/core/severity_scorer.py`
- [Escalation](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/core/escalation.py): decision · Flags human review needs · `app/core/escalation.py`

### LLM Layer

External model integration and fallback generation

- [Prompt prep](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/llm/prompts.py): llm prompt · Builds model context from decisions · `app/llm/prompts.py`
- [Groq client](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/llm/groq_client.py): external ai client · Calls Groq with rotating API keys · `app/llm/groq_client.py`
- [LLM parser](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/llm/parser.py): response parser · Extracts structured model output · `app/llm/parser.py`
- [Fallback reply](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/app/llm/fallback.py): template generator · Produces deterministic text when LLM fails · `app/llm/fallback.py`

### Operations

Containerization, CI, and verification assets

- [Test suite](https://github.com/sifatul-islam-onik/fableflash-preli/tree/main/tests): pytest · Verifies health, analysis, safety, and sample cases · `tests`
- [CI workflow](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/.github/workflows/ci.yml): github actions · Runs tests and builds the image · `.github/workflows/ci.yml`
- [Docker build](https://github.com/sifatul-islam-onik/fableflash-preli/tree/main/Dockerfile): container spec · Defines the service image · `Dockerfile`
- [Compose setup](https://github.com/sifatul-islam-onik/fableflash-preli/blob/main/docker-compose.yml): container config · Local container orchestration · `docker-compose.yml`

## Connections

- App entry → Health API: mounts · Registers the health route
- App entry → Analyze API: mounts · Registers the analysis route
- App entry → Config: loads · Reads runtime settings
- Health API → Response schema: returns · Uses normal API response shape
- Analyze API → Request schema: validates · Checks incoming ticket payload
- Analyze API → Txn matcher: starts · Begins ticket reasoning
- Txn matcher → Evidence check: feeds · Passes matched transaction context
- Evidence check → Case class: routes · Provides supported case context
- Case class → Severity: refines · Adds case priority signal
- Severity → Escalation: decides · Determines need for review
- Escalation → Prompt prep: summarizes · Prepares structured decision context
- Prompt prep → Groq client: invokes · Sends generation request
- Groq client → LLM parser: returns · Model output is parsed into structure
- Groq client → Fallback reply: fails over · Uses deterministic reply on error or rate limit
- Fallback reply → Guardrails: sanitizes · Fallback text still passes safety checks
- LLM parser → Guardrails: sanitizes · Final reply is checked before return
- Guardrails → Response schema: formats · Produces API-ready response payload
- Analyze API → Response schema: returns · Responds with structured investigation result
- Test suite → App entry: covers · Exercises application behavior
- Test suite → Guardrails: covers · Checks safety filtering
- CI workflow → Test suite: runs · CI executes the test suite
- CI workflow → Docker build: builds · CI validates container image
- Compose setup → Docker build: uses · Local compose is based on the service image