{"id":51599284,"url":"https://github.com/johnny4young/puntovivo","last_synced_at":"2026-07-11T21:00:26.892Z","repository":{"id":367784889,"uuid":"1146238547","full_name":"johnny4young/puntovivo","owner":"johnny4young","description":"Local-first, fiscal-native POS for Latin American retail — Electron + React + Fastify + tRPC + SQLite","archived":false,"fork":false,"pushed_at":"2026-07-07T03:37:43.000Z","size":39295,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-07T04:13:08.234Z","etag":null,"topics":["colombia","drizzle","electron","fastify","latam","monorepo","offline-first","point-of-sale","pos","react","retail","sqlite","trpc","typescript"],"latest_commit_sha":null,"homepage":"https://puntovivo.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnny4young.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-30T20:04:15.000Z","updated_at":"2026-07-07T03:15:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/johnny4young/puntovivo","commit_stats":null,"previous_names":["johnny4young/puntovivo"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/johnny4young/puntovivo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnny4young%2Fpuntovivo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnny4young%2Fpuntovivo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnny4young%2Fpuntovivo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnny4young%2Fpuntovivo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnny4young","download_url":"https://codeload.github.com/johnny4young/puntovivo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnny4young%2Fpuntovivo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35375153,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["colombia","drizzle","electron","fastify","latam","monorepo","offline-first","point-of-sale","pos","react","retail","sqlite","trpc","typescript"],"created_at":"2026-07-11T21:00:18.310Z","updated_at":"2026-07-11T21:00:26.844Z","avatar_url":"https://github.com/johnny4young.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Puntovivo\n\nPuntovivo is a local-first, fiscal-native POS for Latin American retail\noperators. The first sellable wedge is Colombia retail for 1-10 site stores:\nfast checkout, cash accountability, site-owned stock, auditability, fiscal\nreadiness, and offline local authority before cloud expansion.\n\nThe project is not a generic ERP, not a cloud-only suite, and not trying to\nship every vertical at once. Restaurant, KDS, AI, delivery, public API, and\nhosted SaaS work exist as modules or roadmap lanes, but the production gate is\nstill retail POS sellability.\n\n## Current Status\n\nAs of 2026-06-01:\n\n| Stage                | Verdict | Why                                                                                                                                     |\n| -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| Development demo     | Yes     | Demo tenant, POS, inventory, cash sessions, quotations, fiscal mock, AI, sync, receipt templates, and operations surfaces can be shown. |\n| Private retail pilot | Not yet | Fiscal contingency, final fiscal receipt proof, and physical POS hardware need to close first.                                          |\n| Production sale      | No      | Requires a DIAN-authorized provider path, legal XML retention proof, hardware validation, and payment-terminal policy.                  |\n\nThe go/no-go checklist lives in [docs/SELLABILITY.md](./docs/SELLABILITY.md),\nwhich holds the MVP Colombia definition of done across the demo, pilot, and\nproduction gates.\n\n![Puntovivo architecture](./docs/architecture.svg)\n\n## Product Boundaries\n\n### In Scope Now\n\n- Colombia retail POS foundation.\n- Local SQLite authority with offline operation.\n- Electron desktop and browser web targets sharing the same React app.\n- Embedded Fastify + tRPC API, with the Electron desktop server running\n  in-process in the main process.\n- Tenant-scoped data model, role guards, audit logs, cash sessions,\n  site-owned stock, and fiscal document foundations.\n- Neutral Latin American Spanish and English UI.\n\n### Parked Or Gated\n\n- Real DIAN provider integration is gated on provider contract, credentials,\n  certificate, and numbering resolution.\n- Hardware printer, drawer, scanner, and terminal certification require a\n  physical lab.\n- Hosted SaaS, public demo tenants, tenant clone, and micro-storefronts depend\n  on the hosted deployment substrate spike.\n- Restaurant/KDS/services/pharmacy depth should move only when a pilot makes\n  that vertical the wedge.\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js `\u003e=24.0.0`\n- pnpm `11.x` through Corepack or a matching local install\n\n```bash\ncorepack enable\npnpm install\npnpm --filter @puntovivo/desktop run rebuild\n./scripts/check-setup.sh\n```\n\npnpm 11 blocks dependency build scripts unless they are allowlisted. The repo\nallowlist lives in [pnpm-workspace.yaml](./pnpm-workspace.yaml) and covers the\nruntime pieces Puntovivo needs: Electron, better-sqlite3-multiple-ciphers,\nargon2, and esbuild. If install prints\n`ERR_PNPM_IGNORED_BUILDS`, fix the allowlist or run `pnpm approve-builds`, then\ninstall again.\n\n## Development Commands\n\nRun workspace commands from the repo root.\n\n| Task                        | Command                      |\n| --------------------------- | ---------------------------- |\n| Desktop stack               | `pnpm run dev:desktop`       |\n| Electron shell only         | `pnpm run dev:desktop-shell` |\n| Web app only                | `pnpm run dev:web`           |\n| Web + standalone backend    | `pnpm run dev:web-stack`     |\n| Backend only                | `pnpm run dev:server`        |\n| Stop dev-launcher processes | `pnpm run dev:stop`          |\n| Web CI gate                 | `pnpm run ci:web`            |\n| Server CI gate              | `pnpm run ci:server`         |\n| Desktop CI gate             | `pnpm run ci:desktop`        |\n| Web E2E                     | `pnpm run test:e2e:web`      |\n| Electron E2E                | `pnpm run test:e2e:electron` |\n| Desktop package build       | `pnpm run build:desktop`     |\n\nDev login:\n\n- Email: `admin@localhost`\n- Password in development: `Admin123!Dev`, unless\n  `PUNTOVIVO_DEV_ADMIN_PASSWORD` was set before first seed.\n\nProduction first-run credentials are generated and shown once in the server\nconsole. See [docs/LOGIN_GUIDE.md](./docs/LOGIN_GUIDE.md).\n\n## Runtime Shape\n\n| Layer    | Current choice                                 | Notes                                                          |\n| -------- | ---------------------------------------------- | -------------------------------------------------------------- |\n| Desktop  | Electron 41 + electron-builder packaging       | Electron 42 is gated by upstream better-sqlite3 V8 14 support. |\n| Web      | React 19 + Vite 8 + TypeScript 6               | Browser target and Electron renderer share the app code.       |\n| API      | Fastify + tRPC 11                              | `/api/trpc` is the canonical application API.                  |\n| Database | SQLite through better-sqlite3-multiple-ciphers | SQLCipher path is wired; dev modes can share an encrypted DB.  |\n| ORM      | Drizzle                                        | Migrations are the single schema path.                         |\n| State    | TanStack Query + Zustand                       | Server state and local UI state are separated.                 |\n| Styling  | Tailwind CSS v4 + CVA                          | See [docs/STYLING.md](./docs/STYLING.md).                      |\n| Realtime | SSE                                            | `/api/realtime/*` remains for live updates.                    |\n\nThe desktop app imports `@puntovivo/server` directly from the Electron main\nprocess. Do not model it as a child server process.\n\n## Native Runtime Notes\n\nElectron and standalone Node use different native ABIs. After install, rebuild\nElectron natives:\n\n```bash\npnpm --filter @puntovivo/desktop run rebuild\n```\n\nIf standalone server tests fail after desktop packaging with a\n`NODE_MODULE_VERSION` mismatch, rebuild the Node-side binding:\n\n```bash\nnode packages/server/scripts/rebuild-better-sqlite3-node.mjs\n```\n\nThe current desktop runtime is Electron `41.7.1`. Keep manual\n`electron-rebuild` invocations aligned with `apps/desktop/package.json`.\n\n## Documentation Map\n\nStart at [docs/README.md](./docs/README.md). The short version:\n\n- [docs/SELLABILITY.md](./docs/SELLABILITY.md): demo, pilot, production go/no-go.\n- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md): current system shape.\n- [docs/ENVIRONMENT_CONFIGURATION.md](./docs/ENVIRONMENT_CONFIGURATION.md): env var reference.\n- [docs/DESKTOP_RUNTIME_GUIDE.md](./docs/DESKTOP_RUNTIME_GUIDE.md): Electron runtime details.\n- [docs/SECURITY.md](./docs/SECURITY.md): auth, hardening, and audit policy.\n\n## Verification Policy\n\nRun the CI gate that matches the area touched:\n\n| Area                                  | Command                      |\n| ------------------------------------- | ---------------------------- |\n| `apps/web` React or TypeScript        | `pnpm run ci:web`            |\n| `packages/server` backend             | `pnpm run ci:server`         |\n| `apps/desktop/src/main` Electron main | `pnpm run ci:desktop`        |\n| Web E2E/login/sales/inventory flows   | `pnpm run test:e2e:web`      |\n| Electron bootstrap/E2E                | `pnpm run test:e2e:electron` |\n\nAny user-facing UI change also needs a live web or Electron smoke in addition\nto tests.\n\n## License\n\nMIT License. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnny4young%2Fpuntovivo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnny4young%2Fpuntovivo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnny4young%2Fpuntovivo/lists"}