# ayhanarashtasin/sust-preliminary-hackathon architecture

> Architecture diagram of the GitHub repository ayhanarashtasin/sust-preliminary-hackathon, 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/ayhanarashtasin/sust-preliminary-hackathon
- Repository: https://github.com/ayhanarashtasin/sust-preliminary-hackathon

## Overview

1. **Repository shape**
   - This is a Node.js 18+ Express API with a small static frontend for manual testing.
   - The core architecture lives under `src/`; `public/` is auxiliary and `Dockerfile` packages the service for deployment.

2. **Entry point and HTTP boundary**
   - `src/server.js` wires Express middleware, security headers, CORS, rate limiting, JSON parsing, route mounting, and error handlers.
   - `src/routes/api.js` exposes the two public endpoints: `GET /health` and `POST /analyze-ticket`.

3. **Request validation boundary**
   - `src/schemas/validation.js` uses Zod to enforce request shape before any analysis runs.
   - It distinguishes malformed input from semantically empty complaints, so the API can return `400` vs `422` deterministically.

4. **Controller orchestration**
   - `src/controllers/ticketController.js` is the main workflow coordinator.
   - It receives validated requests, calls the rule engine first, then the LLM service, applies fallback behavior if AI fails, and returns the final response object.

5. **Deterministic pre-analysis**
   - `src/services/ruleEngine.js` performs evidence matching and classification without AI.
   - It extracts monetary amounts, handles English and Bangla numerals, matches against `transaction_history`, and looks for keywords/patterns such as wrong transfer, payment failure, duplicate payment, and phishing.
   - The rule engine also emits confidence flags that control whether its findings override the model.

6. **LLM analysis layer**
   - `src/services/aiService.js` sends the complaint, transaction history, and rule-engine hints to Groq-hosted Llama models.
   - The LLM is used for nuanced classification, reasoning text, and customer-facing prose, but it must return structured JSON.

7. **Confidence-gated merge**
   - The final result is not purely model-driven.
   - If the rules are confident, they override the LLM on key fields like transaction identity, case type, and risky phishing classifications.
   - If rules are uncertain, the validated LLM output is preferred.
   - Department routing is derived from the final case type, keeping that mapping deterministic.

8. **Response integrity checks**
   - The merged output is validated again with Zod to enforce enums and required fields.
   - This prevents invalid `case_type`, `department`, `severity`, or `evidence_verdict` values from leaving the service.
   - Hallucinated transaction IDs are rejected if they are not present in the provided history.

9. **Safety layer**
   - `src/services/safetyChecker.js` is a post-processing guard that scans generated customer-facing text for unsafe phrases.
   - It blocks credential requests, refund promises, and third-party redirections by replacing unsafe content with guaranteed-safe boilerplate.
   - This sits after the model specifically to catch prompt injection or unsafe generation that earlier layers missed.

10. **Fallback and resilience**
    - If the LLM times out, rate-limits, returns invalid JSON, or fails validation, the controller falls back to a deterministic response based on rule-engine output.
    - The service is designed to never crash on valid input and to avoid exposing internals in errors.

11. **External dependency**
    - Groq Cloud is the only major external runtime dependency affecting the architecture.
    - The service uses a primary and fallback Llama model, with short per-call timeouts and retry/cascade behavior to keep latency bounded.

12. **Static test frontend and sample data**
    - `public/` contains a minimal browser UI for manual testing and demoing the API.
    - `SUST_Preli_Sample_Cases.json` and `sample_output.json` are fixture-like assets for exercising the pipeline and illustrating expected responses.

13. **Deployment boundary**
    - The app is containerized with `node:18-alpine` in `Dockerfile`.
    - Runtime configuration is externalized through environment variables, mainly `GROQ_API_KEY` and optional `PORT`.
    - The container exposes port 3000 and is intended to run as a single API process.

