# 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:
1. **Dexie.js + Vite + PWA (web only)** - Simpler, no native build complexity
2. **PouchDB + CouchDB sync + Capacitor** - Over-engineered, sync not needed
3. **sql.js (SQLite WASM)** - Heavier bundle, more complex
4. **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

## References
- [Capacitor Docs](https://capacitorjs.com/)
- [Dexie.js](https://dexie.org/)
- [Vite](https://vitejs.dev/)
- [OpenSpec](https://openspec.dev/)
- [Agent Skills](https://agentskills.io/)