fuj-management/docs/by-gemini/architecture.md

System Architecture

The FUJ Management system is designed around a "Sheet-as-a-Database" architecture. This allows for easy manual editing and transparency while enabling powerful automation.

🔄 High-Level Data Flow

graph TD
    Fio[Fio Bank API] -->|Sync Script| GS(Google Spreadsheet)
    Att[Attendance Sheet] -->|CSV Export| App(Flask Web App)
    GS -->|API Fetch| App
    App -->|Display| UI[Manager Dashboard]
    GS -.->|Manual Edits| GS
    App -->|Generate| QR[QR Codes for Members]

1. Data Ingestion (Bank to Sheet)

The synchronization pipeline moves raw bank data into a structured format:

• sync_fio_to_sheets.py fetches transactions and appends them to the "Transactions" sheet.
• Each transaction is assigned a unique Sync ID to prevent duplicates.
• infer_payments.py processes new rows, attempting to fill the Person, Purpose, and Inferred Amount columns based on the message and sender.

2. Logic & Reconciliation

The core logic resides in shared Python scripts:

• Attendance: attendance.py pulls the latest practice data from a separate attendance sheet and calculates expected fees (e.g., 0/200/750 CZK rules).
• Matching: match_payments.py performs the "heavy lifting" by correlating members, months, and payments. It handles partial payments, overpayments (credits), and manual exceptions.

3. Presentation Layer

The Flask application (app.py) serves as the primary interface:

• Fees View: Shows attendance-based charges.
• Reconciliation View: The main "truth" dashboard showing balance per member.
• Payments View: Historical list of transactions grouped by member.

🛡 Security & Authentication

• Fio Bank: Authorized via a private API token (kept in .secret/).
• Google Sheets: Authenticated via a Service Account or OAuth2 (using .secret/fuj-management-bot-credentials.json).
• Environment: Secrets are never committed; the .secret/ directory is git-ignored.

🧩 Key Components

Component	Responsibility
Google Spreadsheet	Unified source of truth for transactions and manual overrides.
scripts/	A suite of CLI utilities for batch processing and data maintenance.
Flask App	Read-only views for state visualization and QR code generation.
czech_utils.py	Diacritic-normalization and NLP for Czech month/name parsing.