pos-system/services/_template/ARCHITECTURE.md

Service Template Architecture / Kiến Trúc Template Dịch Vụ

This document describes the high-level architecture of the microservice template. Tài liệu này mô tả kiến trúc cấp cao của template microservice.

Component Diagram / Sơ đồ Thành phần

graph TD
    Client[Client / External Service]
    
    subgraph "Service Boundary / Phạm vi Dịch vụ"
        LB[Load Balancer / Ingress]
        
        subgraph "Application / Ứng dụng"
            Middleware[Middleware Layer]
            Router[Router Layer]
            Controller[Controller Layer]
            Service[Service Layer]
            Repo[Repository / Data Access]
        end
        
        Config[Configuration Manager]
        Logger[Logger]
        Metrics[Prometheus Metrics]
    end
    
    DB[(PostgreSQL Database)]
    Redis[(Redis Cache / State)]
    Jaeger[Jaeger Tracing]
    
    Client -->|HTTP Request| LB
    LB -->|Traffic| Middleware
    
    Middleware -->|Auth & Validation| Router
    Middleware -.->|Track| Metrics
    Middleware -.->|Log| Logger
    
    Router -->|Dispatch| Controller
    
    Controller -->|Business Logic| Service
    Service -->|Data Query| Repo
    Service -->|Cache| Redis
    
    Repo -->|SQL| DB
    
    Config -->|Settings| Application
    Application -.->|Traces| Jaeger

Request Flow / Luồng Xử Lý Request

1. Request Entry: Use hits ingress/load balancer.

   • Đầu vào: Người dùng gửi request đến ingress/load balancer.

2. Middleware:

   • Helmet: Secures HTTP headers. (Bảo mật header HTTP)
   • Rate Limiter: Prevents abuse. (Ngăn chặn spam/abuses)
   • Logger/Metrics: records start time. (Ghi nhận thời gian bắt đầu)

3. Router & Controller:

   • Routes request to specific handler. (Định tuyến đến handler cụ thể)
   • Controller orchestrates response. (Controller điều phối phản hồi)

4. Service Layer:

   • Contains core business logic. (Chứa logic nghiệp vụ cốt lõi)
   • Independent of transport layer (HTTP). (Độc lập với lớp giao thức)

5. Data Access:

   • Prisma ORM communicates with PostgreSQL. (Prisma giao tiếp với PostgreSQL)

6. Response:

   • Formatted JSON response sent back. (Trả về JSON đã định dạng)
   • Metrics/Logs finalized. (Hoàn tất ghi metrics/log)