System_Architecture

🏛️ System Architecture Design (การออกแบบสถาปัตยกรรมระบบ)

---

🇹🇭 ภาษาไทย (For User)

📌 1. หลักการสถาปัตยกรรมสะอาด (Clean Architecture Principles)

SplitDee ใช้หลักการ Clean Architecture ทั้งในฝั่งระบบหลังบ้าน (FastAPI) และระบบส่วนหน้า (Flutter) เพื่อให้แน่ใจว่าตรรกะทางธุรกิจหลัก (Business Logic) จะไม่ขึ้นกับไลบรารีภายนอก ฐานข้อมูล หรือเฟรมเวิร์กของส่วนแสดงผล ทำให้การอัปเกรดระบบ การเปลี่ยนฐานข้อมูล และการเขียนชุดทดสอบ (Unit Test) ทำได้ง่ายและเสถียร

+-----------------------------------------------------------+
| Presentation / UI (FastAPI Routers / Flutter Widgets)     |
|       ↓                                                   |
| Use Cases / Application Rules (Business Logic Flows)      |
|       ↓                                                   |
| Domain / Core Business Entities (Entities & Interfaces)   |
+-----------------------------------------------------------+
*ทิศทางการเชื่อมต่อ (Dependency Arrow) ต้องชี้เข้าสู่ศูนย์กลาง (Domain) เสมอ*

---

🐍 2. สถาปัตยกรรมหลังบ้าน (Backend - FastAPI)

ระบบหลังบ้านแบ่งรหัสออกเป็น 4 ชั้นหลัก:

1. Domain Layer (ชั้นแกนกลาง): ประกอบด้วย Entities หลัก (เช่น ผู้ใช้, บิล, สัตว์เลี้ยง) และ Interfaces (ระบุการเข้าถึงข้อมูลแต่ยังไม่ระบุการทำงานจริง) ห้ามนำเข้า (import) แพ็กเกจของภายนอกในชั้นนี้
2. Use Cases Layer (ชั้นตรรกะทางธุรกิจ): ควบคุมการไหลของข้อมูล เช่น ขั้นตอนการแบ่งบิลเงิน, ขั้นตอนการสั่งจ่าย, การคำนวณการเติบโตของสัตว์เลี้ยง
3. Infrastructure Layer (ชั้นโครงสร้างพื้นฐาน): จัดการการเข้าถึงข้อมูลจริง (PostgreSQL/SQLAlchemy Repository), การเข้ารหัสผ่าน (JWT), การประมวลผล AI ตรวจสอบภาพสลิป และระบบส่งเมล/แจ้งเตือน
4. Presentation Layer (ชั้นติดต่อผู้ใช้): รับคำขอ HTTP ผ่าน FastAPI API Routers, แปลงคลาสด้วย Pydantic (Schemas) และส่งคืนผลลัพธ์เป็น JSON

---

🐦 3. สถาปัตยกรรมหน้าบ้าน (Frontend - Flutter)

ระบบหน้าบ้านแบ่งโครงสร้างเป็น 3 ชั้น:

1. Domain Layer: นิยาม Entity ของข้อมูลแอป และ Usecases ในหน้าจอ รวมทั้ง abstract repository
2. Data Layer: จัดการการร้องขอ API ผ่าน HTTP Client, โครงสร้างข้อมูล JSON (Models) และการบันทึกข้อมูลในเครื่อง (Secure Storage)
3. Presentation Layer: ส่วนวาดหน้าจอ (Pages/Widgets) และการจัดการสถานะหน้าจอ (State Management) โดยเลือกใช้ Riverpod เพื่อจัดการสภาวะหน้าจอและการแจ้งเตือน

---

🔄 4. แผนผังการไหลของข้อมูล (Data Flow Diagram)

ตัวอย่างการไหลของข้อมูลเมื่อผู้ใช้ทำรายการบันทึกบิลค่าใช้จ่าย:

sequenceDiagram
    participant User as ผู้ใช้ (Flutter UI)
    participant Controller as State Controller (Riverpod)
    participant Router as FastAPI Router
    participant UseCase as CreateBill UseCase
    participant DB as PostgreSQL DB
    participant AI as AI Service (OCR/Slip)

    User->>Controller: กรอกรายละเอียดและยืนยันสร้างบิล
    Controller->>Router: HTTP POST /api/v1/groups/{id}/bills
    Router->>UseCase: เรียกใช้ฟังก์ชันธุรกิจ
    UseCase->>DB: บันทึกข้อมูลบิลลงฐานข้อมูล
    UseCase->>AI: (ถ้ามีการแนบใบเสร็จ) ประมวลผลรูปภาพบิล
    AI-->>UseCase: ส่งผลวิเคราะห์ข้อความกลับมา
    UseCase-->>Router: ส่งคืนข้อมูลบิลที่คำนวณสัดส่วนแล้ว
    Router-->>Controller: ส่งข้อมูล JSON ผลลัพธ์
    Controller-->>User: แสดงผลบิลที่สร้างสำเร็จบนแอปมือถือ

---

🇬🇧 English (For AI Agents)

📌 1. Clean Architecture Design

SplitDee applies Clean Architecture pattern for both backend (FastAPI) and frontend (Flutter) to achieve a decoupled, testable, and highly maintainable codebase.

• Dependency Rule: Source code dependencies must point inwards. Outer layers (UI, databases, frameworks) can depend on inner layers (Use Cases, Domain), but inner layers must never depend on outer layers.

🐍 2. Backend Layer Breakdown (FastAPI)

• app/domain: Contains core business model models (Entities) and repository interfaces. Clean from framework imports.
• app/use_cases: Application business rules. Coordinates the flow of data to and from the domain entities.
• app/infrastructure: Framework-specific implementations. Includes PostgreSQL database drivers, SQLAlchemy ORM mappings, external AI integration clients (OCR, slip scanner), JWT authorization providers, and Firebase messaging integration.
• app/presentation: FastAPI endpoints, routers, middleware, and request/response validation schemas (Pydantic models).

🐦 3. Frontend Layer Breakdown (Flutter)

• lib/domain: Entities representing UI-agnostic models, abstract repositories, and business use cases.
• lib/data: API clients, data transfer models (DPOs with JSON serialization), local secure storage, and repository implementations.
• lib/presentation: Widgets, screens, layouts, and Riverpod State Management controllers.

🤖 4. External Integration Points

• AI Verification Service: Processes slip transaction IDs and amounts. Interfaces with bank validation APIs using an adapter pattern.
• Firebase Cloud Messaging: Delivers real-time notifications for system events (such as debt updates or Mochi pet actions).
• PromptPay QR Code Engine: Generates custom EMV Co-compliant QR payloads dynamically for swift in-app scanning.