# asef69/buet-air architecture

> Architecture diagram of the GitHub repository asef69/buet-air, 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/asef69/buet-air
- Repository: https://github.com/asef69/buet-air

## Overview

1. **Overall shape**
   - This repository is a small, stateless AI support-analysis service.
   - The core workflow is: incoming ticket → validate/normalize → analyze transaction evidence in Python → call Gemini for a structured answer → apply safety filtering → return JSON to the client.

2. **API boundary**
   - The public entrypoint lives in `Iztihad/api`.
   - `main.py` boots the FastAPI application, `routes.py` defines the HTTP endpoints, `schemas.py` defines request/response contracts, and `middleware.py` holds cross-cutting request handling.
   - The README indicates the main use case is a POST-style ticket analysis endpoint rather than a broader web app.

3. **Domain / orchestration layer**
   - `Asef/core/ticket_analyzer.py` is the central orchestrator.
   - It likely coordinates classification, evidence extraction, prompt assembly, model invocation, and response shaping.
   - This is the main seam between API concerns and business logic.

4. **Evidence-first analysis**
   - `Asef/core/evidence_engine.py` is a deterministic rules-based layer that examines the complaint and transaction history before any LLM call.
   - The README says it extracts amounts in English/Bangla, matches amounts to history, detects duplicate payments, and infers recipient patterns.
   - Architecturally, this is the factual grounding layer that reduces dependence on the model for numeric or transactional reasoning.

5. **Complaint classification**
   - `Asef/core/classifier.py` appears to categorize ticket intent or dispute type before downstream response generation.
   - This likely helps route the case or choose the right prompt/analysis branch.
   - It functions as a lightweight domain decision layer rather than a machine-learning-heavy subsystem.

6. **Response generation**
   - `Asef/core/reply_builder.py` is the component that turns analysis results into the final customer-facing reply.
   - It sits after evidence analysis and model output, shaping the answer into a support-appropriate format.
   - This is the formatting/composition boundary between internal reasoning and the external response.

7. **Safety and compliance layer**
   - `Asef/core/safety_guard.py` is a post-processing gate on model-generated text.
   - The README describes protections against PIN/OTP leakage, overpromising refunds, and non-official contact instructions.
   - In the architecture diagram, this should be shown as a final filter before the API response leaves the system.

8. **LLM integration**
   - `Asef/llm/client.py` is the external-model adapter, and `Asef/llm/prompts.py` contains prompt templates/context construction.
   - The service uses Google Generative AI Gemini, specifically `gemini-2.5-flash`, as a hosted external dependency.
   - The architecture relies on structured JSON output from the model, which is important for reliable API responses.

9. **Shared contracts and types**
   - `Shared/models/enums.py` and the test fixtures under `Shared/tests` suggest shared domain constants and reusable cases.
   - These shared definitions likely keep the API layer, core engine, and tests aligned on status labels, categories, or response codes.
   - This is the repo’s main contract layer for consistency across modules.

10. **Validation and test harness**
   - `Shared/tests/test_api.py`, `test_classifier.py`, `test_evidence.py`, and `test_safety.py` indicate unit/integration coverage around the major subsystems.
   - `sample_output.json` and `Shared/tests/SUST_Preli_Sample_Cases.json` provide reference cases for regression verification.
   - The `scratch/` scripts are ad hoc validation tools and are not part of the runtime path.

11. **Configuration and deployment**
   - `Iztihad/config/settings.py` likely centralizes environment-driven config such as API keys and runtime settings.
   - `Iztihad/infra/Dockerfile`, `docker-compose.yaml`, `vercel.json`, and `.env.example` show the service is designed for containerized deployment with environment configuration.
   - This is a deployable service, not a stateful platform; there is no visible database or queue subsystem in the tree.

12. **External dependencies and trust boundary**
   - The only explicit external runtime dependency in the architecture is the Gemini API hosted by Google.
   - All ticket reasoning is performed inside the service before and after the model call, with the model acting as an assistant rather than the source of truth.
   - The trust boundary should therefore show: client → FastAPI service → external LLM → safety filter → client, with deterministic Python analysis anchoring the model output.

