# 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

```mermaid
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. |
```