impuestospy/README.md

Impuestos

Tax automation for Paraguayan taxpayers: scan comprobantes, classify them for IVA credit and IRP deductions, watch a live tax position, and get Formulario 120 and 515 pre-filled and ready to file yourself.

Working name. See docs/ for the specifications, DECISIONS.md for choices made along the way and the gaps that still need answers.

Status: phase 7 of 8. The whole taxpayer path works: scan a comprobante, confirm it, watch the position move, and take the resulting Formulario 120 or 515 from review to approved to a PDF you file yourself in Marangatu. Staff have a console: look an account up, work the ingestion error queue, read and export the audit log. It installs to a home screen, keeps a capture taken with no signal and sends it later, and can send a push when a deadline is close. The scale-out work is the last phase.

---

Quick start

pnpm install
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
pnpm db:migrate
pnpm db:seed
pnpm dev

The web app is on http://localhost:3005, the API on http://localhost:4000. db:seed prints the development sign in details for the four demo accounts.

Two of those accounts reach the staff console at /es/usuarios, /es/errores and /es/auditoria: staff@demo.local can search accounts, work the error queue and read the audit log, and superadmin@demo.local can also change roles. Everyone else gets a plain "team only" page and a 403 from the API.

The web port lives in apps/web/.env and apps/api/.env has to name the same one in APP_PUBLIC_URL and BETTER_AUTH_URL. Auth checks the request Origin, so a mismatch fails sign in with a 403 that looks nothing like a port problem. localhost and 127.0.0.1 count as different origins too.

Or the whole thing in containers, with nothing installed but Docker:

docker compose up

That builds both images, migrates, seeds and serves http://localhost:3000. Only the web port is published: the browser talks to one origin and /api is forwarded internally.

Architecture

Browser ──► apps/web (Next.js, stateless)
              │  app/api/[...path]/route.ts ──► API_INTERNAL_URL
              ▼
           apps/api (Hono on Node, stateless)
              ├── Better Auth (sessions in the database)
              ├── Kysely ──► SQLite  or  Postgres
              ├── StorageDriver ──► local disk  or  S3 compatible
              ├── Jobs (portable table and poller)
              └── Notifications (push, email, Telegram)

apps/api is the only process that touches the database or storage. apps/web renders UI, holds no secrets beyond API_INTERNAL_URL, and reaches the API only through the typed client in packages/contracts. Because the browser only ever sees the web origin, cookies are first party and there is no CORS configuration anywhere.

Path	What lives there
apps/api	HTTP, auth, database, jobs, storage, notifications
apps/web	Every screen, PWA, no database access at all
packages/rules	Tax math, form definitions, calendario. Pure, no I/O
packages/contracts	Zod schemas and the typed API client
packages/i18n	Message catalogs, t(), formatGs, date formatting
deploy/	Compose stack and k8s manifests
docs/	The specifications this is built from

