​

Architecture Overview

​

Three-Layer Architecture

Routes Layer (HTTP)          Flask-RESTX, request/response
       |
Service Layer (Logic)        Business logic, orchestration
       |
Data Layer (Database)        SQL, database connections

​

Routes Layer

• Parses and validates request payloads
• Maps HTTP inputs to domain request models
• Calls the service layer
• Returns standardized responses
• Does NOT contain business logic or database calls

​

Service Layer

• Implements domain logic and orchestration
• Coordinates between multiple data layers when needed
• Does NOT contain raw SQL
• Uses the data layer for persistence

​

Data Layer (Repository / DAO)

• Encapsulates SQL and database connections
• Returns domain entities or simple DTOs
• Does NOT call external APIs or LLMs

​

Active Domains

​

Dependency Injection

• Unit testing with mocked dependencies
• Swapping implementations (e.g., local vs external knowledge base)
• Clear dependency graphs between components

​

Error Handling

{
  "error": "ERROR_CODE",
  "message": "Human-readable description",
  "code": "SPECIFIC_CODE"
}

• VALIDATION_ERROR (400) — Invalid input
• UNAUTHORIZED (401) — Missing or invalid auth
• AUTHORIZATION_ERROR (403) — Insufficient permissions
• RESOURCE_NOT_FOUND (404) — Entity not found
• SERVICE_ERROR (500) — Internal failure

​

External Dependencies