# 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 0 of 8.** Foundation only. There is no tax logic, no ingestion and no
> dashboard yet: `packages/rules` is waiting on `docs/RULES.md`, which is not in the repo.

---

## Quick start

```bash
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:3000, the API on http://localhost:4000. `db:seed`
prints the development sign in details for the four demo accounts.

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

```bash
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: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, idempotent |

## 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.

## 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.

## Adding a form version

Form definitions live in `packages/rules` and every declaration stores the `rulesVersion`
that produced it, so an old declaration always renders with the rules it was computed
under. Bump `RULES_VERSION`, add the new definition beside the old one, and leave the old
one in place. (Fully specified once `docs/RULES.md` lands.)

## 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.

```bash
E2E_BASE_URL=http://localhost:3000 pnpm test:e2e
```