🏷️ LocalPosSoftware

Sistema POS modular, multiplataforma y offline-first para comercios minoristas.

Un producto, múltiples rubros. El core cubre la operación común a cualquier comercio (ventas, stock, caja, facturación). Los módulos verticales se activan según el rubro del negocio: retail textil, taller a medida, gastronomía, ferretería, etc.

📌 Sobre el nombre

Producto: LocalPosSoftware
Repositorio: local-pos-software
Namespace interno: localpos
Nombre visible al usuario: configurable por instalación (ej. "Espacio BIP", "Ferretería Don Juan", etc.)

🏢 Primera instalación: Espacio BIP

La primera instalación productiva de LocalPosSoftware es Espacio BIP, un local en Landeta (Santa Fe, Argentina) con dos unidades de negocio:

Front: Blanquería, Decoración y Aromas (módulo retail-textil)
Back: Diseño de vestidos a medida (módulo taller-medida)

Esto sirve como caso de prueba real y como validación de que la arquitectura modular funciona.

📖 Documentación del Proyecto

Leer en este orden antes de trabajar:

Documento	Propósito	Audiencia
`README.md` (este archivo)	Cómo arrancar, comandos útiles, visión rápida	Todos
`PROJECT.md`	Especificación completa del producto	Desarrolladores, agentes de IA, stakeholders
`AGENT_INSTRUCTIONS.md`	Reglas de código y flujo de trabajo	Desarrolladores, agentes de IA

🚀 Primeros pasos

Prerrequisitos

Node.js 20 LTS o superior
npm 10 o superior
Git

Instalación

# Clonar el repositorio
git clone https://github.com/<tu-usuario>/local-pos-software.git
cd local-pos-software

# Instalar dependencias
npm install

# Copiar y editar las variables de entorno
cp .env.example .env
# Editar .env con tus credenciales de AFIP y Supabase

# Correr las migraciones de la base de datos
npm run db:migrate

# Cargar datos de prueba (opcional, útil para desarrollo)
npm run db:seed

# Iniciar en modo desarrollo
npm run dev

Setup inicial al primer arranque

La primera vez que se inicia la app (sin base de datos existente), se ejecuta un wizard de configuración:

Datos del negocio: nombre visible (ej. "Espacio BIP"), CUIT, logo, dirección
Primera unidad de negocio: nombre (ej. "Front"), categoría fiscal, numeración de facturas
Módulo vertical: elegir qué módulo aplica a esta unidad de negocio (ej. retail-textil)
Usuario admin: crear el primer usuario con rol administrador

Desde ese punto, el admin puede crear más unidades de negocio y asignarles sus módulos.

🧩 Arquitectura modular

Core (siempre presente)

El código base cubre lo que tiene todo comercio:

Gestión de productos y stock
Punto de venta (POS)
Caja diaria
Clientes
Facturación electrónica AFIP
Reportes básicos
Sincronización con la nube

Módulos verticales (activables por unidad de negocio)

Cada unidad de negocio tiene asignado uno de estos módulos al crearla:

Módulo	Para qué rubro	Qué agrega
`retail-general`	Cualquier comercio básico	Lo mínimo, sin extras
`retail-textil`	Blanquería, deco, aromas, ropa	Variantes (color, tamaño, material), catálogo web con imágenes
`taller-medida`	Diseño a medida, sastrería	Pedidos con seña, fechas de entrega, toma de medidas, estados de confección
`gastronomia`	Restó, bar, rotisería	Mesas/comandas, cocina, productos por hora del día
`ferreteria`	Ferretería, materiales	Unidades de medida (metros, kilos), stock por sucursal

Los módulos se desarrollan incrementalmente. La primera versión del producto incluye retail-general, retail-textil y taller-medida (los que necesita Espacio BIP).

Unidades de negocio (Business Units)

Una instalación de LocalPosSoftware puede tener una o varias unidades de negocio. Cada una:

Tiene su propio stock (no se comparten productos entre unidades)
Tiene su propia caja diaria
Tiene su propia numeración de facturas
Tiene su módulo vertical asignado
Aparece como selector visible en la UI (el usuario elige en qué unidad está trabajando)

Comparten entre sí:

Usuarios del sistema
Configuración AFIP (puede ser el mismo CUIT o distintos)
Branding global

🛠️ Comandos disponibles

Desarrollo