Main entry points: [`Asef/core/ticket_analyzer.py`](https://github.com/asef69/buet-air/blob/main/Asef/core/ticket_analyzer.py) (Analyzer), [`Iztihad/api/main.py`](https://github.com/asef69/buet-air/blob/main/Iztihad/api/main.py) (Main app), [`Iztihad/api/routes.py`](https://github.com/asef69/buet-air/blob/main/Iztihad/api/routes.py) (Routes), [`Asef/core/safety_guard.py`](https://github.com/asef69/buet-air/blob/main/Asef/core/safety_guard.py) (Safety guard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API boundary"]
  node_api_main["Main app<br/>FastAPI bootstrap<br/>[main.py]"]
  node_api_routes["Routes<br/>HTTP endpoints<br/>[routes.py]"]
  node_api_schemas["Schemas<br/>API contracts<br/>[schemas.py]"]
  node_api_middleware["Middleware<br/>cross-cutting HTTP<br/>[middleware.py]"]
end

subgraph group_core["Domain core"]
  node_core_analyzer{{"Analyzer<br/>orchestrator<br/>[ticket_analyzer.py]"}}
  node_core_classifier(("Classifier<br/>dispute routing<br/>[classifier.py]"))
  node_core_evidence{{"Evidence engine<br/>rules-based analysis<br/>[evidence_engine.py]"}}
  node_core_reply["Reply builder<br/>response composition<br/>[reply_builder.py]"]
  node_core_safety{{"Safety guard<br/>policy filter<br/>[safety_guard.py]"}}
end

subgraph group_llm["LLM integration"]
  node_llm_client["Gemini client<br/>model adapter<br/>[client.py]"]
  node_llm_prompts["Prompts<br/>prompt templates<br/>[prompts.py]"]
end

subgraph group_shared["Shared contracts"]
  node_shared_enums["Enums<br/>shared constants<br/>[enums.py]"]
  node_shared_cases["Sample cases<br/>test fixtures"]
end

subgraph group_ops["Deployment"]
  node_infra_settings["Settings<br/>runtime config<br/>[settings.py]"]
  node_infra_docker["Dockerfile<br/>container build"]
  node_infra_compose["Compose<br/>local deployment"]
  node_infra_vercel["Vercel config<br/>deployment config<br/>[vercel.json]"]
end

subgraph group_validation["Validation"]
  node_tests_api["API tests<br/>integration tests<br/>[test_api.py]"]
  node_tests_core["Core tests<br/>unit tests<br/>[test_classifier.py]"]
  node_tests_safety["Safety tests<br/>unit tests<br/>[test_safety.py]"]
end

node_api_main -->|"registers"| node_api_routes
node_api_main -->|"uses"| node_api_middleware
node_api_routes -->|"validates"| node_api_schemas
node_api_routes -->|"calls"| node_core_analyzer
node_core_analyzer -->|"classifies"| node_core_classifier
node_core_analyzer -->|"grounds"| node_core_evidence
node_core_analyzer -->|"prepares"| node_llm_prompts
node_core_analyzer -->|"invokes"| node_llm_client
node_llm_prompts -->|"feeds"| node_llm_client
node_core_analyzer -->|"formats"| node_core_reply
node_core_analyzer -->|"filters"| node_core_safety
node_core_reply -->|"checks"| node_core_safety
node_core_safety -->|"returns"| node_api_routes
node_core_classifier -->|"uses"| node_shared_enums
node_core_evidence -->|"uses"| node_shared_enums
node_api_schemas -->|"uses"| node_shared_enums
node_tests_api -.->|"exercises"| node_api_routes
node_tests_core -.->|"tests"| node_core_classifier
node_tests_core -.->|"tests"| node_core_evidence
node_tests_safety -.->|"tests"| node_core_safety
node_tests_core -.->|"uses"| node_shared_cases
node_infra_settings -->|"configures"| node_api_main
node_infra_docker -->|"packages"| node_api_main
node_infra_compose -->|"runs"| node_infra_docker
node_infra_vercel -->|"deploys"| node_api_main

click node_api_main "https://github.com/asef69/buet-air/blob/main/Iztihad/api/main.py"
click node_api_routes "https://github.com/asef69/buet-air/blob/main/Iztihad/api/routes.py"
click node_api_schemas "https://github.com/asef69/buet-air/blob/main/Iztihad/api/schemas.py"
click node_api_middleware "https://github.com/asef69/buet-air/blob/main/Iztihad/api/middleware.py"
click node_core_analyzer "https://github.com/asef69/buet-air/blob/main/Asef/core/ticket_analyzer.py"
click node_core_classifier "https://github.com/asef69/buet-air/blob/main/Asef/core/classifier.py"
click node_core_evidence "https://github.com/asef69/buet-air/blob/main/Asef/core/evidence_engine.py"
click node_core_reply "https://github.com/asef69/buet-air/blob/main/Asef/core/reply_builder.py"
click node_core_safety "https://github.com/asef69/buet-air/blob/main/Asef/core/safety_guard.py"
click node_llm_client "https://github.com/asef69/buet-air/blob/main/Asef/llm/client.py"
click node_llm_prompts "https://github.com/asef69/buet-air/blob/main/Asef/llm/prompts.py"
click node_shared_enums "https://github.com/asef69/buet-air/blob/main/Shared/models/enums.py"
click node_shared_cases "https://github.com/asef69/buet-air/blob/main/Shared/tests/SUST_Preli_Sample_Cases.json"
click node_tests_api "https://github.com/asef69/buet-air/blob/main/Shared/tests/test_api.py"
click node_tests_core "https://github.com/asef69/buet-air/blob/main/Shared/tests/test_classifier.py"
click node_tests_safety "https://github.com/asef69/buet-air/blob/main/Shared/tests/test_safety.py"
click node_infra_settings "https://github.com/asef69/buet-air/blob/main/Iztihad/config/settings.py"
click node_infra_docker "https://github.com/asef69/buet-air/tree/main/Iztihad/infra/Dockerfile"
click node_infra_compose "https://github.com/asef69/buet-air/blob/main/Iztihad/infra/docker-compose.yaml"
click node_infra_vercel "https://github.com/asef69/buet-air/blob/main/vercel.json"

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_api_main,node_api_routes,node_api_schemas,node_api_middleware toneBlue
class node_core_analyzer,node_core_classifier,node_core_evidence,node_core_reply,node_core_safety toneAmber
class node_llm_client,node_llm_prompts toneMint
class node_shared_enums,node_shared_cases toneRose
class node_infra_settings,node_infra_docker,node_infra_compose,node_infra_vercel toneIndigo
class node_tests_api,node_tests_core,node_tests_safety toneTeal
```

## Components

### API boundary

Public HTTP entrypoint and request/response handling.

- [Main app](https://github.com/asef69/buet-air/blob/main/Iztihad/api/main.py): FastAPI bootstrap · Starts the API service and wires runtime components. · `Iztihad/api/main.py`
- [Routes](https://github.com/asef69/buet-air/blob/main/Iztihad/api/routes.py): HTTP endpoints · Defines the ticket analysis API endpoints. · `Iztihad/api/routes.py`
- [Schemas](https://github.com/asef69/buet-air/blob/main/Iztihad/api/schemas.py): API contracts · Request and response models for the public interface. · `Iztihad/api/schemas.py`
- [Middleware](https://github.com/asef69/buet-air/blob/main/Iztihad/api/middleware.py): cross-cutting HTTP · Shared request handling and API-level concerns. · `Iztihad/api/middleware.py`

### Domain core

Ticket analysis, evidence extraction, classification, reply shaping, and safety.

- [Analyzer](https://github.com/asef69/buet-air/blob/main/Asef/core/ticket_analyzer.py): orchestrator · Coordinates the full ticket analysis workflow. · `Asef/core/ticket_analyzer.py`
- [Classifier](https://github.com/asef69/buet-air/blob/main/Asef/core/classifier.py): dispute routing · Categorizes the ticket before downstream analysis. · `Asef/core/classifier.py`
- [Evidence engine](https://github.com/asef69/buet-air/blob/main/Asef/core/evidence_engine.py): rules-based analysis · Extracts and matches transaction facts before LLM use. · `Asef/core/evidence_engine.py`
- [Reply builder](https://github.com/asef69/buet-air/blob/main/Asef/core/reply_builder.py): response composition · Shapes analysis output into a customer-facing reply. · `Asef/core/reply_builder.py`
- [Safety guard](https://github.com/asef69/buet-air/blob/main/Asef/core/safety_guard.py): policy filter · Screens generated text for leakage and unsafe guidance. · `Asef/core/safety_guard.py`

### LLM integration

External model adapter and prompt construction.

- [Gemini client](https://github.com/asef69/buet-air/blob/main/Asef/llm/client.py): model adapter · Calls the hosted Gemini model and handles structured output. · `Asef/llm/client.py`
- [Prompts](https://github.com/asef69/buet-air/blob/main/Asef/llm/prompts.py): prompt templates · Builds the instructions and context sent to the model. · `Asef/llm/prompts.py`

### Shared contracts

Common enums and reusable test fixtures.

- [Enums](https://github.com/asef69/buet-air/blob/main/Shared/models/enums.py): shared constants · Common domain labels and status values shared across modules. · `Shared/models/enums.py`
- [Sample cases](https://github.com/asef69/buet-air/blob/main/Shared/tests/SUST_Preli_Sample_Cases.json): test fixtures · Reference cases used to validate expected behavior. · `Shared/tests/SUST_Preli_Sample_Cases.json`

### Deployment

Container and environment configuration.

- [Settings](https://github.com/asef69/buet-air/blob/main/Iztihad/config/settings.py): runtime config · Centralizes environment-driven configuration. · `Iztihad/config/settings.py`
- [Dockerfile](https://github.com/asef69/buet-air/tree/main/Iztihad/infra/Dockerfile): container build · Builds the service image for deployment. · `Iztihad/infra/Dockerfile`
- [Compose](https://github.com/asef69/buet-air/blob/main/Iztihad/infra/docker-compose.yaml): local deployment · Runs the service with container orchestration locally. · `Iztihad/infra/docker-compose.yaml`
- [Vercel config](https://github.com/asef69/buet-air/blob/main/vercel.json): deployment config · Deployment configuration for the hosted environment. · `vercel.json`

### Validation

Repository-level tests and sample cases.

- [API tests](https://github.com/asef69/buet-air/blob/main/Shared/tests/test_api.py): integration tests · Exercises the public ticket analysis API. · `Shared/tests/test_api.py`
- [Core tests](https://github.com/asef69/buet-air/blob/main/Shared/tests/test_classifier.py): unit tests · Covers classifier and evidence analysis behavior. · `Shared/tests/test_classifier.py`
- [Safety tests](https://github.com/asef69/buet-air/blob/main/Shared/tests/test_safety.py): unit tests · Checks the safety and compliance filter. · `Shared/tests/test_safety.py`

## Connections

- Main app → Routes: registers · Bootstraps the HTTP routes into the application.
- Main app → Middleware: uses · Applies cross-cutting request handling.
- Routes → Schemas: validates · Shapes incoming and outgoing payloads.
- Routes → Analyzer: calls · Hands ticket requests to the domain orchestrator.
- Analyzer → Classifier: classifies · Determines the ticket or dispute type.
- Analyzer → Evidence engine: grounds · Extracts factual transaction evidence.
- Analyzer → Prompts: prepares · Assembles structured prompt context.
- Analyzer → Gemini client: invokes · Sends the analysis context to Gemini.
- Prompts → Gemini client: feeds · Provides the model instructions and context.
- Analyzer → Reply builder: formats · Turns analysis output into a support reply.
- Analyzer → Safety guard: filters · Applies policy checks before returning text.
- Reply builder → Safety guard: checks · Routes the generated reply through safety review.
- Safety guard → Routes: returns · Produces the final safe response for the client.
- Classifier → Enums: uses · Shares canonical labels and statuses.
- Evidence engine → Enums: uses · Aligns extracted evidence with shared domain values.
- Schemas → Enums: uses · Reuses common contract values in API models.
- API tests → Routes: exercises · Validates the public endpoint behavior.
- Core tests → Classifier: tests · Checks classification behavior.
- Core tests → Evidence engine: tests · Checks evidence extraction and matching.
- Safety tests → Safety guard: tests · Checks safety filtering behavior.
- Core tests → Sample cases: uses · Loads reference cases for regression coverage.
- Settings → Main app: configures · Supplies runtime settings to the service.
- Dockerfile → Main app: packages · Containerizes the API service.
- Compose → Dockerfile: runs · Coordinates the local containerized deployment.
- Vercel config → Main app: deploys · Defines hosted deployment entry behavior.