49 lines
2.4 KiB
Markdown
49 lines
2.4 KiB
Markdown
# 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. |
|
|
```
|