Comando	Descripción
`npm run dev`	Inicia la app completa en modo desarrollo (backend + frontend + electron)
`npm run dev:server`	Inicia solo el backend Express
`npm run dev:renderer`	Inicia solo el frontend React

Base de datos

Comando	Descripción
`npm run db:generate`	Genera una nueva migration desde el schema
`npm run db:migrate`	Aplica las migrations pendientes
`npm run db:studio`	Abre Drizzle Studio para inspeccionar la DB
`npm run db:seed`	Carga datos de ejemplo
`npm run db:reset`	Borra la DB y vuelve a migrar (solo dev)

Testing

Comando	Descripción
`npm test`	Corre todos los tests unitarios
`npm run test:watch`	Tests en modo watch
`npm run test:coverage`	Reporte de cobertura
`npm run test:e2e`	Tests end-to-end con Playwright

Calidad de código

Comando	Descripción
`npm run lint`	Corre ESLint
`npm run lint:fix`	ESLint con auto-fix
`npm run format`	Formatea con Prettier
`npm run format:check`	Verifica formato sin modificar
`npm run typecheck`	Verifica tipos de TypeScript

Build y distribución

Comando	Descripción
`npm run build`	Compila la app para producción
`npm run dist:win`	Genera instalador para Windows
`npm run dist:mac`	Genera instalador para macOS
`npm run dist:linux`	Genera paquete para Linux

📦 Generar el instalador de Windows (versión de prueba)

npm run dist:win

Esto compila el renderer (Vite) y el server (tsc), y empaqueta todo con electron-builder. Al terminar, el instalador queda en:

dist/Espacio BIP Setup 0.1.0.exe

Instalar en otra PC

Copiar Espacio BIP Setup 0.1.0.exe a la notebook de destino y ejecutarlo.
Windows SmartScreen puede advertir porque el instalador no está firmado — click en "Más información" → "Ejecutar de todas formas".
El instalador permite elegir carpeta de destino (no requiere admin).

Dónde queda todo

Qué	Dónde
Base de datos (`localpos.db`)	`%APPDATA%\Espacio BIP\localpos.db`
Log de diagnóstico	`%APPDATA%\Espacio BIP\logs\main.log`
Config editable (`.env`)	`<carpeta de instalación>\resources\.env`
Catálogo de prueba (`productos.csv`)	`<carpeta de instalación>\resources\seed\productos.csv`

La base de datos vive en userData, no en la carpeta de instalación — persiste entre reinstalaciones/actualizaciones y no se borra si reinstalás encima.

Qué trae esta versión

AFIP desactivada: las ventas se registran e imprimen como ticket interno, sin factura electrónica (resources/.env → AFIP_ENVIRONMENT=disabled).
Catálogo de prueba: se carga automáticamente desde resources/seed/productos.csv en cada arranque (SEED_DEMO=true). Podés editar ese CSV con tu catálogo real y reiniciar la app — no hace falta recompilar. Ver resources/seed/README.md para el formato exacto de columnas (incluye variantes de color/tamaño/fragancia/material).
Una sola unidad de negocio: "Aromas/Home&Deco", activa por defecto.
Medios de pago: Efectivo, Mercado Pago, Transferencia y Débito, editables (activar/desactivar) desde Configuración → Medios de pago.
Reiniciar datos de prueba: Configuración → pestaña "Negocio" → sección "Zona de testing" al final. Borra productos/stock/ventas/caja/clientes y vuelve a cargar el CSV desde cero (requiere escribir "BORRAR" para confirmar). No afecta la configuración del negocio ni el usuario admin.
Supabase opcional: completar SUPABASE_URL/SUPABASE_ANON_KEY en resources/.env con un proyecto de test si querés probar la sincronización. Si se dejan vacíos, la app funciona 100% offline.

Si vas a seguir developeando después de generar el instalador

electron-builder recompila better-sqlite3 para el ABI de Electron al empaquetar. Si después corrés npm run dev, vas a ver un error de NODE_MODULE_VERSION — corré npm run rebuild para volver a compilarlo para el Node del sistema:

npm run dist:win
npm run rebuild   # necesario antes de volver a "npm run dev"

📁 Estructura del proyecto

