dinary 0.0.1__tar.gz → 0.2.0__tar.gz

dinary-0.2.0/.env.example

@@ -0,0 +1,5 @@
+# Copy to .env and fill in your values (.env is gitignored)
+#   cp .env.example .env
+DINARY_GOOGLE_SHEETS_SPREADSHEET_ID=your-spreadsheet-id-here
+DINARY_DEPLOY_HOST=ubuntu@<PUBLIC_IP>
+# DINARY_TUNNEL=tailscale  # tailscale (default) | cloudflare | none

{dinary-0.0.1 → dinary-0.2.0}/.github/workflows/ci.yml

@@ -29,7 +29,7 @@ jobs:
   matrix-build:
     strategy:
       matrix:
-        python-version: ["3.10", 3.11, 3.12]
+        python-version: [3.13, 3.14]
         platform: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.platform }}
 
@@ -48,6 +48,17 @@ jobs:
     - name: Install dependencies
       run: uv sync --frozen
 
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 22
+
+    - name: Install JS dependencies
+      run: npm ci
+
+    - name: Run JS tests
+      run: npm test
+
     - name: Test with pytest
       run: ${{ env.PYTEST_CMD }}
 
@@ -73,6 +84,17 @@ jobs:
     - name: Install dependencies
       run: uv sync --frozen
 
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 22
+
+    - name: Install JS dependencies
+      run: npm ci
+
+    - name: Run JS tests with Allure
+      run: npm test
+
     - name: Test with pytest and Allure report
       run: "${{ env.PYTEST_CMD }} --alluredir=./allure-results"
 

{dinary-0.0.1 → dinary-0.2.0}/.gitignore

@@ -16,4 +16,11 @@ pytest-coverage.txt
 **/ru/reference.md
 **/.setup-scripts/
 allure-results/
+allure-report/
 dist/
+credentials.json
+.env
+node_modules/
+data/
+_static/
+backups/

{dinary-0.0.1/.github → dinary-0.2.0}/.plans/architecture.md

@@ -11,10 +11,15 @@ prioritizing clean data model and scriptability over UI polish.
 
 ### Repositories
 
-| Repository | Language | Role                                                                                                                              |
-|---|---|-----------------------------------------------------------------------------------------------------------------------------------|
-| **dinary** | Python (FastAPI + DuckDB) | Backend — REST API, data storage, rule-based classification, dashboards, Google Sheets sync. Manuals & configs to setup frontend. |
-| **dinary-analyst** | Rust | Local desktop tool — AI classification and spending analysis via `claude -p`, communicates with dinary-server API                 |
+| Repository         | Language | Role                                                                                                                                                                       |
+|--------------------|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **dinary-server**  | Python (FastAPI + DuckDB) | Backend — REST API, data storage, rule-based classification, dashboards, Google Sheets sync. Also: PWA mobile frontend (in `static/`), user manuals (MkDocs in `docs/`), deployment configs. |
+| **dinary** | Rust | Desktop app (macOS/Windows): daemon for background AI tasks via `claude -p`, and GUI for analysis parameters, interactive results view, and quick data entry (text/PDF receipt import). Communicates with dinary-server API. |
+
+#### Documentation convention
+
+- **`docs/`** in dinary-server is a **MkDocs site** with bilingual content (`docs/src/en/`, `docs/src/ru/`). All user-facing manuals (PWA install, deployment guides, Cloudflare setup) go here. Do not place standalone markdown files directly in `docs/` — they will break the MkDocs build.
+- **`.plans/`** is for development docs (architecture, phase plans, evaluation notes). These are not published to the MkDocs site.
 
 ---
 
@@ -28,6 +33,21 @@ prioritizing clean data model and scriptability over UI polish.
 - Python-native: `import duckdb` — no server, no driver, no ORM needed.
 - At the expected scale (~30K item rows/year), every query completes in milliseconds.
 
+### Server Memory Constraint
+
+The production design must fit on an always-on VPS with **1 OCPU / 1 GB RAM**.
+This is a hard architectural constraint, not just a deployment preference.
+
+Implications:
+
+- Prefer embedded/local components over additional server daemons. DuckDB is acceptable precisely because it runs in-process and avoids a separate database service.
+- The backend must remain a **small FastAPI + DuckDB process**, not a multi-service stack.
+- Do not require Docker in production on the 1 GB instance.
+- Do not run AI/LLM workloads, heavy batch classification, or other memory-hungry jobs on the server. Those stay on the laptop-side `dinary` agent.
+- Keep background work serialized and bounded: no fan-out workers, no parallel sync pipelines, no large in-memory queues.
+- Google Sheets sync should operate on **dirty months / targeted aggregates**, not full-sheet or full-history recomputation on every request.
+- Caches must stay small and optional. Correctness must not depend on large resident in-memory datasets.
+
 ### Partitioning Strategy
 
 One DuckDB file per year:
