# Developer documentation
Build, run and extend AutoFolio, the lifelong garage for current, sold and wished-for cars.
AutoFolio keeps each car's costs, maintenance, documents and photos for life, shows an honest net worth, closes a sale with the deal result and the economic result apart, and shares a privacy-safe passport with a buyer. It ships in Portuguese (Brazil), English and German. An Expo app holds the garage; one Cloudflare Worker serves the site, the buyer passport at `/p/:token`, authentication, the typed API and scheduled jobs. Postgres stores the household's records under row-level security; R2 stores private photos and documents.
The product, screens and business rules come from the read-only handoff in `handoff/`. The code is built on a full-stack template whose auth, tenancy, uploads and jobs it reuses; [ADR-0014](/docs/adr/0014-autofolio-on-the-template) maps one onto the other and [ADR-0015](/docs/adr/0015-autofolio-data-model) records the data model.
Environment, a local database, the demo garage and the dev client.
Follow a request and learn the server boundary.
Garage, money, service, sharing, AI, appearance and the platform under them.
See what landed and why it matters.
## Quickstart [#quickstart]
```sh
git clone https://github.com/CarlosZiegler/autofolio.git
cd autofolio
pnpm install
pnpm run setup
pnpm run db:migrate
DEV_SEED_LOGIN=true pnpm dev:web
```
pnpm 11 has built-in `setup` and `doctor` commands, so the repository's scripts need `pnpm run`. The web runs at `http://localhost:3005`; `DEV_SEED_LOGIN=true` lets the dev links sign into a demo garage loaded from `handoff/data/seed.json`. The project runs locally for now: use a local or Docker Postgres, apply reviewed migrations and never push the schema. [Local setup](/docs/development/setup) covers the database, the Expo dev client, the `autofolio://dev/` links and the end-to-end flows.
## What is in the app [#what-is-in-the-app]
The mobile app has four tabs, Garage, Finances, Service and Profile. It covers adding cars from the catalog, purchase, trade-in and financing, expenses with duplicate warnings and an offline queue, recurring expenses, spreadsheet import, services, maintenance plans and alerts, documents, photos, history, net worth, insights, closing a sale, passports, history transfer, data export and account deletion. The family garage (with invite links and QR), the cost assistant and partner shops are later releases already built behind their boards.
Built on top, behind flags that are off by default:
- **AI** ([AI foundation](/docs/features/ai)): the [document scanner](/docs/features/scanner) and shoebox, the [Cinematic Studio](/docs/features/studio), [copilot cards](/docs/features/assistant#copilot-cards), [proactive insights](/docs/features/insights#proactive-insights-ai-spec-4) with the monthly summary and the dashboard photo, and the [AI extras](/docs/features/ai-extras). A model only fills a draft the person confirms, and every figure it shows comes from the records.
- **Social**: [Moments and share cards](/docs/features/moments) made on the phone, [showcase links](/docs/features/showcase) at `/g/:token`, and the [shared garage](/docs/features/family-garage#invite-by-link-or-qr) by link or QR with its activity line.
- **[Appearance](/docs/features/appearance)**: Monochrome (the default), Car colour and Warm, in the app and the signed-in web.
The web has the marketing site (`/`), the privacy page (`/privacy`), the buyer passport (`/p/:token`, live or revoked), the public showcase (`/g/:token`), the invite page (`/i/:token`), the partner portal (`/partners`, v2 vision), these docs, and the template's account and admin pages in the AutoFolio style.
The product rules of the AI and social boards are in [`docs/specs/ai-features.md`](https://github.com/CarlosZiegler/autofolio/blob/main/docs/specs/ai-features.md) and [`docs/specs/social-sharing.md`](https://github.com/CarlosZiegler/autofolio/blob/main/docs/specs/social-sharing.md), each with what is built and what is deferred. The domain words are in [`CONTEXT.md`](https://github.com/CarlosZiegler/autofolio/blob/main/CONTEXT.md).
## Stack at a glance [#stack-at-a-glance]
| Layer | Choice |
| ----------------- | ---------------------------------------------------------------------------- |
| Web | TanStack Start 1.0, React, Vite, Tailwind CSS and shadcn/Base UI |
| Native | Expo, Expo Router and React Native |
| API and contracts | oRPC, Zod and TanStack Query |
| Identity | Better Auth with Organizations, passkeys and two-factor |
| Data | Drizzle, Postgres/Neon and Cloudflare Hyperdrive |
| Background work | Stable Effect APIs and durable Drizzle leases |
| Agents | Shared tool catalog, TanStack AI and MCP OAuth |
| Documentation | Headless Fumadocs MDX/core, static highlighting and server-rendered articles |
The [library reference](/docs/libraries) records pinned versions and upgrade policy.
## Platform from the template [#platform-from-the-template]
Authentication and account security, Organizations (an AutoFolio household), files, imports, admin management, audit records, feature flags, three-language app chrome, transactional email, provider-gated payments, AI approvals, MCP tools, OG images and agent-readable pages. Native purchases, widgets and ads have explicit activation paths; installed code does not imply configured providers.
## How these docs are organized [#how-these-docs-are-organized]
The pages are arranged by altitude, from the map down to templates. Read only as far down as you need.
| Altitude | Question | Where |
| ----------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Map | Where do I look? | This page |
| Principles | Why is it shaped this way? | [Architecture](/docs/architecture) |
| Conventions | What is the exact rule? | [Backend conventions](/docs/development/backend-conventions), [Conventions](/docs/development/conventions), [Features](/docs/features) |
| Reference | What exists, and what checks it? | [Packages](/docs/packages), [Review checklist](/docs/development/review-checklist), [Enforcement](/docs/development/enforcement) |
| Templates | Give me the files. | The `domain-feature` skill in `.agents/skills/` |
| Process | How do these evolve? | [Decisions](/docs/adr), [Changelog](/docs/changelog), [Runbooks](/docs/development/runbooks) |
## Repository map [#repository-map]
{`apps/web/ Site, passport, account pages, docs content and Worker entry
apps/mobile/ Expo screens, hooks and native registration
packages/api/ oRPC features: AutoFolio's beside the template's
packages/domain/ Money, ledger and business rules from the handoff
packages/tokens/ Design tokens for React Native and CSS
packages/ Other shared platform packages
handoff/ Product spec, screens, seed and e2e flows (read-only)
docs/ ADRs, operations guides and measurements
scripts/ Verification, migrations and deployment helpers
.agents/skills/ Project workflows for contributors`}
Docs articles are written in English. Navigation controls follow the app language (Portuguese, English or German). Architectural decisions are [rendered from their original files](/docs/adr), so there is one source of truth.