# Proposal: add-toldo-poc-capacitor

## Why

The Circuito de Economía Solidaria de Támesis (CESTA) needs a software solution to facilitate registration and control of products and expenses at Sunday markets held in the main park of the municipality. 

Key business flows:
- Team rotation for managing the "Toldo" (canopy) each Sunday
- Initial inventory that should match previous week's final inventory, recording differences if any
- Sales registration (product, quantity, unit price, total value, payment method: cash or QR code)
- Expense registration during the day (tape, pens, bags, transportation, etc.)
- End-of-day cash reconciliation considering starting cash, sales, expenses
- End-of-day inventory that should match initial inventory minus sold products
- Reports by producer: inventory differences, initial inventory (real), inventory movements from sales, sales value, total per producer
- Cash reconciliation report with date/time, concept, income, expenses, balance; separate for cash and QR payments; track cash discrepancies and QR/bank differences; total sales (cash + QR)
- Ability to adjust initial inventory, sales, cash discrepancies, QR discrepancies with required change reason tracked in final report
- Store daily records with consolidated reports by date range, week, or month
- Add products mid-week/bodega restocks (register product, quantity, person who received)
- Products linked to a producer; same product name from different producers = different products (e.g., "Café molido 250gr Santa Ana" vs "Café molido 250gr Familia Gonzalez")

## Constraints

- Must work well offline (poor internet at park)
- Only a lightweight HTTP server to serve static files OR run as APK on Android tablet
- Data stored in browser storage (IndexedDB/localStorage) if web-based
- No user authentication required initially
- Must be able to export data to import on another device
- Must be Free/Libre Software
- Single git repo, possibility to add more folders/modules in future

## What Changes

Implement a Capacitor + Vite + TypeScript POC with:
- **Architecture**: Clean layered architecture (core/domain, data/infrastructure, services/application, ui/presentation) following SOLID principles
- **Storage**: Dexie.js over IndexedDB for structured offline storage
- **Packaging**: Capacitor to generate Android APK for tablet use; maintain web-first for static serving if needed
- **Testing**: TDD with Vitest, @testing-library, fake-indexeddb; mock Capacitor plugins
- **Export/Import**: Versioned JSON format for data portability between devices
- **Offline-first**: All assets bundled in APK, no backend required

## Impact

- **New apps**: `apps/toldo-app/` (Vite + Capacitor app)
- **New packages**: `packages/core/` (domain, pure TS), `packages/data/` (Dexie repos), `packages/services/` (use cases), `packages/ui/` (reusable components)
- **OpenSpec**: New change with specs
- **Agent Skills**: New skills for architecture, domain modeling, TDD, export/import
- **Android**: Capacitor Android platform configuration

## Non-Goals

- Real-time multi-device synchronization (CouchDB/PouchDB sync) - manual export/import is sufficient
- Barcode scanner integration (not requested in README)
- User authentication/authorization (explicitly not required initially)
- Complex PDF generation in first iteration (can be added later)
- TWA packaging (Capacitor direct APK preferred)