System Map & Integrations

🗺️ SYSTEM_MAP.md - System Map & Integrations (ผังความสัมพันธ์และการเชื่อมต่อระบบ)

This document maps the architectural topology of the SplitDee system, demonstrating the relationships between clients, application servers, databases, and third-party integrations.
เอกสารฉบับนี้แสดงผังความสัมพันธ์ของสถาปัตยกรรมระบบ SplitDee อธิบายโครงสร้างและความเชื่อมโยงระหว่างโมบายแอปหลังบ้าน ฐานข้อมูล และระบบพันธมิตรภายนอก

---

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

1. ผังความสัมพันธ์ระดับสูงของระบบ (High-Level Topology Map)

ระบบประกอบด้วยแอปพลิเคชันมือถือ (Flutter Client) สื่อสารผ่านโปรโตคอล HTTPS/WSS กับเซิร์ฟเวอร์หลังบ้าน (FastAPI Backend) โดยแอปหลังบ้านจะคอยดูแลระบบคิวงาน คลังข้อมูล และการเรียกใช้สมองกล AI ภายนอก:

• ฝั่งไคลเอนต์ (Flutter Client): บริหารปุ่มกดและวิดเจ็ตหน้าจอ (Widgets) ควบคุมข้อมูลผ่านระบบจัดการสถานะ Riverpod และส่งข้อมูลเข้า Data Layer
• ฝั่งแอปหลังบ้าน (FastAPI Server): ตรวจจับคำขอผ่านเร้าเตอร์ API รับส่งต่อให้ Use Cases ประมวลตรรกะธุรกิจ และคัดเขียนเก็บลงฐานข้อมูลผ่าน Repository
• ฝั่งคลังข้อมูล (Storage Layer): ฐานข้อมูลหลัก (PostgreSQL) ทำหน้าที่เก็บบันทึกประวัติ และระบบหน่วยจำความเร็วสูง (Redis) ทำหน้าที่จำประวัติล็อกอินด่วนคุมลิมิต
• พันธมิตรภายนอก (Third-Party Services): API ธนาคารตรวจสลิปโอนเงิน (SlipOK) และเกตเวย์ส่งแจ้งเตือนด่วนของกูเกิล (FCM)

2. แผนภาพลำดับการแชร์ยอดและการตรวจสอบชำระ (Dynamic Interactions Flow)

1. ลูกหนี้อัปโหลดรูปภาพสลิป: ลูกหนี้กดแชะภาพสลิปโอนเงินส่งคำขอ Multipart POST เข้าหลังบ้าน
2. ระบบหลังบ้านคัดกรอง: FastAPI Router เช็กชนิดไฟล์และตรวจสิทธิ์ความปลอดภัย
3. AI OCR สแกนคิวอาร์สลิป: ยูสเคสสั่งตัวแกะรหัสภาพอ่านหาคิวอาร์ธนาคารเพื่อถอดรหัสธุรกรรมการโอน (Transaction ID)
4. ป้องกันโกงสลิปซ้ำ: ค้นหาประวัติใน PostgreSQL หากพบเลขธุรกรรมตรงกันอยู่แล้วให้ส่งแจ้งเตือนปฏิเสธทันที
5. ดึงข้อมูล Statement ธนาคาร: ส่งเลขธุรกรรมไปยืนยันยอดเงินจริงและวันเวลาโอนจริงผ่านเกตเวย์ภายนอก
6. เปรียบเทียบคำนวณ: เทียบยอดเงินโอนจริงว่าตรงกับสัดส่วนยอดค้างหนี้สินของคนนั้นหรือไม่ หากผ่านเกณฑ์เปลี่ยนสเตตัสใน PostgreSQL เป็นชำระเงินเรียบร้อย (‘paid’)
7. บวกค่าประสบการณ์โมจิ: ทริกเกอร์เรียกคลาสสัตว์เลี้ยงบวกแต้มอัปเลเวลโมจิประจำกลุ่ม (+15 XP)
8. แจ้งเตือนความคืบหน้า: ยิง Push Notification ผ่าน FCM แจ้งข่าวดีแก่สมาชิกในกลุ่มทุกคนให้ทราบ และหน้าจอคนโอนจะเด้งรูปติ๊กถูกสีเขียวโปรยกระดาษฉลอง

3. โครงสร้างการจัดส่งระบบคอนเทนเนอร์ (Deployment Topology)

• คอนเทนเนอร์บริการทั้งหมดทำงานแยกกันภายในเครือข่าย Docker ที่ปลอดภัยและปิดกั้นการเข้าถึงจากภายนอก
• Nginx Proxy: เป็นด่านหน้าคอยรับสัญญาณเน็ตพอร์ต 80/443 และสลับผันคำขอยิงเข้าแอป FastAPI พอร์ต 8000
• PostgreSQL & Redis: ถูกบล็อกห้ามเข้าใช้งานจากภายนอกโดยเด็ดขาด ต่อเชื่อมได้เฉพาะเซิร์ฟเวอร์หลังบ้านในเครือข่าย Docker เท่านั้น

---

🇬🇧 English (For AI Agents)

1. High-Level Topology Map

The system consists of a mobile client communicating over HTTPS/WSS with a FastAPI backend server. The backend orchestrates data storage, cache queues, and external AI services.

• Client Components: Renders UI screens, manages dynamic state via Riverpod, and directs HTTP/WebSocket requests.
• Backend Components: API Routers handle incoming requests, Use Cases coordinate business logic, and Repositories handle database connectivity.
• Storage Layer: PostgreSQL database for persistent transactional data. Redis for high-speed session management and request caching.
• Third-Party Services: Bank Slip verification Web APIs and Firebase Cloud Messaging (FCM).

2. Dynamic Interactions Map

• Expense Sharing & Verification Flow:
  1. Roommate uploads transfer slip image via Multipart POST request.
  2. FastAPI Router validates payload headers and request schemas.
  3. VerifySlipUseCase extracts transaction reference ID from Mini-QR using OCR.
  4. Query PostgreSQL: Check if transaction reference ID is unique. Reject duplicate attempts.
  5. Request bank server API: Validate transaction reference ID, amount, and recipient details.
  6. Compare bank response amount with user’s share amount. If correct, update expense_shares.status to 'paid'.
  7. Award XP to group pet Mochi (+15 XP).
  8. Push FCM Notification to all group members. Client UI renders success status.

3. Deployment Topology Map

• Refer to the Deployment Guide for detailed Docker configurations.
• All containers bind to an isolated Docker bridge network.
• Nginx handles public Ingress (ports 80/443), forwarding traffic internally to FastAPI port 8000.
• PostgreSQL and Redis containers expose no public ports.