System Component Diagram

🏛️ COMPONENT_DIAGRAM.md - System Component Diagram (แผนภาพคอมโพเนนต์ของระบบ)

This document illustrates the internal component layout and module interfaces of the SplitDee frontend and backend application.
เอกสารฉบับนี้แสดงแผนผังขอบเขตสัดส่วนระบบคอมโพเนนต์และการต่อเชื่อมโมดูลของแอป SplitDee หน้าบ้านและหลังบ้าน

---

🇹🇭 ภาษาไทย (สำหรับผู้ใช้งาน)

📊 สรุปโครงสร้างคอมโพเนนต์ย่อยของระบบ

• ฝั่งแอปโมบาย (Flutter Mobile Client Components):
  • UI Widgets & Pages: วาดจัดหน้าจอหลักของแอป เช่น หน้าหลักแสดงสถานะสัตว์เลี้ยงโมจิ และหน้าตั้งหารบิล
  • Riverpod State Controllers: จัดแจงและคอยประมวลจำสถานะตัวแปรเพื่อสั่งอัปเดตหน้าจอทันเมื่อมีการแก้ไข
  • Local Secure Storage: จัดเก็บและรักษาความปลอดภัยตั๋ว JWT Access/Refresh Token บนความปลอดภัยของโทรศัพท์มือถือ
  • HTTP Client (API client): เชื่อมต่อส่ง REST API และทรานแซกชัน หรือต่อ WebSockets รับส่งแชทสนทนากลุ่มสด
  • Camera Picker: ตัวดึงประตูกล้องมือถือถ่ายภาพสลิปใบเสร็จ
• ฝั่งแอปหลังบ้าน (FastAPI Backend Components):
  • API Routers: จุดเชื่อมต่อคัดกรองขอยิง API ชี้เป้าตัวนำทางเข้าระบบย่อย
  • Auth Guard: ระบบป้องกันและถอดรหัส Token ความปลอดภัยเทียบกับ Redis Blacklist
  • UseCase Engine: ขุมพลังแกนกลางประมวลตรรกะธุรกิจเดี่ยวๆ (เช่น การแชร์เงิน การตรวจสอบสลิป) ปราศจากการยึดติดฐานข้อมูลภายนอก
  • SQLAlchemy ORM: แปลคลาสข้อมูลโดเมนโดเมน ไปสั่งคำสั่งคิวรีฐานข้อมูล PostgreSQL
  • AI OCR Service: ตัวคุมงานสกัดแสกนสลิปธนาคารและกรองรูปภาพ
• คลังข้อมูลและผู้ให้บริการภายนอก (Infrastructure):
  • PostgreSQL Database: ฐานข้อมูลเชิงสัมพันธ์เก็บตารางหลัก
  • Redis Cache: หน่วยจำแรมบันทึก Token ยกเลิกด่วน
  • Bank Verification API & FCM: API สลีปธนาคารภายนอก และคลาวด์ส่ง Push แจ้งเตือนด่วนของกูเกิล

---

🇬🇧 English (For AI Agents)

🗺️ Component Diagram

graph TD
    subgraph MobileClient [Flutter Mobile Client Components]
        UI[UI Widgets & Pages]
        StateCtrl[Riverpod State Controllers]
        SecureStorage[Local Secure Storage]
        HTTPClient[API client - HTTP/WS]
        CameraPicker[Camera & Gallery Picker]
        
        UI --> StateCtrl
        StateCtrl --> SecureStorage
        StateCtrl --> HTTPClient
        HTTPClient --> CameraPicker
    end

    subgraph BackendApp [FastAPI Backend Components]
        Router[API Routers & Controllers]
        AuthGuard[Auth Middleware / JWT Validator]
        UseCaseEngine[Use Case business logic Engine]
        SQLAlchemyORM[SQLAlchemy ORM & Models]
        SecurityUtil[Hasher & Token Generators]
        OCRService[AI OCR & Image Pre-processor]

        Router --> AuthGuard
        Router --> UseCaseEngine
        UseCaseEngine --> SQLAlchemyORM
        UseCaseEngine --> SecurityUtil
        UseCaseEngine --> OCRService
    end

    subgraph Infrastructure [Data Storage & External Services]
        Postgres[(PostgreSQL Database)]
        Redis[(Redis Cache)]
        BankAPI[Bank Slip verification API]
        FCM[Firebase Messaging Server]
    end

    HTTPClient -- HTTPS REST / WebSocket --> Router
    SQLAlchemyORM -- pg_driver --> Postgres
    AuthGuard -- Redis Client --> Redis
    UseCaseEngine -- HTTP Client --> BankAPI
    UseCaseEngine -- Firebase Admin SDK --> FCM

📝 Component Specifications

• 1. Flutter Mobile Client Components
  • UI Widgets & Pages: Renders pages for Dashboard, Group Details, and Bills.
  • Riverpod State Controllers: Manages local state lifecycle, reloading UI widgets on updates.
  • Local Secure Storage: Securely persists JWT credentials on-device.
  • HTTP/WS Client: Executes async HTTP queries and WebSocket chat connections.
• 2. FastAPI Backend Components
  • API Routers: Directs requests to specific presentation layer schemas and controllers.
  • Auth Guard: Middleware decoding credentials, checking Redis blacklists, and injecting user context.
  • UseCase Engine: Contains the pure domain business rules (creating bills, verifying slips) decoupled from ORMs.
  • SQLAlchemy ORM: Map models to PostgreSQL relational tables.
  • AI OCR Service: Processes receipt images and extracts Mini-QR identifiers.