local-pos-software/
├── electron/          # Main process de Electron
├── src/               # Frontend React + TypeScript
│   ├── components/    # Componentes reutilizables
│   ├── core/          # Features del core (POS, stock, caja, etc.)
│   ├── modules/       # Módulos verticales (retail-textil, taller-medida, etc.)
│   ├── lib/           # Utilidades compartidas
│   └── types/         # Tipos globales
├── server/            # Backend Express + SQLite
│   ├── db/            # Schemas y migrations
│   ├── core/          # Servicios y rutas del core
│   ├── modules/       # Servicios y rutas de módulos verticales
│   └── repositories/  # Acceso a datos
├── shared/            # Tipos y constantes compartidas
├── tests/             # Tests unitarios y E2E
└── assets/            # Íconos, imágenes, fuentes

Ver AGENT_INSTRUCTIONS.md sección 4 para la estructura completa y reglas de ubicación.

🧑‍💻 Trabajando con un agente de IA

Este proyecto está diseñado para ser desarrollado con asistencia de agentes de IA (GitHub Copilot, Cursor, Claude Code, etc.).

Prompt inicial para cualquier tarea

Leé AGENT_INSTRUCTIONS.md y PROJECT.md antes de trabajar.

Tarea: [descripción de la tarea]

Requisitos funcionales relacionados: [RF-XX, RF-YY]
Módulo afectado: [core | retail-textil | taller-medida | etc.]

Por favor:
1. Primero presentame un plan con los archivos que vas a crear o modificar
2. Esperá mi confirmación antes de codear
3. Seguí las convenciones de AGENT_INSTRUCTIONS.md
4. Al terminar, dame el checklist de la sección 13 completado

Ver AGENT_INSTRUCTIONS.md sección 12 para más plantillas.

Reglas importantes

Identificar siempre si una tarea es core o modular antes de empezar
No agregar dependencias sin justificación
Seguir el orden de implementación: schema → service → controller → UI
Siempre validar inputs con Zod
Siempre testear la lógica de negocio
Seguir Conventional Commits

🗺️ Roadmap

El desarrollo está dividido en fases. Ver PROJECT.md sección 11 para el detalle.

Etapa 1 — Core funcional

Fase 0: Setup y arquitectura base
Fase 1: Modelo de Business Units + configuración inicial
Fase 2: CRUD de productos y control de stock (core)
Fase 3: POS básico
Fase 4: Caja diaria y gestión de clientes
Fase 5: Facturación electrónica AFIP
Fase 6: Modo offline con cola de sincronización

Etapa 2 — Primeros módulos verticales

Fase 7: Módulo retail-textil (para el Front de Espacio BIP)
Fase 8: Módulo taller-medida (para el Back de Espacio BIP)
Fase 9: Dashboard, reportes y sincronización con Supabase

Etapa 3 — Producto comercial

Fase 10: Módulo de proveedores y simulador de compras
Fase 11: Pulido, testing, instaladores
Fase 12+: Nuevos módulos verticales (gastronomía, ferretería, etc.)

🧪 Cómo contribuir

Crear una rama desde develop: git checkout -b feature/nombre-del-feature
Hacer los cambios siguiendo AGENT_INSTRUCTIONS.md
Correr tests y linter: npm test && npm run lint
Commit siguiendo Conventional Commits
Abrir un pull request a develop

🔒 Variables de entorno

Ver .env.example para la lista completa. Las más importantes:

NODE_ENV=development
SERVER_PORT=3001

# AFIP
AFIP_CUIT=20123456789
AFIP_CERT_PATH=./certs/certificate.crt
AFIP_KEY_PATH=./certs/private.key
AFIP_ENVIRONMENT=testing

# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key

⚠️ Nunca commitear el archivo .env. Ya está en .gitignore.

📄 Licencia

Versión del README: 2.0 Última actualización: Abril 2026

Name		Name	Last commit message	Last commit date
.claude		.claude
assets		assets
docs		docs
electron		electron
mockup		mockup
resources		resources
server		server
shared		shared
src		src
supabase		supabase
tests/unit		tests/unit
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
AGENT_INSTRUCTIONS.md		AGENT_INSTRUCTIONS.md
FASE_0_NOTAS.md		FASE_0_NOTAS.md
PROJECT.md		PROJECT.md
README.md		README.md
check_current_db.ts		check_current_db.ts
check_db.ts		check_db.ts
clean_db.ts		clean_db.ts
comparador_proveedores.html		comparador_proveedores.html
drizzle.config.ts		drizzle.config.ts
electron-builder.yml		electron-builder.yml
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
remove_test_bu.ts		remove_test_bu.ts
reset_db.ts		reset_db.ts
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation