ADR 0001: Arquitectura Capacitor + Vite + TypeScript + Dexie

Status: Accepted
Date: 2026-10-24
Deciders: Development team

Context

The ToldoConjunto project needs a POC for CESTA (Circuito de Economía Solidaria de Támesis) to manage inventory, sales, expenses, cash reconciliation, and reports for Sunday markets.

Constraints:

Must work well offline (poor internet at park)
Only lightweight HTTP server for static files OR APK
Data in browser storage if web-based
No authentication required initially
Must export/import data between devices
Must be Free/Libre Software
Single git repo, can add more folders later
Tablet Android available for use

Alternatives considered:

Dexie.js + Vite + PWA (web only) - Simpler, no native build complexity
PouchDB + CouchDB sync + Capacitor - Over-engineered, sync not needed
sql.js (SQLite WASM) - Heavier bundle, more complex
Existing FOSS POS apps - Hard to customize to specific CESTA flows

Decision

Use Capacitor + Vite + TypeScript + Dexie.js with clean layered architecture.

Stack

Build: Vite + TypeScript (web-first)
Packaging: Capacitor for Android APK
Storage: Dexie.js over IndexedDB
Testing: Vitest + Testing Library + fake-indexeddb
Architecture: packages/core (domain), packages/data (infra), packages/services (app), packages/ui (presentation), apps/toldo-app (composition)

Rationale

Why Capacitor:

Better UX on Android tablet (app icon, no browser UI)
All assets bundled in APK - truly offline, no server needed
Easy distribution via USB/OTG
Can access native APIs in future if needed
Still maintains web-first approach

Why Dexie over PouchDB:

Lighter weight, simpler API
No revision/conflict complexity not needed
Manual export/import is sufficient for device-to-device transfer
Easier to test and reason about
Better fit for relational domain model

Why Clean Architecture:

Core business logic (cuadre, productos por productor, ajustes con motivo) is complex and must be correct
TDD easier with pure domain layer
Easy to evolve without tight coupling
Components stay small and reusable
Can extract to separate modules later in same repo

Consequences

Positive

APK provides great UX for non-technical users
Works completely offline
Business logic is highly testable
Clear separation of concerns
Easy to add new features/modules
Export/import JSON is simple and reliable
Skills enforce good practices

Negative

More complex build process than pure web (need Android SDK for APK)
Need to mock Capacitor plugins in tests
More boilerplate with packages structure
Slightly larger app size with Capacitor runtime

Mitigations

Keep web-first - can still serve dist/ statically
Mock all @capacitor/* in unit tests
Start simple, add packages as needed
Document build process clearly
Use skills to maintain discipline

Compliance

✅ Works offline
✅ Can serve as static files or APK
✅ Data in IndexedDB (browser storage)
✅ No auth required
✅ Export/import capability
✅ Free/Libre Software (all dependencies MIT/Apache/BSD compatible)
✅ Single git repo, extensible structure
✅ TDD capable
✅ Follows SOLID, separation of concerns

3.4 KiB Raw Blame History