103 lines
3.4 KiB
Markdown
103 lines
3.4 KiB
Markdown
# 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/)
|