docs: experiment with generated documentation, let's keep it in git for

now

docs/by-gemini/architecture.md

@@ -0,0 +1,48 @@
+# 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. |
+```