VehicleOS

VehicleOS is free early access for car owners at app.vehicleos.app. MIT-licensed public repo for architecture, ADRs, and evals methodology — not a self-host product. This repository contains the product code and lightweight architecture artifacts.

What this project demonstrates

• Event-sourced domain model for durable state and explainability
• Deterministic policy engine for maintenance recommendations
• AI-assisted extraction and explanation with Owner verification on conflicts
• Monorepo architecture with separate marketing, product, API, and worker apps
• AI-native build: human-led architecture + agent-assisted implementation (Cursor)

License

MIT — see LICENSE. Showcase code is public for transparency, learning, and contributor review.

Public repo: Architecture showcase — see docs/open-core-boundary.md. Product: hosted early access at app.vehicleos.app.

Public URLs

URL	App	Purpose
app.vehicleos.app	apps/web	Product — free early access (sign in)
vehicleos.app	apps/marketing	Landing page
GitHub (this repo)	—	ADRs, domain model, evals — architecture showcase

Repository layout

apps/
  marketing/  Public landing site - Phase A live
  web/        Next.js product application → app.vehicleos.app
  api/        TypeScript API service
  worker/     Background jobs and extraction workers
packages/
  domain/     Domain events, models, and transition logic
  ui/         Shared UI primitives
  config/     Shared TypeScript and lint configuration
  prompts/    Versioned prompt assets and schema contracts
db/
  migrations/
  seeds/
infra/
  docker/     Local dev only (not a supported self-host product)
  terraform/
docs/
  01-architecture/
  02-repo-design/
  03-mvp-spec/
  04-lakehouse-v2/
  05-marketing-site/   Sitemap and landing page plan
docs-lite/
  adr/
  diagrams/
tests/
  integration/
  e2e/
evals/
  README.md
connectors/
  carfax-connect/   Import schema + CLI + TLX example (PDF-first · ADR-009)

First vertical slice target

Receipt upload → extraction → service.recorded event → projection update → recommendation → Owner verification (or future Reminders channel).

Quick start

1. Install Node 20+ and pnpm 9+.
2. Run pnpm install.
3. Run pnpm dev to start dev targets (marketing, web, api, worker).

Before a PR, run pnpm docs:check-links, pnpm typecheck, and pnpm test. Windows contributors can run the complete pinned build sequence with pnpm verify:windows.

See CONTRIBUTING.md for branch naming, PR workflow, and CI expectations.

Deployment (recommended)

App	Platform	Why
apps/marketing	Vercel	Next.js-native, fast marketing deploys, custom domain
apps/web (+ /api/*)	Vercel	Owners UI + golden-path API route handlers on app.vehicleos.app
Postgres	Supabase	Managed Postgres via DATABASE_URL — see docs/deployment/supabase-setup.md
apps/api	Local / optional	Fastify dev server; same @vehicleos/server as Vercel routes
apps/worker	Railway / Fly.io (later)	Background jobs when shipped — Postgres stays on Supabase

Vercel + Supabase is the default hosted stack for BUILD freeze. Railway/Fly are only needed when you deploy long-running workers, not for Postgres itself.

Deliberately not automated yet

• External scheduling and dealer APIs
• Insurance and registration automation
• Full conversational co-pilot for every workflow
• Marketing site Phase 2 pages (see docs/05-marketing-site/sitemap.md)

Key docs

• Contributing: CONTRIBUTING.md — branches, PRs, CI
• Vercel CD: docs/deployment/vercel-setup.md — preview + production deploys
• Supabase Postgres: docs/deployment/supabase-setup.md — hosted Owners DB + env vars
• ADR-004: docs-lite/adr/ADR-004-phase0-hosted-deployment.md — Phase 0 hosted stack decision
• ADR-005: docs-lite/adr/ADR-005-owners-only-positioning.md — Owners-only GTM
• ADRs: docs-lite/adr/
• System architecture: docs/01-architecture/system-architecture.md
• MVP spec: docs/03-mvp-spec/mvp-technical-spec.md
• Maintenance item intelligence: docs/03-mvp-spec/maintenance-item-intelligence.md
• Maintenance intelligence delivery queue: docs/03-mvp-spec/maintenance-item-intelligence-queue.md
• Marketing sitemap: docs/05-marketing-site/sitemap.md

Maintainer links

Dashboards

System	Link
CI	GitHub Actions · workflow
Marketing (Vercel)	Project dashboard
Product (Vercel)	Project dashboard
Live site	vehicleos.app · app.vehicleos.app

Docs

• CONTRIBUTING.md — branches, PRs, CI
• Vercel CD setup
• GitHub repo polish