Estructura de repositorios
Mapa de los tres repositorios de ElVendedor: carpetas principales, stacks, dónde vive cada módulo y qué documentación es interna o pública.
El ecosistema son tres repositorios hermanos. Esta página te dice en cuál buscar cuando tengas que tocar algo y dónde está la documentación que no se publica en el sitio. Las rutas son relativas a la raíz de cada repositorio.
Vista de conjunto
| Repositorio | Stack | Versión | Artefacto |
|---|---|---|---|
el-vendedor |
Ionic 8, Angular 17, Capacitor 6, PouchDB con SQLite | 2.1.6 |
APK de Android |
el-vendedor-desktop |
Electron 42.3.3, Vite 5, JavaScript sin framework, PouchDB sobre IndexedDB |
2.1.6 |
Instaladores Windows y Linux |
el-vendedor-back |
Laravel 12, PHP 8.2+, Sanctum 4, Inertia 2 + Vue 3, Pest 4 | APP_VERSION=2.1.6 |
Servicio HTTP + backoffice |
el-vendedor (móvil)
android/ Proyecto nativo y firma de la APK
src/app/ Código Angular
pages/ Pantallas (POS, caja, stock, restaurante…)
services/ Lógica de negocio y acceso a datos
guards/ Protección de rutas (trial, licencia, rol)
models/, interfaces/ Contratos TypeScript
synchronization/ Pantalla y flujo de sincronización
components/ Componentes compartidos
src/environments/ URLs de staging y producción
docs/ Documentación interna
karma.conf.js Configuración de pruebas
capacitor.config.ts Configuración de CapacitorDónde está cada cosa:
| Tema | Archivo |
|---|---|
| Sync (bootstrap, pull, push, conflictos) | src/app/services/sync.service.ts |
| Constantes del contrato | src/app/services/sync-contract.ts |
| Licencias y trial | src/app/services/license.service.ts |
| Terminal del hub de restaurante | src/app/services/restaurant-lan-hub.service.ts |
| Pantalla de comanda | src/app/pages/restaurant-order/ |
| Ventas, compras, devoluciones | src/app/services/bill.service.ts |
| Productos y stock | src/app/services/products.service.ts |
Documentación interna: docs/arquitectura-sync-offline-first.md,
docs/contrato-sync-cliente.md, docs/restaurante-lan-guideline.md,
docs/release-checklist.md.
el-vendedor-desktop (escritorio)
src/main.js Proceso principal de Electron (arranca el hub)
src/preload.js Puente seguro hacia el renderer
src/renderer.js Arranque de la interfaz
src/app/views.js Vistas de la aplicación
src/app/components/ Componentes de interfaz
src/app/services/ Lógica de negocio, almacenamiento y sync
scripts/ Pruebas (scripts/*.test.mjs) y empaquetado (dist.js)
forge.config.js Makers de Electron Forge (squirrel, deb, rpm, zip)
vite.*.config.mjs Configuración de Vite por proceso
docs/ Documentación internaDónde está cada cosa:
| Tema | Archivo |
|---|---|
| Cliente de sync | src/app/services/sync-client.js |
| Entidades que el escritorio aplica | src/app/services/sync-capabilities.js |
| Base local (colecciones y almacenes) | src/app/services/pouchdb-store.js |
| Contrato de factura | src/app/services/invoice-contract.js |
| Totales de factura | src/app/services/invoice-totals.js |
| Hub LAN de restaurante | src/app/services/restaurant-lan-hub.js |
| Estructura de caja multidispositivo | docs/caja-multidispositivo.md |
Las pruebas se ejecutan con node --test "scripts/*.test.mjs" y usan un mock de
backend propio en scripts/sync-mock-server.mjs (npm test).
Documentación interna: docs/facturacion/, docs/inventario/, docs/pos/,
docs/distribucion/, docs/ux/, docs/pantalla-licencia.md,
docs/release-checklist.md.
el-vendedor-back (backend)
app/Http/Controllers/Api/V1/ API de sync, auth, licencias, caja, catálogo
app/Http/Controllers/Api/ Marketplace público y shim legacy de licencias
app/Http/Middleware/ sync.request, business.license, current.business
app/Support/Sync/ Compatibilidad, registro de entidades, cursores
app/Support/Licensing/ Tarifario y estado de licencia
app/Modules/ Dominios (Catalog, Inventory, Licensing, Marketplace, Sales)
app/Models/ Modelos Eloquent
config/sync.php Protocolo, contrato y política de compatibilidad
config/licensing.php Gate de escrituras y gracia offline
routes/api.php Rutas de la API v1
routes/backoffice.php Backoffice (Inertia)
database/migrations/ Esquema
tests/Feature/Api/V1/Sync/ Pruebas de contrato de sync
deploy/ Configuración de servidor
docs/ Documentación internaDónde está cada cosa:
| Tema | Archivo |
|---|---|
| Bootstrap, pull, push y conflictos | app/Http/Controllers/Api/V1/Sync/ |
| Compatibilidad de versiones | app/Support/Sync/SyncCompatibility.php |
| Lista canónica de entidades | app/Support/Sync/SyncEntityRegistry.php |
| Aplicación de entidades y transacciones | app/Support/Sync/SyncEntityApplier.php, SyncTransactionApplier.php |
| Licencias | app/Http/Controllers/Api/V1/Licensing/, app/Support/Licensing/ |
| Caja por REST y lease master | app/Http/Controllers/Api/V1/CashRegister/ |
| Reset de negocio | app/Support/Backoffice/ (BusinessCleaner) |
Documentación interna: docs/sync-api-v1.md, docs/sync-version-compatibility.md,
docs/licensing.md, docs/higiene-repo.md, docs/release-checklist.md,
docs/marketplace-architecture-report.md.
Documentación interna y pública
| Dónde | Qué es | Se publica |
|---|---|---|
el-vendedor-docs/ |
Sitio de documentación (este sitio) | sí |
docs/ de cada repo |
Notas de diseño, contratos internos, checklists de release | no |
elvendedor-api-contract-digest.md |
Artefacto único del contrato entre los tres repos | no (referencia de trabajo) |
| Auditorías del workspace | Revisión interna de integridad y paridad | no |
Regla práctica: si una página de este sitio y un documento interno se contradicen, manda el contrato del digest y el código; después se corrige la página pública. Las auditorías son material de trabajo, no fuente para el cliente.
Versionado y etiquetas
- Cada repositorio tiene su
docs/release-checklist.mdy su propio número de versión:package.jsonen los clientes yAPP_VERSIONen el backend. - Ningún repositorio publica etiquetas de versión: al 2026-11-16
git tagno devuelve ninguna en los tres. La correlación entre una entrega de cliente y un despliegue de backend se hace a mano con el checklist. - El backend no declara versión de producto en
composer.json(conserva el nombre del esqueleto de Laravel). Su versión efectiva esAPP_VERSION, que es también lo que compara con la app en el bootstrap. - Los contratos (protocolo y datos) suben por separado de la versión de producto; ver Compatibilidad de versiones.
Árboles de trabajo, no releases
Esta estructura describe el árbol de trabajo actual, que puede tener cambios sin
confirmar. No hay etiquetas que congelen una entrega: si necesitas reproducir un
fallo, pide la versión exacta que corre en el equipo y el APP_VERSION del
backend al que apunta.
Siguiente paso
- Cómo se conectan las piezas: Arquitectura del ecosistema.
- Qué hablan entre sí: Contrato de sincronización v1.
- Cómo se despliega el servicio: Despliegue del backend.
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte