How ayhanarashtasin/sust-preliminary-hackathon works
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: ticketController.js Ticket Controller · index.html Test UI · api.js API Routes · server.js Server
Components 19
HTTP API
Express entrypoint, routing, and request/response boundary
- Server · Bootstraps middleware, security, CORS, rate limiting, routes, and error handling
src/server.js - API Routes · Exposes health and analyze-ticket endpoints
src/routes/api.js - Ticket Controller · Orchestrates validation, rule engine, LLM analysis, fallback, and final response assembly
src/controllers/ticketController.js - Health Check · Simple liveness endpoint
- Analyze Ticket · Primary complaint analysis endpoint
Analysis Pipeline
Validation, deterministic rules, LLM reasoning, merge, and safety checks
- Request Schema · Validates incoming complaints and separates malformed input from empty complaints
src/schemas/validation.js - Rule Engine · Matches evidence, extracts amounts, classifies patterns, and emits confidence signals
src/services/ruleEngine.js - LLM Service · Sends complaint context to Groq-hosted Llama models and expects structured JSON
src/services/aiService.js - Confidence Merge · Combines rule output and LLM output, letting strong rules override risky or uncertain model fields
- Output Validation · Revalidates merged results, enforcing enums, required fields, and allowed transaction IDs
- Safety Checker · Scrubs unsafe customer-facing prose and replaces risky generations with safe boilerplate
src/services/safetyChecker.js - Deterministic Fallback · 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 · Minimal browser interface for manual testing and demos
public/index.html - UI Script · Front-end behavior for the manual test page
public/app.js - Styles · Presentation styles for the manual test UI
public/style.css - Sample Cases · Example complaints for exercising the pipeline
SUST_Preli_Sample_Cases.json - Sample Output · Representative expected responses for illustration and testing
sample_output.json
Deployment
Container packaging and runtime configuration
- Dockerfile · Packages the service in node:18-alpine and exposes the API port
Dockerfile - Env Config · External configuration for API key and port
.env.example
Connections 22
- 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