# AutoFolio on the template

The repository's architectural decision, rationale and consequences.

# AutoFolio on the template

**Status:** accepted · **Date:** 2026-10-22 · **Related:** [ADR-0003](0003-organizations-are-the-tenant.md), [ADR-0009](0009-row-level-security.md), [ADR-0011](0011-backend-feature-shape.md), [ADR-0013](0013-mobile-features-mirror-the-backend-shape.md)

The product handoff in `handoff/` (read-only) was written for an empty monorepo: `apps/api`, `packages/domain`, `packages/db`, `packages/tokens`, `packages/i18n`, and its own `users`/`households`/`memberships` tables. This repository already has authentication, tenancy with row-level security, oRPC, Effect at the edges, R2 uploads, a cron queue, i18n and an Expo app. We build AutoFolio on it instead of beside it.

## Decision [#decision]

The handoff wins on product, design and business rules. This repository's `AGENTS.md` and ADRs win on structure. The mapping:

| Handoff                                         | Here                                                                                                                                                                                                                                                                            |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps/api` (Hono or oRPC)                       | `packages/api/src/features/<feature>/`, served by the `apps/web` Worker over oRPC. Endpoints in PRD §ARD become procedures with the same meaning.                                                                                                                               |
| `users` (locale, currency, units, region, plan) | Better Auth `user` plus an `account_preference` row per user (locale, main currency, distance and volume unit, data region, reminder channels). Plan comes from billing entitlements; no entitlement means Free (a deployment with no billing provider enforces no Free limit). |
| `households`, `memberships`                     | The Better Auth Organization is the household (ADR-0003). Every AutoFolio table carries `organization_id` and is isolated by RLS (ADR-0009). Per-vehicle roles for the family garage (v1.2) are a `vehicle_member` table.                                                       |
| ★ append-only tables                            | RLS grants without UPDATE/DELETE for `app_tenant`, plus a trigger that rejects UPDATE/DELETE for every role. Corrections are new rows with a reason.                                                                                                                            |
| `packages/domain`                               | `packages/domain`, a client-safe package with no imports beyond itself: `reference/domain` ported as is, tests run by vitest.                                                                                                                                                   |
| `packages/tokens`                               | `packages/tokens`, generated from `handoff/design/tokens.json` into a React Native theme and CSS variables.                                                                                                                                                                     |
| `packages/i18n`                                 | Product strings from `handoff/i18n/*.json` become the mobile locales `pt-BR`, `en`, `de` (i18next, flat keys) and the web dictionaries. The template's `fr` locale is dropped: AutoFolio ships three languages.                                                                 |
| `apps/web` (TanStack Start)                     | `apps/web`: D-Site replaces the template landing, plus D-Privacidade and the buyer passport `/p/:token`.                                                                                                                                                                        |
| Postgres queue                                  | The existing one-minute cron tick and leased jobs (ADR-0005, ADR-0006).                                                                                                                                                                                                         |
| CI                                              | Not used for now. Every check runs locally (typecheck, lint, tests, Maestro, agent-browser).                                                                                                                                                                                    |

The template's `todo` example feature is removed once the garage replaces it as the home of the app.

## Consequences [#consequences]

- Isolation, auth, uploads and jobs are reused, so AutoFolio work is product work.
- Data region per account (ADR-07 of the handoff) is stored now and enforced later; there is one database until the EU launch needs more.
- The handoff's `testID`s, deep link `autofolio://dev/<board>` and Maestro flows are kept as they are. The Maestro `APP_ID` is `io.zietec.autofolio`.