impuestospy/docs/SPEC.md

SPEC.md: Paraguay Tax Platform v1, Technical Specification

Companion to PROMPT.md (constraints, phases), FLOWS.md (UX), RULES.md (tax logic), COPY.md (copy/i18n), CONTRACTS.md (API shapes, seed). This file defines architecture, data, modules, configuration and deployment.

---

1. Purpose and domain summary

Users are Paraguayan taxpayers identified by RUC (companies/independents) or CI (individuals). The platform ingests purchase/sale comprobantes, classifies them for IVA credit and IRP deductions, shows a live tax position, and produces pre-filled declarations:

• Formulario 120: monthly IVA declaration (debito from sales, credito from purchases).
• Formulario 515: annual IRP-RSP declaration (income minus deductible personal/family expenses).

Deadlines follow the calendario perpetuo (RULES.md section 3). Tax math, CDC parsing, classification and form computation live exclusively in packages/rules (RULES.md is authoritative). All money is integer guaranies, no floats anywhere in money paths.

---

2. Architecture overview

Browser ──► apps/web (Next.js, stateless)
              │  Next rewrites: /api/* ──► API_INTERNAL_URL
              ▼
           apps/api (Hono on Node, stateless)
              ├── Better Auth (sessions in DB)
              ├── Kysely ──► SQLite file  OR  Postgres
              ├── StorageDriver ──► local disk  OR  S3-compatible
              ├── Jobs (portable table + poller; inline or dedicated worker)
              └── Notifications (push/email/telegram fan-out)

• apps/api is the ONLY process touching the database and storage. It serves everything under /api, including the Better Auth routes.
• apps/web renders UI, holds zero secrets beyond API_INTERNAL_URL, and consumes the typed client from packages/contracts. Server Components may call the API server-side (forwarding cookies); all mutations go through TanStack Query on the client.
• Single-origin model: the browser only ever sees the web origin; the web app proxies /api/*. No CORS in v1. Exposing the API directly (mobile apps) is a future concern; do not add CORS scaffolding now.
• The dedicated worker is the same apps/api image started with ROLE=worker: it runs migrations check, the job poller and sweeps, and serves only /healthz. With ROLE=server (default) the poller runs inline only when JOBS_INLINE=true (default true, set false when a dedicated worker exists).

3. Stack

Layer	Choice
API	Hono on Node 22, @hono/node-server
Frontend	Next.js latest stable, App Router
Language	TypeScript strict everywhere
DB	Kysely; SQLite (better-sqlite3) default, Postgres (pg) supported
Auth	Better Auth in apps/api (email+password, email OTP, admin plugin)
i18n	packages/i18n catalogs; next-intl in web; same catalogs in api for errors/notifications
Server state	TanStack Query over the typed hono/client
UI	Tailwind + shadcn/ui + boneyard + GSAP + canvas-ui (2 spots)
Validation	Zod at every boundary
PDF	pdf-lib
QR	BarcodeDetector + zxing-wasm fallback (client-side)
OCR	Anthropic API behind OcrProvider; disabled gracefully without key
Jobs	Portable jobs table + poller (section 10)
Tests	Vitest, Playwright; CI matrix sqlite+postgres
Monorepo	pnpm workspaces: apps/api, apps/web, packages/rules, packages/contracts, packages/i18n

Pure packages (rules, contracts, i18n) have zero runtime deps besides Zod, no I/O, importable everywhere.

4. Repository layout and module boundaries

/apps/api
  /src
    /modules
      /pii              profiles, dependents, consents (ONLY module touching pii tables)
      /documents        comprobantes, files, ingestion pipeline
      /classification   rule application, bandeja logic
      /declarations     F120/F515 assembly, PDF
      /deadlines        calendario perpetuo, upcoming obligations
      /notifications    push/email/telegram fan-out, localized templates
      /audit            append-only audit writes + queries
      /jobs             poller, claim, handlers, sweeps
      /storage          StorageDriver: local | s3
      /admin            admin services (compose pii+audit)
    /auth               better-auth config, role guards
    /db                 kysely factories, migrations, seed
    /http               hono app, routes, error envelope, healthz/readyz
    /lib                env, cdc helpers, dates, formatGs (re-export from i18n)
  Dockerfile
/apps/web
  /app
    /[locale]
      /(marketing)      landing, RUC hook, legal
      /(auth)           login, register, verify
      /(app)            inicio, bandeja, comprobantes, declaraciones, vencimientos, perfil
      /(admin)          usuarios, errores, auditoria
  /src (components, query hooks, i18n wiring, pwa)
  Dockerfile
/packages/rules         tax math, form definitions, calendario (pure, RULES.md)
/packages/contracts     zod schemas + typed client (CONTRACTS.md)
/packages/i18n          catalogs es/en, typed t(), formatGs, date formatting per locale
/deploy
  docker-compose.yml    combined mode
  /k8s                  api.yaml, web.yaml, worker.yaml, ingress.yaml, configmap-example.yaml

Boundary rules (eslint no-restricted-imports): only modules/pii imports pii table types; UI never imports Kysely (web cannot: no DB deps in its package.json); packages/* import nothing from apps; user-facing strings only via packages/i18n (lint rule bans string literals in JSX text positions outside catalogs, allowlist for punctuation).

5. Database

Dialect from DATABASE_URL scheme. One Kysely Database interface (apps/api/src/db/schema.ts); factories createSqliteDb / createPostgresDb. Portable migrations via Kysely migrator:

• ids text UUIDv7 (app-generated), timestamps text ISO-8601 UTC, money integer guaranies, json text + Zod parse helper, booleans integer 0/1.
• Dialect-specific SQL only in the two factories and jobs/claim.ts.
• SQLite pragmas at boot: journal_mode=WAL, busy_timeout=5000, foreign_keys=ON.
• CI runs the whole suite on both dialects.

Tables (Better Auth manages its own; locale note: profiles.locale drives all server-side localization):

profiles (pii): user_id PK/FK, full_name, doc_type ('ruc'|'ci'), ruc, ruc_dv, ci, taxpayer_kind ('individual'|'company'), deadline_digit 0-9, obligations json [{code:'iva_120'|'irp_515', active, since}], irp_gross_estimate int null, auto_confirm_days int default 7 (0=off), locale ('es'|'en') default 'es', timestamps.

dependents (pii): id, user_id, display_name, relationship ('conyuge'|'hijo'|'padre'|'otro'), doc_number null, active, timestamps.

consents (pii): id, user_id, kind ('data_processing'|'notifications'), granted_at, revoked_at null, text_version.

document_files: id, driver ('local'|'s3'), path, mime, size, sha256, created_at.

documents: id, user_id, source ('scan_qr'|'scan_ocr'|'manual'), status ('needs_review'|'confirmed'|'rejected'), cdc null, qr_url null, doc_kind ('factura'|'autofactura'|'nota_credito'|'nota_debito'|'boleta_resimple'|'otro'), direction ('purchase'|'sale'), emitter_ruc, emitter_dv null, emitter_name, receiver_doc null, issue_date, currency 'PYG', total, amount_iva10, amount_iva5, amount_exenta, iva10, iva5, supplier_regime_hint ('normal'|'resimple'|'unknown'), verified_dnit bool, verification_status ('unverified'|'valid'|'invalid'|'error'), dedupe_hash, file_id null, raw_extraction json null, created_at, confirmed_at null. Unique (user_id, dedupe_hash).

classifications: document_id PK/FK, iva_credit_eligible, iva_credit_amount, irp_category (8 categories | 'none'), irp_deductible_amount, dependent_id null, confidence real, decided_by ('auto'|'user'|'staff'), rules_version, updated_at.

declarations: id, user_id, form_code ('120'|'515'), period, status ('draft'|'ready'|'approved'), values json, summary json, pdf_file_id null, rules_version, document_ids json, created_at, approved_at null, filed_marked_at null. Unique (user_id, form_code, period).

jobs: id, type, payload json, status ('pending'|'running'|'done'|'failed'|'dead'), run_at, attempts, max_attempts default 5, locked_by null, locked_at null, last_error null, timestamps. Index (status, run_at).

ingest_errors: id, user_id null, document_id null, stage ('qr_parse'|'ocr'|'dedupe'|'verify'|'job'|'other'), message, payload json, status ('open'|'resolved'), resolved_by null, resolved_at null, created_at.

audit_log (append-only): id, actor_user_id, actor_role, action, subject_user_id null, resource, detail json, ip null, created_at.

notification_prefs: user_id PK, push_enabled, email_enabled, telegram_chat_id null, digest_hour default 9.

push_subscriptions: id, user_id, endpoint, keys json, created_at.

6. Auth and roles

Better Auth in apps/api: email+password, email OTP verification. Roles: user (default), accountant (dormant), staff, superadmin. Sessions DB-backed (stateless replicas). Cookies: httpOnly, sameSite=lax, secure in production; issued on the web origin because auth routes are proxied like everything else. Role checks re-validated in every handler. Superadmin role changes audited. Rate limiting: token bucket keyed by IP, in-memory per replica in v1 behind a RateLimiter interface (per-replica limits are acceptable at this scale; note in README).

7. Storage

interface StorageDriver {
  put(key, data, mime): Promise<void>;
  getStream(key): Promise<ReadableStream>;
  delete(key): Promise<void>;
  url(key): Promise<string>; // signed URL (s3) or authenticated api route (local)
}

LocalDriver under STORAGE_LOCAL_PATH/<userId>/<uuid>, served via authenticated /api/files/:id (ownership or staff, audited for staff). S3Driver via AWS SDK v3, any S3-compatible endpoint, path-style option, signed GETs 10 min. Keys never contain user filenames. Scaling rule: local driver requires a single shared volume; multi-replica requires S3 or an RWX volume (boot check warns, section 15).

8. Ingestion pipeline

1. Client captures image, attempts QR decode locally, uploads file + optional qrPayload.
2. POST /api/documents/scan: store file; QR present → parse URL → CDC → prefill → create document scan_qr; enqueue verify_cdc (Noop v1) + classify_document.
3. No QR + ANTHROPIC_API_KEY set → enqueue ocr_extract (Zod-constrained extraction per RULES.md section 9; low confidence flags fields). No key → { needsManual: true, fileId }.
4. Dedupe on (user_id, dedupe_hash): merge, prefer QR-sourced data, return merged: true.
5. Classification via packages/rules; auto-confirm sweep respects profiles.auto_confirm_days.
6. Failures → ingest_errors + user-visible retry affordance. Offline: client queues in IndexedDB, syncs when online.

9. packages/rules

Implemented exactly per RULES.md (constants, RUC DV, calendario with holidays, CDC parsing, classification hints, computeF120, computeF515, projections). Exports RULES_VERSION, stamped on classifications and declarations. Test bar: RULES.md section 10.

10. Jobs

Portable poller inside apps/api:

• Runs when ROLE=worker, or inline when ROLE=server && JOBS_INLINE=true. Guard against duplicate pollers per process.
• Claim (jobs/claim.ts, the ONE dialect divergence): Postgres SELECT ... FOR UPDATE SKIP LOCKED then mark running with locked_by=<instanceId>; SQLite atomic conditional UPDATE ... WHERE status='pending' relying on single-writer serialization.
• Stale recovery: running jobs with locked_at older than JOBS_STALE_MINUTES (default 10) return to pending (crash safety).
• Retry backoff 1m/5m/25m/2h/12h, then dead (surfaced in admin errors as stage 'job').
• Types: ocr_extract, classify_document, verify_cdc (noop), generate_declaration_pdf, send_notification, deadline_sweep (daily), auto_confirm_sweep (daily), digest_sweep (hourly, respects per-user digest_hour and locale).
• Sweeps are idempotent (dedupe key per user+period+type in payload; skip if an identical done/pending job exists).

11. i18n (packages/i18n)

• Catalogs: es.ts (verbatim from COPY.md), en.ts (agent-written per COPY.md 0-EN), identical key sets enforced by a type-level check and a test.
• Typed t(locale, key, params) used by the API for: error envelope messages, notification/email/telegram templates, PDF cover labels (form bodies stay Spanish).
• Web: next-intl with [locale] routing, default es, language switcher in header and profile; switcher updates profiles.locale when authenticated (drives server-side notifications).
• Locale-aware date formatting; currency ALWAYS formatGs regardless of locale.
• Adding a locale = one new catalog file + adding the code to a SUPPORTED_LOCALES array.

12. API surface

As specified in CONTRACTS.md (shapes, error envelope, endpoints). Additions for this architecture:

• GET /healthz (liveness: process up) and GET /readyz (readiness: DB reachable, migrations current, storage driver responds) on the API; web exposes GET /healthz too.
• Localized error.message per requester locale (profile locale, else Accept-Language, else es).
• TanStack Query conventions: queryKeys ['me'], ['documents', filters], ['dashboard'], ['declarations'], ['deadlines'], ['admin', ...]; optimistic updates ONLY for bandeja confirm/reclassify.

13. Testing

• Vitest: rules exhaustive; api module services against SQLite in-memory; i18n key-parity test.
• Playwright golden paths (against compose stack): (1) onboarding, (2) scan QR fixture → bandeja confirm, (3) manual entry + classification edit, (4) F120 generate → approve → PDF, (5) admin lookup → audit row. Plus: language switch persists after reload; offline scan queued then synced.
• Behavior pins from CONTRACTS.md section 5. CI matrix: sqlite + postgres service.
• Scale tests (Phase 8): with Postgres and 2 worker processes, enqueue 100 jobs, assert each claimed exactly once; SIGTERM drains in-flight HTTP before exit.

14. Security and privacy

PII module boundary + audited staff access; audit append-only; files private by default; Zod on every input; no raw SQL interpolation; secrets only via env; CSP, self-hosted fonts, no third-party scripts; soft-delete users + purge job stub; data export ships in v1. .env.example completeness enforced by a script against the env schema.

15. Deployment and scaling

Configuration, apps/api/.env:

NODE_ENV=development
PORT=4000
APP_PUBLIC_URL=http://localhost:3000        # user-facing origin (links in emails)
ROLE=server                                  # server | worker
JOBS_INLINE=true
JOBS_POLL_INTERVAL_MS=2000
JOBS_STALE_MINUTES=10
DATABASE_URL=sqlite:./data/app.db            # or postgres://...
BETTER_AUTH_SECRET=change-me-32-chars-min
BETTER_AUTH_URL=http://localhost:3000        # public origin (cookies issued via proxy)
STORAGE_DRIVER=local                         # local | s3
STORAGE_LOCAL_PATH=./data/files
S3_ENDPOINT= S3_REGION= S3_BUCKET= S3_ACCESS_KEY_ID= S3_SECRET_ACCESS_KEY= S3_FORCE_PATH_STYLE=true
ANTHROPIC_API_KEY=                           # optional
OCR_MODEL=claude-sonnet-4-6
PUSH_VAPID_PUBLIC_KEY= PUSH_VAPID_PRIVATE_KEY=
SMTP_HOST= SMTP_PORT=587 SMTP_USER= SMTP_PASS= SMTP_FROM=
TELEGRAM_BOT_TOKEN=                          # optional
DEFAULT_LOCALE=es

apps/web/.env:

API_INTERNAL_URL=http://localhost:4000       # server-side proxy target (cluster DNS in k8s)
NEXT_PUBLIC_DEFAULT_LOCALE=es

Mode matrix (enforced by boot checks, hard fail or loud warn):

Mode	DB	Storage	api replicas	worker
Combined (compose, one VPS)	SQLite	local volume	1	inline
Split small	SQLite	local shared volume	1	inline or 1 dedicated
Scaled (k8s/k3s)	Postgres required	S3 required (or RWX volume)	N	1+ dedicated, JOBS_INLINE=false

Boot checks in apps/api: SQLite + ROLE=worker running alongside another poller is not detectable, so instead: if DATABASE_URL is SQLite, refuse JOBS_INLINE=false (forcing single-process mode) and log a scaling notice; if driver=local, log the shared-volume requirement.

docker-compose.yml (combined): two services (api, web), one named volume mounted to api for ./data (SQLite + files), healthchecks wired to /healthz, web depends_on api healthy, ports 3000 exposed only.

k8s manifests (deploy/k8s/): Deployments api (readiness /readyz, liveness /healthz, resources requests/limits, terminationGracePeriodSeconds: 30), web, worker (ROLE=worker, replicas 1 default, safe at N on Postgres); Services api+web (ClusterIP); Ingress to web only; ConfigMap/Secret examples; migrations run as an initContainer on api (pnpm db:migrate, safe concurrent: Kysely migrator + Postgres advisory lock taken in the migrate script). HPA example for api (CPU 70%). SQLite is explicitly unsupported on k8s manifests (values assume Postgres+S3); README says so.

Statelessness rules (both apps): no local file writes outside StorageDriver, no in-memory caches that affect correctness (rate limiter exempt and documented), push/OCR/SMTP clients constructed per process, graceful SIGTERM: stop accepting, drain (max 25s), close DB pool, exit 0.