docs: add constitution, spec, plan, and data model for InteriorScan MVP

- Constitution: self-hosted first, FPS-grade immersion, mobile-first capture, API-first, open formats - Spec: 6 user stories (upload & process, share & embed, dashboard, API, measurements, billing) - Plan: 6 phases, 50 tasks, Phase 1-3 = MVP core - Data model: Drizzle schema with projects, photos, walkthroughs, processing_jobs, subscriptions
2026-05-28 20:26:22 +02:00
parent f44b1543d5
commit 3db7e47994
6 changed files with 634 additions and 2 deletions
@@ -0,0 +1,71 @@
+# InteriorScan — AGENTS.md
+
+## Project Overview
+
+InteriorScan is a SaaS platform for interior photogrammetry targeting real estate. Users upload photos of a property, the system reconstructs a 3D mesh, and visitors navigate the space in first-person (WASD + click-to-walk) — like a Doom map of a real apartment.
+
+**Purpose**: Filter properties before physical visits. Save time for buyers and agents.
+
+**Stack**: Next.js 16 App Router · Turborepo · Drizzle ORM · PostgreSQL · Valkey · three.js · COLMAP/OpenMVS · Stripe
+
+**Repo**: https://git.d0a1.es/hermes/interiorscan
+
+## Architecture
+
+```
+interiorscan/
+├── apps/web/                    # Next.js 16 App Router (SSR + client)
+│   ├── src/app/(marketing)/     # Landing, pricing, public pages
+│   ├── src/app/(saas)/          # Auth-guarded dashboard
+│   ├── src/app/api/             # Webhooks, health, processing callbacks
+│   └── src/lib/3d/              # three.js viewer components (FPS controls, mesh loader)
+├── apps/processor/              # Node.js worker — orchestrates COLMAP/OpenMVS pipeline
+├── packages/
+│   ├── auth/                    # better-auth + RBAC
+│   ├── db/                      # Drizzle schema + migrations
+│   ├── ui/                      # shadcn/ui v4 + Tailwind tokens
+│   ├── utils/                   # Zod schemas, neverthrow, error catalog
+│   └── ts-config/               # Shared TS configs
+├── docker/                      # Docker Compose (web + postgres + valkey + GPU worker)
+└── .specify/                    # Constitution, specs, plans
+```
+
+## Constitution
+
+See `.specify/memory/constitution.md` — all development must comply.
+
+## Key Decisions
+
+- **FPS navigation**: WASD + click-to-walk (both modes). Not 360° panos.
+- **Mobile-first capture**: iPhone/Android photos as baseline. LiDAR = enhancement.
+- **Self-hosted**: All infra self-hosted except Stripe.
+- **API-first**: Every feature has REST API before UI.
+- **Open exports**: OBJ, E57, LAS/LAZ, DXF minimum. IFC in P4+.
+
+## Development Commands
+
+```bash
+pnpm install          # Install dependencies
+pnpm dev              # Start dev server (all apps)
+pnpm build            # Production build
+pnpm test             # Run Vitest
+pnpm lint             # Biome check
+pnpm typecheck        # TypeScript strict check
+```
+
+## Standards Reference
+
+| Layer | Choice | Standard |
+|---|---|---|
+| Auth | better-auth | [SECURITY.md](https://git.d0a1.es/d0a1-agentic-crew/agentic-standards/src/branch/main/standards/SECURITY.md) |
+| Design | d0a1 palettes | [DESIGN_SYSTEM.md](https://git.d0a1.es/d0a1-agentic-crew/agentic-standards/src/branch/main/standards/DESIGN_SYSTEM.md) |
+| CSS | #app[data-theme] selectors | Design system token pattern |
+| Lint | Biome 2.x only | [STANDARDS.md](https://git.d0a1.es/d0a1-agentic-crew/agentic-standards/src/branch/main/standards/STANDARDS.md) |
+| Testing | Vitest v4 + Playwright | tpl-next-saas pattern |
+
+## Branch Strategy
+
+- `main` — production-ready
+- `feat/###-description` — feature branches from spec IDs
+- `fix/description` — bugfixes
+- Conventional commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`