Module boundaries are enforced by eslint, not convention: packages/* cannot import from apps/*, only modules/pii reaches the PII tables, the web app cannot import a database driver, and user facing strings cannot be written inline in JSX.

Commands

Command	What it does
pnpm dev	Both apps in watch mode
pnpm test	Vitest across the workspace
pnpm test:coverage	The tax rules with coverage, which fails below 100%
pnpm test:e2e	Playwright against a running stack (E2E_BASE_URL to point it)
pnpm typecheck	tsc --noEmit in every package
pnpm lint	eslint, including the module boundary and inline copy rules
pnpm db:migrate	Auth tables, then our migrations
pnpm db:seed	Demo accounts and their comprobantes, idempotent
pnpm db:reset	Drops the local SQLite file and rebuilds it. Destructive, SQLite only
pnpm --filter @impuestos/api fixtures	Redraws the scan fixtures under /fixtures

Configuration

Every variable is documented in apps/api/.env.example and apps/web/.env.example, and validated with Zod at boot: a bad value stops the process with a message naming the variable and the problem. A test asserts .env.example and the schema never drift apart.

The two that decide everything else:

• DATABASE_URL picks the dialect. sqlite:./data/app.db or postgres://.... Nothing else selects it, and the same migrations run on both.
• STORAGE_DRIVER picks the file backend: local or s3. s3 additionally requires a bucket, a region and both keys, checked at boot.

Deployment modes

Mode	Database	Storage	api replicas	Worker
Combined (one VPS)	SQLite	local volume	1	inline
Split small	SQLite	shared volume	1	inline
Scaled (k8s)	Postgres	S3	N	1+ dedicated, JOBS_INLINE=false

Both apps are stateless: no in process state that breaks with N replicas, no local writes outside the storage driver, /healthz and /readyz on both, and SIGTERM fails readiness first, then drains in flight requests for up to 25 seconds before closing the pool.

Two things bound how far the combined mode scales, and both fail loudly rather than quietly corrupting: SQLite has a single writer, so the API refuses JOBS_INLINE=false and logs a scaling notice at boot; the local storage driver needs one shared volume across every replica, which it also says at boot. Scaling past one API replica means Postgres and S3. The k8s manifests assume both.

Rate limiting is in memory and therefore per replica. At this scale that is deliberate; the limiter is behind an interface for when it is not.

Installing it, offline and push

app/manifest.ts and the icons in apps/web/public make the web app installable; the icons are generated from one SVG by apps/web/scripts/generate-icons.mjs and committed, so a build never needs a browser.

The service worker (apps/web/src/lib/service-worker.js) caches the app shell and the /offline page and nothing else. No API response is cached: a tax figure that is quietly out of date is worse than one that is honestly missing.

A scan taken with no network is stored whole in IndexedDB and sent when there is one. The chip in the shell says so and clears itself.

Push needs VAPID keys on the API:

npx web-push generate-vapid-keys

Put them in apps/api/.env as PUSH_VAPID_PUBLIC_KEY and PUSH_VAPID_PRIVATE_KEY, plus PUSH_VAPID_SUBJECT (an https: or mailto: URL) unless APP_PUBLIC_URL is already https. Without keys the offer is hidden everywhere; with keys and no usable subject, push switches itself off and logs why rather than taking the API down.

Adding a locale

1. Add the code to SUPPORTED_LOCALES in packages/i18n/src/locales.ts.
2. Add one catalog file next to es.ts and en.ts, typed as Record<MessageKey, string>, so the compiler lists anything you missed.

That is the whole change. Routing, the switcher, the API's notification and error localization and the date formatting all read from that array. formatGs never localizes: money is always Gs. 1.234.567. Official form previews and PDFs stay Spanish in every locale, because they mirror DNIT forms.

The tax rules

Everything that decides a number lives in packages/rules and nothing there does I/O, so it is all directly testable. docs/RULES.md is authoritative for it and the module names follow that document's sections: ruc.ts, calendario.ts, cdc.ts, classification.ts, f120.ts, f515.ts, projections.ts.

Three rules hold the package together:

• No floats in a money path. Money is a branded Pyg of whole guaranies, percentages go through percentOf, which is integer arithmetic rounded half up, and pyg() throws on anything that is not a safe integer.
• Never guess a tax rule. Anything docs/RULES.md does not state carries a TODO-TAX-VERIFY comment and a test that pins today's behaviour, so verifying it later is a red/green diff. DECISIONS.md has the register of all six.
• Data, not code. The holiday table, the keyword to category map and the form definitions are plain data files. Extending them for a new year or a new keyword is not a code change.

Coverage is enforced at 100%: pnpm test:coverage fails below it.

Adding a form version

Form definitions live in packages/rules/src/forms and every declaration stores the rulesVersion that produced it, so an old declaration always renders with the rules it was computed under. Add f120.v2.ts beside f120.v1.ts, bump RULES_VERSION, and leave the old definition in place: it is what old declarations still render through.

Testing

Vitest covers the rules package, the API services against SQLite in memory, and catalog parity. Playwright covers the golden paths against a running stack. CI runs the suite against both SQLite and Postgres.

pnpm test:e2e does not start anything: bring the stack up first, then point it at the right origin. The suite signs in as the demo accounts and confirms, rejects and scans against their data, so it changes the state it runs in. Reset before a run, with the stack stopped, or the second run has a different bandeja than the first:

pnpm db:reset

Then start the stack and run it:

E2E_BASE_URL=http://localhost:3005 pnpm test:e2e

A dev server compiles each route the first time it is asked for, which is slow enough to push a sign in past the five seconds Playwright waits on a navigation. e2e/global-setup.ts asks for every screen once before the suite starts, so the cost is paid before the first test rather than by it. Against a heavily loaded dev server, one worker is still steadier than two:

E2E_BASE_URL=http://localhost:3005 npx playwright test --workers=1