Main entry points: [`src/controllers/ticketController.js`](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/controllers/ticketController.js) (Ticket Controller), [`public/index.html`](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/public/index.html) (Test UI), [`src/routes/api.js`](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/routes/api.js) (API Routes), [`src/server.js`](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/server.js) (Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_http["HTTP API"]
  node_n_server["Server<br/>express entrypoint<br/>[server.js]"]
  node_n_routes["API Routes<br/>route map<br/>[api.js]"]
  node_n_controller["Ticket Controller<br/>workflow coordinator"]
  node_n_health(("Health Check<br/>endpoint"))
  node_n_analyze(("Analyze Ticket<br/>endpoint"))
end

subgraph group_grp_analysis["Analysis Pipeline"]
  node_n_validation["Request Schema<br/>zod validation<br/>[validation.js]"]
  node_n_rule{{"Rule Engine<br/>deterministic analysis<br/>[ruleEngine.js]"}}
  node_n_ai["LLM Service<br/>groq llama client<br/>[aiService.js]"]
  node_n_merge(("Confidence Merge<br/>decision logic"))
  node_n_postval["Output Validation<br/>zod guardrail"]
  node_n_safety{{"Safety Checker<br/>text guard<br/>[safetyChecker.js]"}}
  node_n_fallback(("Deterministic Fallback<br/>resilience path"))
end

subgraph group_grp_frontend["Manual Testing"]
  node_n_ui["Test UI<br/>static frontend<br/>[index.html]"]
  node_n_ui_js["UI Script<br/>browser script<br/>[app.js]"]
  node_n_ui_css["Styles<br/>static asset<br/>[style.css]"]
  node_n_cases["Sample Cases<br/>fixture data"]
  node_n_output["Sample Output<br/>fixture data<br/>[sample_output.json]"]
end

subgraph group_grp_deploy["Deployment"]
  node_n_docker["Dockerfile<br/>container build"]
  node_n_env["Env Config<br/>runtime config<br/>[.env.example]"]
end

node_n_server -->|"mounts"| node_n_routes
node_n_routes -->|"serves"| node_n_health
node_n_routes -->|"serves"| node_n_analyze
node_n_analyze -->|"validates"| node_n_validation
node_n_validation -->|"passes"| node_n_controller
node_n_controller -->|"checks"| node_n_rule
node_n_controller -->|"calls"| node_n_ai
node_n_rule -->|"hints"| node_n_merge
node_n_ai -->|"results"| node_n_merge
node_n_merge -->|"verifies"| node_n_postval
node_n_postval -->|"sanitizes"| node_n_safety
node_n_safety -->|"returns"| node_n_controller
node_n_controller -->|"falls back"| node_n_fallback
node_n_fallback -.->|"derives from"| node_n_rule
node_n_ui -->|"uses"| node_n_ui_js
node_n_ui -->|"styles"| node_n_ui_css
node_n_ui -.->|"calls"| node_n_analyze
node_n_cases -.->|"feeds"| node_n_ui
node_n_output -.->|"illustrates"| node_n_ui
node_n_docker -->|"packages"| node_n_server
node_n_env -.->|"configures"| node_n_ai
node_n_env -.->|"configures"| node_n_server

click node_n_server "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/server.js"
click node_n_routes "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/routes/api.js"
click node_n_controller "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/controllers/ticketController.js"
click node_n_validation "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/schemas/validation.js"
click node_n_rule "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/services/ruleEngine.js"
click node_n_ai "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/services/aiService.js"
click node_n_safety "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/services/safetyChecker.js"
click node_n_ui "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/public/index.html"
click node_n_ui_js "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/public/app.js"
click node_n_ui_css "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/public/style.css"
click node_n_cases "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/SUST_Preli_Sample_Cases.json"
click node_n_output "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/sample_output.json"
click node_n_docker "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/tree/main/Dockerfile"
click node_n_env "https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/.env.example"

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_n_server,node_n_routes,node_n_controller,node_n_health,node_n_analyze toneBlue
class node_n_validation,node_n_rule,node_n_ai,node_n_merge,node_n_postval,node_n_safety,node_n_fallback toneAmber
class node_n_ui,node_n_ui_js,node_n_ui_css,node_n_cases,node_n_output toneMint
class node_n_docker,node_n_env toneRose
```

## Components

### HTTP API

Express entrypoint, routing, and request/response boundary

- [Server](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/server.js): express entrypoint · Bootstraps middleware, security, CORS, rate limiting, routes, and error handling · `src/server.js`
- [API Routes](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/routes/api.js): route map · Exposes health and analyze-ticket endpoints · `src/routes/api.js`
- [Ticket Controller](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/controllers/ticketController.js): workflow coordinator · Orchestrates validation, rule engine, LLM analysis, fallback, and final response assembly · `src/controllers/ticketController.js`
- **Health Check**: endpoint · Simple liveness endpoint
- **Analyze Ticket**: endpoint · Primary complaint analysis endpoint

### Analysis Pipeline

Validation, deterministic rules, LLM reasoning, merge, and safety checks

- [Request Schema](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/schemas/validation.js): zod validation · Validates incoming complaints and separates malformed input from empty complaints · `src/schemas/validation.js`
- [Rule Engine](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/services/ruleEngine.js): deterministic analysis · Matches evidence, extracts amounts, classifies patterns, and emits confidence signals · `src/services/ruleEngine.js`
- [LLM Service](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/services/aiService.js): groq llama client · Sends complaint context to Groq-hosted Llama models and expects structured JSON · `src/services/aiService.js`
- **Confidence Merge**: decision logic · Combines rule output and LLM output, letting strong rules override risky or uncertain model fields
- **Output Validation**: zod guardrail · Revalidates merged results, enforcing enums, required fields, and allowed transaction IDs
- [Safety Checker](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/src/services/safetyChecker.js): text guard · Scrubs unsafe customer-facing prose and replaces risky generations with safe boilerplate · `src/services/safetyChecker.js`
- **Deterministic Fallback**: resilience path · Produces a rule-based response when the LLM times out, fails, or returns invalid content

### Manual Testing

Static browser UI and sample data for exercising the API

- [Test UI](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/public/index.html): static frontend · Minimal browser interface for manual testing and demos · `public/index.html`
- [UI Script](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/public/app.js): browser script · Front-end behavior for the manual test page · `public/app.js`
- [Styles](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/public/style.css): static asset · Presentation styles for the manual test UI · `public/style.css`
- [Sample Cases](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/SUST_Preli_Sample_Cases.json): fixture data · Example complaints for exercising the pipeline · `SUST_Preli_Sample_Cases.json`
- [Sample Output](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/sample_output.json): fixture data · Representative expected responses for illustration and testing · `sample_output.json`

### Deployment

Container packaging and runtime configuration

- [Dockerfile](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/tree/main/Dockerfile): container build · Packages the service in node:18-alpine and exposes the API port · `Dockerfile`
- [Env Config](https://github.com/ayhanarashtasin/sust-preliminary-hackathon/blob/main/.env.example): runtime config · External configuration for API key and port · `.env.example`

## Connections

- Server → API Routes: mounts · Registers the API router on the Express app
- API Routes → Health Check: serves · Health endpoint
- API Routes → Analyze Ticket: serves · Ticket analysis endpoint
- Analyze Ticket → Request Schema: validates · Checks request shape before analysis
- Request Schema → Ticket Controller: passes · Validated ticket payload reaches the workflow controller
- Ticket Controller → Rule Engine: checks · Runs deterministic classification first
- Ticket Controller → LLM Service: calls · Invokes Groq Llama analysis with ticket context
- Rule Engine → Confidence Merge: hints · Provides evidence, confidence, and override signals
- LLM Service → Confidence Merge: results · Provides structured model output
- Confidence Merge → Output Validation: verifies · Ensures merged response is schema-safe
- Output Validation → Safety Checker: sanitizes · Post-processes customer-facing text for unsafe content
- Safety Checker → Ticket Controller: returns · Final safe response is handed back to the controller
- Ticket Controller → Deterministic Fallback: falls back · Uses deterministic output when LLM or validation fails
- Deterministic Fallback → Rule Engine: derives from · Fallback response is based on rule-engine findings
- Test UI → UI Script: uses · Browser page behavior
- Test UI → Styles: styles · Static presentation layer
- Test UI → Analyze Ticket: calls · Manual testing client submits analysis requests
- Sample Cases → Test UI: feeds · Example inputs for manual runs
- Sample Output → Test UI: illustrates · Expected response examples
- Dockerfile → Server: packages · Container runs the API process
- Env Config → LLM Service: configures · Supplies API key and runtime settings
- Env Config → Server: configures · Supplies port and process settings