@@ -316,32 +336,35 @@ For expenses without QR codes (cafés, services, cash payments, foreign purchase
 
 The specific mobile client is a build-time decision.
 The architecture is agnostic — the input layer is a thin client that sends structured data to the backend via a simple REST API.
-Key functional requirements regardless of the chosen tool:
 
-- Camera access for QR scanning.
-- Fast manual entry: amount + category selector + optional comment, one tap to submit.
+**Phase 0 (MVP) requirements:**
+
+- Camera access for QR scanning. In the implemented MVP the browser decodes the Serbian fiscal QR locally with `zbar-wasm`, and the client can extract amount/date from the QR URL path without waiting for a backend roundtrip.
+- Fast manual entry: amount + group selector + category selector + optional comment, one tap to submit. Entry saves instantly to IndexedDB first; network send happens only after local persistence is secured.
+- Offline data persistence via IndexedDB (reliable for installed PWAs — iOS Safari eviction only affects non-installed sites). `navigator.storage.persist()` for additional protection.
+- QR scan with parallel processing: while user selects group/category, the app finishes local QR parsing and can still fall back to backend parsing when needed.
+
+**Full requirements (Phase 3 target):**
+
+- All Phase 0 capabilities, plus:
+- Confirmation screen after QR scan: shows parsed line items, allows quick category corrections before saving.
 - Event selector: if the expense date falls within an active event's date range, auto-suggest it. If multiple active events overlap, show a dropdown. Allow manual assignment/removal.
 - Beneficiary selector: defaults to "семья", quick switch to a specific family member.
-- Confirmation screen after QR scan: shows parsed items, allows quick category corrections before saving.
 
-#### Frontend Tool Evaluation (Phase 3 prerequisite)
+#### Frontend Tool Evaluation
 
-Before building the mobile input layer, evaluate the candidate tools listed below **and research whether other tools exist** that may fit better.
-The list is a starting point, not exhaustive — the no-code/low-code landscape changes rapidly and there may be newer or niche tools
-that satisfy the requirements better than any of these.
-
-Build a minimal MVP with the most promising 1-2 candidates to compare real-world UX before committing.
+**Evaluation result**: .plans/frontend-evaluation.md
 
 **Initial candidate list:**
 
 | Tool | Type | Evaluate for |
 |------|------|-------------|
-| **Telegram Bot** | Chat-based UI | Lowest dev effort. Native camera for QR photo/URL sharing. Inline keyboards for category selection. No app install needed. Limitation: no true "form" UX — interaction is sequential, not a single screen. **Offline: does not work offline — requires internet for every interaction.** |
+| ~~**Telegram Bot**~~ | Chat-based UI | **Disqualified:** does not work offline (fails must-have #1). Lowest dev effort otherwise. Native camera for QR photo/URL sharing. Inline keyboards for category selection. No app install needed. Limitation: no true "form" UX — interaction is sequential, not a single screen. |
 | **Glide Apps** | No-code app builder (Google Sheets/SQL backend) | Can it connect to a custom REST API or DuckDB directly? Does it support camera/QR scanning? Free tier limits? Good for rapid prototyping if it can talk to our backend. Check offline support. |
 | **Retool** | Low-code internal tool builder | Strong on forms, tables, and API integration. Mobile-responsive. Free tier (5 users) is sufficient. Can it do QR scanning natively or via a component? Overkill for input-only, but could double as an admin/review UI for classifications. Check offline support — likely none. |
 | **Appsmith** | Open-source Retool alternative | Self-hostable (important for data ownership). Same evaluation criteria as Retool. Check: mobile UX quality, QR scanning support, DuckDB/REST connectivity, offline mode. |
-| **Appgyver (SAP Build Apps)** | No-code native app builder | Produces actual mobile apps. QR scanning is a built-in component. Free tier available. Evaluate: learning curve, API connectivity, ease of iteration. Has offline data storage capabilities. More effort than Telegram but better native UX. |
-| **Tally / Typeform** | Form builders | Good for quick data capture. Tally is free and supports webhooks. Can a form-based flow work for receipt entry? Likely too rigid for the QR→review→confirm flow, but worth checking for manual entry only. No offline support. |
+| ~~**Appgyver (SAP Build Apps)**~~ | No-code native app builder | **Likely disqualified:** produces native mobile apps that require App Store / Google Play publishing (fails must-have #0). QR scanning is a built-in component. Free tier available. Has offline data storage capabilities. Only viable if it supports a web/PWA deployment mode that bypasses store publishing — verify before evaluating further. |
+| ~~**Tally / Typeform**~~ | Form builders | **Disqualified:** no offline support (fails must-have #1), no QR scanning (fails must-have #6). Good for quick data capture otherwise. Tally is free and supports webhooks. Likely too rigid for the QR→review→confirm flow. |
 | **PWA (custom)** | Self-built Progressive Web App | Maximum control. Camera API for QR scanning (via `navigator.mediaDevices`). Full offline support via Service Workers + IndexedDB. Requires actual frontend development. Best long-term option if no-code tools don't fit. Works on both Android and iOS via browser. |
 
 **Evaluation criteria:**
@@ -354,9 +377,9 @@ Must-have (tool is disqualified if it fails any of these):
 3. **API connectivity** — must be able to POST structured data to a custom REST endpoint.
 4. **Free for expected load** — sustainable at zero cost for a single user with 10-20 entries/day. No "free trial" that expires.
 5. **Longevity / sustainability** — the tool must have a credible future. For open-source: sufficient community (contributors, stars, release cadence). For commercial: a clear business model and track record suggesting the free tier won't be killed. Tools that have recently been acquired, pivoted, or deprecated their free tier are high-risk.
+6. **QR scanning** — can the tool access the camera and scan a QR code to extract the URL? Required from Phase 0 (total-only extraction) through Phase 3b (full line-item flow).
 
 Important:
-6. **QR scanning** — can the tool scan a QR code and extract the URL? (must-have for Phase 3b, not required for MVP)
 7. **Speed of entry** — how many taps/screens for a manual expense? (critical for daily use adoption)
 8. **Dev effort for MVP** — how fast can a working prototype be built?
 
@@ -370,16 +393,14 @@ Nice-to-have:
 
 ### Three-tier Classification
 
-**Tier 1: Rule-based (instant, free).** `category_rules` table contains patterns (substrings or regexes) matched against item names.
-Example: pattern `MLEKO` matches category "Dairy", pattern `SREDSTVO ZA` matches "Household chemicals".
-Rules are applied immediately when items are ingested. This handles the majority of repeat purchases after an initial learning period.
+**Tier 1: Fuzzy ML based classification like in other personal expense tracking apps.
 
 **Tier 2: AI batch classification (deferred, economical).** Unclassified items (`classification_status = 'pending'`) accumulate on dinary-server throughout the day.
-When the user runs dinary-analyst (manually or via scheduler), it fetches pending items from the server API and classifies them using `claude -p`:
+When the user runs dinary (manually or via scheduler), it fetches pending items from the server API and classifies them using `claude -p`:
 
 ```bash
-# dinary-analyst fetches pending items from dinary-server
-dinary-analyst classify
+# dinary fetches pending items from dinary-server
+dinary classify
 
 # Under the hood:
 # 1. GET https://server/api/tasks/pending-classifications
@@ -442,12 +463,12 @@ The dashboard is a view layer, not a data entry point.
 
 **Purpose:** "What should I pay attention to? What can I optimize?"
 
-**Trigger:** On demand, when the user runs dinary-analyst. Not automated — the user decides when to run it.
+**Trigger:** On demand, when the user runs dinary. Not automated — the user decides when to run it.
 
 **Flow:**
-1. dinary-analyst fetches aggregated data from dinary-server:
+1. dinary fetches aggregated data from dinary-server:
    ```bash
-   dinary-analyst analyze --period 2026-Q1
+   dinary analyze --period 2026-Q1
    ```
 2. Under the hood: fetches data from server API, feeds to `claude -p`, pushes the report back to dinary-server.
 3. The report is stored on the server and optionally displayed in the dashboard.
@@ -477,12 +498,15 @@ The sync script is idempotent — running it twice produces the same result.
 
 The system is split into two parts: an always-on **backend** (VPS) that handles data ingestion and serves dashboards, and a **local agent**
 (user's laptop) that runs expensive AI tasks using the existing Claude subscription via `claude -p`.
-The backend owns the single source of truth (DuckDB).
+
+**Note on source of truth:** In Phase 0, Google Sheets is the single source of truth (the backend writes directly to it).
+Starting from Phase 1, DuckDB on the backend becomes the single source of truth, and Google Sheets becomes a read-only view layer synced from DuckDB.
+
 The local agent is stateless — it fetches tasks, processes them, and pushes results back.
 
 ```
 ┌──────────────┐         ┌─────────────────────────────────────┐
-│  dinary-app  │────────▶│  dinary (VPS)                │
+│  dinary-app  │────────▶│  dinary-server (VPS)                │
 │  (mobile)    │         │                                     │
 │              │◀────────│  FastAPI + DuckDB                   │
 └──────────────┘         │  - receives expenses from mobile    │
@@ -496,18 +520,26 @@ The local agent is stateless — it fetches tasks, processes them, and pushes re
                               task queue API (REST)
                                         │
                          ┌──────────────▼──────────────────────┐
-                         │  dinary-analyst (user's laptop)     │
+                         │  dinary (user's laptop)             │
                          │                                     │
-                         │  Rust binary + claude -p             │
-                         │  - fetch pending classification tasks│
-                         │  - AI batch classify (claude -p)     │
-                         │  - AI spending analysis (claude -p)  │
-                         │  - push results back to server API   │
-                         │  - any future AI-heavy tasks         │
+                         │  ┌─ daemon (background) ──────────┐ │
+                         │  │  Rust + claude -p               │ │
+                         │  │  - batch classification         │ │
+                         │  │  - spending analysis            │ │
+                         │  │  - push results to server API   │ │
+                         │  └────────────────────────────────┘ │
+                         │  ┌─ GUI (interactive) ────────────┐ │
+                         │  │  Rust + GUI framework           │ │
+                         │  │  - analysis params & results    │ │
+                         │  │  - quick manual entry           │ │
+                         │  │  - paste text/PDF → AI API      │ │
+                         │  │    → extract & store expense    │ │
+                         │  │  - review AI suggestions        │ │
+                         │  └────────────────────────────────┘ │
                          └─────────────────────────────────────┘
 ```
 
-### dinary (VPS)
+### dinary-server (VPS)
 
 **What it does:**
 - Accepts expenses from dinary-app (REST API).
@@ -522,26 +554,58 @@ The local agent is stateless — it fetches tasks, processes them, and pushes re
   - `POST /api/tasks/analysis-report` — stores the AI-generated report.
 
 **What it does NOT do:**
-- Any AI/LLM calls. All AI work is delegated to dinary-analyst.
+- Any AI/LLM calls. All AI work is delegated to dinary.
 
-**Hosting:** Oracle Cloud Free Tier (free ARM VM, 4 cores, 24 GB RAM — permanent free tier). Alternative: any cheap VPS, or even a Raspberry Pi at home with Cloudflare Tunnel for external access.
+**Hosting (free, always-on options):**
 
-**Accessibility:** Dashboard and API served via Cloudflare Tunnel (free, no public IP needed) or directly from the VPS.
+- **Oracle Cloud Free Tier** — AMD Micro VM (1 OCPU, 1 GB RAM, always available) is recommended for reliability. ARM A1 Flex (up to 4 OCPU, 24 GB RAM) is more powerful but often unavailable due to shared capacity pool. Run directly with uvicorn as a systemd service (no Docker — saves RAM on 1 GB instances). Docker available for local development.
+- **Self-hosted (Mac/PC)** — run locally, expose via Tailscale Serve (tailnet-only) or Cloudflare Tunnel (custom domain + Cloudflare Access). Aligns with Phase 4 architecture (dinary desktop app on the same machine).
 
-### dinary-analyst (User's Laptop)
+**Important:** sleeping/serverless hosting (Render free tier, AWS Lambda, etc.) is **not suitable** — the PWA on iOS cannot run background sync, so the server must respond within 1-2 seconds while the user still has the app open.
 
-**What it does:**
-- Runs on demand (manually or via scheduler) when the user is at the computer.
+**Accessibility:** API served via Cloudflare Tunnel or Tailscale Serve. For the current MVP, Tailscale Serve is the preferred default because it avoids public internet exposure.
+
+#### 1 GB Server Rules
+
+Because the reference production target is the Oracle AMD Micro instance, the server-side implementation must follow these rules:
+
+- Run a single app process by default. Do not scale by adding multiple uvicorn workers on the 1 GB host.
+- Avoid colocating extra infrastructure on the VPS: no separate Postgres, Redis, Celery, message broker, or background analytics service in Phase 1.
+- Treat Google Sheets sync as lightweight projection work, not as a second analytics engine.
+- Prefer on-demand or dirty-month scoped recomputation over broad periodic rebuilds.
+- Any future feature that materially increases steady-state RAM use must be designed to run off-box (for example on the laptop-side agent) or be explicitly deferred until a larger host is available.
+
+### dinary (User's Laptop)
+
+A desktop application with two components: a **daemon** for background AI processing and a **GUI** for interactive use.
+
+**Daemon (background service):**
+- Runs continuously (or on schedule) when the user is at the computer.
 - Fetches pending tasks from the dinary-server API.
 - Processes them using `claude -p` (Claude Code CLI, non-interactive mode) under the user's existing subscription — no API token costs.
 - Pushes results back to the dinary-server API.
+- Handles all heavy/batch AI work that can be deferred.
+
+**GUI (interactive desktop app):**
+- Set analysis parameters (time range, grouping, filters) and view interactive analysis results.
+- Quick manual entry: hot-key to enter an expense, import from email/messages like bank notifications of internet payments.
+- Paste text or PDF with a receipt — the app responsively extracts payment data and stores it (uses AI API directly for fast turnaround; see "AI processing modes" below).
+- Review and confirm AI classification suggestions.
+
+**AI processing modes:**
+
+The desktop app uses two distinct AI channels depending on latency requirements:
 
-**Task types:**
+1. **`claude -p` (daemon, batch)** — for tasks where latency is not critical: batch classification, spending analysis, report generation. Runs under the existing Claude subscription at zero API cost. This is the primary AI channel.
+
+2. **AI API (GUI, interactive)** — for tasks that must feel responsive to the user: when the user pastes text or a PDF with a receipt, the app calls an AI API directly to extract payment data (amount, date, store, items) in real time. The user should not wait seconds for `claude -p` to spin up. This is a lightweight, targeted use — simple extraction prompts with small payloads, minimal API cost.
+
+**Task types (daemon):**
 
 1. **Batch classification** (daily or on demand):
    ```bash
    # Fetch unclassified items from dinary-server
-   dinary-analyst classify
+   dinary classify
 
    # Under the hood:
    # 1. GET https://server/api/tasks/pending-classifications → pending.json
@@ -551,7 +615,7 @@ The local agent is stateless — it fetches tasks, processes them, and pushes re
 
 2. **Spending analysis** (weekly/monthly/on demand):
    ```bash
-   dinary-analyst analyze --period 2026-Q1
+   dinary analyze --period 2026-Q1
 
    # Under the hood:
    # 1. GET https://server/api/tasks/analysis-export?period=2026-Q1 → data.json
@@ -559,9 +623,10 @@ The local agent is stateless — it fetches tasks, processes them, and pushes re
    # 3. POST https://server/api/tasks/analysis-report ← report
    ```
 
-3. **Future AI tasks** — any new AI-intensive operation follows the same pattern: dinary-server exposes a task endpoint, dinary-analyst fetches, processes with `claude -p`, pushes results back.
+3. **Future AI tasks** — any new AI-intensive operation follows the same pattern: dinary-server exposes a task endpoint, dinary fetches, processes with `claude -p`, pushes results back.
 
-**Built as a Rust binary** — single executable, no runtime dependencies, compact installer for macOS and Windows.
+**Built in Rust** — targeting macOS and Windows. Packaging model (single binary vs. app bundle, installer type, tray integration,
+daemon lifecycle management) depends on the GUI framework choice and will be determined during the Phase 4 GUI framework POC.
 
 ### Backup Strategy
 
@@ -572,75 +637,145 @@ The local agent is stateless — it fetches tasks, processes them, and pushes re
 
 ### Security
 
-- dinary-server API protected by API key or mutual TLS (single user, no need for full auth system).
-- Cloudflare Tunnel provides HTTPS without exposing the VPS directly.
+- dinary-server API protected by Cloudflare Access (if using Cloudflare Tunnel) or by tailnet membership (if using Tailscale Serve). Single user, no need for an in-app auth system.
+- Cloudflare Tunnel or Tailscale Serve provides HTTPS without exposing the application port directly to the internet.
 - DuckDB files are not accessible from the internet — only through the dinary-server API.
 
 ---
 
 ## Build Plan (Incremental Phases)
 
-### Phase 0: MVP — Manual Entry → Google Sheets (no DuckDB, no QR, no AI)
+### Phase 0: MVP — Manual Entry + QR Total → Google Sheets (completed)
 
-The fastest path to replacing manual spreadsheet editing. No new database, no receipt parsing — just a mobile frontend that writes directly to the existing Google Sheets structure.
+The fastest path to replacing manual spreadsheet editing, with early validation of QR scanning.
+No new database, no line-item parsing — just a mobile frontend that writes directly to the existing Google Sheets structure.
 
 **Scope:**
-- A mobile frontend (chosen from the evaluation table, or a quick Telegram bot / PWA prototype) with a simple form: amount (RSD) + category (dropdown from the existing ~33 categories) + category group (auto-filled from category) + optional comment.
-- A lightweight backend (Python script or serverless function) that receives the entry and writes it to the existing Google Sheets spreadsheet via the Sheets API.
-- **Auto-month creation:** if the backend detects that rows for the current month don't exist yet in the sheet, it automatically creates the full block of category rows for the new month (copying the category/group structure from the previous month). This eliminates the most tedious manual step.
-- Currency conversion: RSD → EUR using the same fixed rate currently used in the sheet.
-- No item-level parsing, no DuckDB, no AI. The user picks the category manually, just as they do now — but from a phone instead of editing a spreadsheet.
+
+- A mobile frontend (implemented as a PWA) with a simple form: amount (RSD) + group dropdown + category dropdown + optional comment. This matches the existing spreadsheet model better than a single huge selector.
+- **QR scanning with parallel processing:** the user scans a Serbian fiscal receipt QR code on the phone. The QR code is decoded on the device (fully offline — client-side image processing) using `zbar-wasm`. The client extracts amount/date from the receipt URL immediately and shows the form without waiting for the backend. Backend QR parsing remains as a fallback/API capability. No line-item parsing, no store extraction in Phase 0.
+- A FastAPI backend that receives the entry and writes it to the existing Google Sheets spreadsheet via the Sheets API. FastAPI (not serverless) because it carries forward into Phase 1 (DuckDB) and Phase 4 (AI agent API) without rewriting.
+- **Auto-month creation:** if the backend detects that rows for the current month don't exist yet in the sheet, it automatically creates the full block of category rows for the new month by copying the previous block, preserving spreadsheet formulas, zeroing RSD values, and inserting the new month at the top of the yearly sheet.
+- **Currency conversion:** the EUR/RSD exchange rate is stored in the sheet itself, on the first row of each month block. When the backend creates a new month or writes the first expense of the month, it checks that month header row and writes the rate only there if missing.
+- **Offline queue:** entries are stored in IndexedDB on the device before any network call. When connectivity is restored, the queue is flushed automatically on app open, on `online`, and after successful user actions when pending items exist. The user must never lose an entry due to network or server failure.
+- **Always-on server required:** PWA on iOS cannot run background sync — sync only happens while the app is open. The server must respond within 1-2 seconds. Sleeping/serverless hosting (Render free tier, Lambda) is not suitable. Use Oracle Cloud Free Tier (AMD Micro, always on) or self-hosted Mac/PC with Tailscale Serve / Cloudflare Tunnel.
+- No line-item parsing, no store extraction, no DuckDB, no AI. The user picks the category manually, just as they do now — but from a phone instead of editing a spreadsheet. QR scanning only extracts the receipt total amount and date, not individual items or store.
 
 **What this validates:**
+
 - The chosen mobile frontend tool works for daily data entry (offline persistence, speed, UX).
+- **QR scanning works reliably** with the chosen frontend tool (camera access, code extraction, end-to-end flow).
 - The Google Sheets API integration is reliable.
 - The user actually adopts phone-based entry over direct spreadsheet editing.
 
-**Exit criteria for Phase 0:** the user has used the system daily for 2+ weeks and no longer opens the spreadsheet to enter data manually.
+**Deliverables**
+
+- PWA frontend (in `static/`), backend, manuals, deployment scripts — all in the dinary-server repo
+- The `dinary` repo is not used in Phase 0 (reserved for the Rust desktop app, Phase 4+)
+
+**Operational conventions introduced by the completed MVP:**
+
+- Local/CI regression entry point is `inv test`, which runs both pytest and Vitest and writes a shared `allure-results/` directory.
+- New tests must preserve the existing Allure taxonomy unless there is an explicit architecture-level reason to extend it.
+- Phase 0 approved Allure epics are: `Data Safety`, `Google Sheets`, `API`, `Services`, `Build`.
+- Phase 0 approved features are:
+- `Data Safety`: `Formula Preservation`, `Comment Preservation`, `Column Protection`, `Offline Queue`, `No Data Loss`
+- `Google Sheets`: `Read Categories`, `Write Expense`, `Exchange Rate`, `Month Creation`, `Helpers`
+- `API`: `Health`, `Categories`, `Expenses`, `QR Parse`
+- `Services`: `Category Store`, `Exchange Rate`, `QR Parser`
+- `Build`: `Version`
+
+**Exit criteria for Phase 0:**
+- The user has used the system daily for 2+ weeks and no longer opens the spreadsheet to enter data manually.
+- QR scanning has been used successfully on real receipts (camera → URL extraction → total + date pre-fill) and is confirmed to work reliably with the chosen frontend tool.
+
+### Phase 1: Data Foundation & Idempotent Ingestion (dinary-server) ✓ IMPLEMENTED
+
+Detailed plan: [phase1.md](phase1.md)
+
+- DuckDB with the **full 5-dimensional classification schema** (category, beneficiary, event, tags, store) from day one.
+- **sheet-to-5D mapping table** (`sheet_category_mapping`) decomposes the current Google Sheet's flat `(Расходы, Конверт)` pairs into proper 5D assignments.
+- **PWA unchanged** -- sends `(category, group)` as in Phase 0; server resolves to 5D via mapping table.
+- DuckDB-backed expense ingestion with idempotent deduplication via `expenses.id PRIMARY KEY`.
+- Google Sheets is a derived read-only view: sync layer projects 5D DuckDB data back into sheet format.
+- Client generates `expense_id = crypto.randomUUID()` at enqueue time; server returns `200 created`, `200 duplicate`, or `409 Conflict`.
+- Allure test suite covers: `Data Safety / Deduplication` (Python + JS), `DuckDB / Bootstrap`, `DuckDB / Mapping`, `DuckDB / Travel Events`, `DuckDB / Reverse Mapping`, `DuckDB / Year Boundary`.
 
-### Phase 1: Data Foundation & Backend Deployment (dinary-server)
-- Set up DuckDB schema (config.duckdb + budget_2026.duckdb) on VPS (Oracle Cloud Free Tier).
-- Deploy dinary-server (FastAPI) with basic REST API for expense ingestion.
-- Migrate existing Google Sheets data into DuckDB.
-- Write basic SQL queries for monthly aggregates.
-- Backend now writes to both DuckDB (primary) and Google Sheets (view layer).
-- Set up Cloudflare Tunnel or direct HTTPS access to the backend.
+**Historical data migration is NOT part of Phase 1.** After Phase 1 cutover, DuckDB holds only new expenses; historical data remains in Google Sheets until Phase 1.5.
+
+### Phase 1.5: Historical Data Migration
+
+The existing Google Sheets contain ~10 years of data. Nearly every year used a slightly different category system (different category names, different envelope groupings) and even different column layouts. This makes bulk import impractical -- each year requires individual analysis and its own mapping.
+
+- Analyze each yearly Google Sheets tab individually: identify that year's category/envelope structure, column layout, and how it differs from other years.
+- Build per-year mapping from that year's flat `(category, envelope)` pairs to the 5D classification model, handling cases where the same category name meant different things in different years.
+- For "путешествия" envelopes: create a per-year synthetic event "отпуск-YYYY" (`date_from = YYYY-01-01`, `date_to = YYYY-12-31`) and map all travel rows to it (same approach as Phase 1 uses for the current year). Once the PWA switches to native 5D input (Phase 2+), set `date_to` of the last synthetic travel event to the release date of the 5D PWA. From that date forward, the user creates specific named trips instead of a per-year umbrella, and the auto-attach rule for `sheet_group = "путешествия"` is retired.
+- Build per-year import scripts that create synthetic expense rows in `budget_YYYY.duckdb` with `source = 'legacy_import'`.
+- Reconcile imported totals against original sheet totals.
+- After successful import, run DuckDB -> Google Sheets sync to verify the rebuilt sheet matches legacy data.
 
 ### Phase 2: Receipt Parser
 - Integrate or adapt sr-invoice-parser for fetching and parsing Serbian fiscal receipts from SUF PURS URLs.
 - Build the ingestion pipeline: URL → fetch HTML → parse line items → insert into `expenses` table in DuckDB.
-- Implement rule-based auto-classification.
+- Implement fuzzy ML / AI auto-classification that produces 5D classification directly (category, beneficiary, event, tags, store).
+- Change the PWA so it no longer works in Google Sheets terms for new receipt/manual flows. From Phase 2 onward, the PWA should use the native 5D classification model directly instead of asking the user for `(Расходы, Конверт)` from the spreadsheet.
+- Google Sheets sync uses the `sheet_category_mapping` table in reverse: from the 5D classification produced by AI/rules, determine the target `(Расходы, Конверт)` row in the sheet.
 
 ### Phase 3: Mobile Input — Full Version (dinary-app)
-- **3a: Frontend tool evaluation.** Research the candidate tools from the evaluation table (see "Frontend Tool Evaluation" section) **and any other tools discovered during research**. Build a minimal MVP (scan QR → send URL → see parsed items) with 1-2 top candidates. Compare: QR scanning reliability, offline data persistence, speed of manual entry, API connectivity, cross-platform behavior (Android + iOS), overall UX on phone. Decide on the tool. Note: if the Phase 0 tool already satisfies all must-have criteria, this step may be a confirmation rather than a new evaluation.
+**Done as part of MVP**
+
+- **3a: Frontend tool evaluation.
+
+  - ** Research the candidate tools from the evaluation table (see "Frontend Tool Evaluation" section) **and any other tools discovered during research**.
+  - Build a minimal MVP (scan QR → send URL → see parsed items with line-item detail) with 1-2 top candidates.
+  - Compare: QR scanning reliability, offline data persistence, speed of manual entry, API connectivity, cross-platform behavior (Android + iOS), overall UX on phone.
+  - Decide on the tool. Note: QR scanning and basic UX are already validated in Phase 0. This step focuses on whether the Phase 0 tool also handles the full line-item review flow, or whether a different tool is needed for Phase 3b.
+
 - **3b: Build the full mobile input layer** with the chosen tool.
+
   - QR scan → send URL → parse → store.
   - Manual entry for non-QR expenses.
   - Event auto-suggestion and selection.
   - Beneficiary selector.
   - Offline queue with sync-on-reconnect.
 
-### Phase 4: AI Classification (dinary-analyst)
-- Build dinary-analyst as a Rust CLI binary.
-- Implement the task queue API on dinary-server (`/api/tasks/*`).
-- Build the batch classification flow: fetch pending → `claude -p` → push results.
-- Implement the review/confirm flow (via dashboard or CLI).
-- Wire up rule learning (confirmed classifications → new rules in `category_rules`).
+### Phase 4: AI Classification & Desktop App (dinary)
+
+- **4a: GUI framework POC.**
+  - Evaluate Rust GUI frameworks for the desktop app (e.g., Tauri, egui/eframe, Slint, Dioxus, Iced).
+  - Build a minimal POC: a window with a form (analysis parameters), a results view, and a paste-to-extract flow (paste text → call AI API → display extracted data).
+  - Evaluate: cross-platform support (macOS + Windows), native look and feel, ease of iteration, maturity/community, integration with async Rust for API calls.
+  - Decide on the framework.
+
+- **4b: Build dinary daemon + GUI.**
+  - Daemon: background service that fetches pending tasks from dinary-server, processes with `claude -p`, pushes results back.
+  - Implement the task queue API on dinary-server (`/api/tasks/*`).
+  - Build the batch classification flow: fetch pending → `claude -p` → push results.
+  - GUI: interactive AI API calls for responsive receipt extraction (paste text/PDF → AI API → extract amount, date, items → store via server API).
+  - After AI classification of receipt line items is available, change the PWA receipt flow so scanning a receipt submits it immediately without waiting for a manual `Save` press. The scan should create the receipt/import job right away; later user interaction is only for review/correction, not for the initial submission.
+  - Implement the review/confirm flow (via GUI or CLI).
+  - Wire up rule learning (confirmed classifications → new rules in `category_rules`).
 
 ### Phase 5: Dashboards (dinary-server)
 - Operational dashboard (static HTML, current month snapshot).
 - Analytical dashboard (interactive SPA with time range selector and breakdowns).
 
-### Phase 6: AI Analysis & Google Sheets Sync (dinary-analyst + dinary-server)
+### Phase 6: AI Analysis & Google Sheets Sync (dinary + dinary-server)
 - Add analysis export endpoint to dinary-server API.
-- Build the dinary-analyst analysis flow: fetch aggregates → `claude -p` → push report.
+- Build the dinary analysis flow: fetch aggregates → `claude -p` → push report.
 - Build the Google Sheets sync script on dinary-server (if not already done in Phase 1).
 - Set up scheduled runs on the VPS (sync, dashboard regeneration).
 
 Each phase is independently useful.
 
-- Phase 0 alone eliminates manual spreadsheet editing and validates the mobile input tool.
-- Phase 1 establishes the proper data foundation.
+- Phase 0 alone eliminates manual spreadsheet editing, validates QR scanning, and validates the mobile input tool.
+- Phase 1 establishes the proper data foundation with idempotent ingestion and deduplication.
+- Phase 1.5 migrates historical Google Sheets data into DuckDB (complex, per-year analysis required).
 - Phase 2 solves the supermarket opacity problem.
-- Phase 3 adds QR scanning and full offline support.
-- Phases 4-6 add intelligence and convenience.
+- Phase 3 adds full line-item QR flow and complete mobile input.
+- Phase 4 builds the desktop app (daemon + GUI) with AI classification and responsive receipt extraction.
+- Phases 5-6 add dashboards, AI analysis, and Google Sheets sync.
+
+## Open questions
+
+- **Cross-year events**: events (e.g. a trip) can span a year boundary (start in December, end in January). Since `expenses` are partitioned into yearly `budget_YYYY.duckdb` files but `events` live in the shared `config.duckdb`, this works at the data level -- expenses in both years reference the same `event_id`. However, reporting and sync need to handle the case where a single event's expenses are split across two yearly DB files. Decide whether to query both years when summarizing an event, or accept per-year totals as sufficient.