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,46 @@
+# InteriorScan Constitution
+
+## Core Principles
+
+### I. Self-Hosted First (NON-NEGOTIABLE)
+All infrastructure must be self-hosted or FOSS. The ONLY external SaaS dependency is Stripe for billing. Database: PostgreSQL. Cache/sessions: Valkey. Processing: own GPU nodes. No vendor lock-in on reconstruction pipeline, viewer, or storage.
+
+### II. Progressive Experience
+Every feature must degrade gracefully. If WebGL fails, show 360° fallback. If processing fails, show uploaded photos. No feature should have a single point of failure that blocks the entire experience.
+
+### III. FPS-Grade Immersion
+The 3D viewer is not a "virtual tour" — it is a navigable space. Controls feel like a first-person game: WASD + mouse on desktop, tap-to-walk on mobile. Smooth movement, collision detection, gravity, head-bob optional. If it feels like a slideshow, it's wrong.
+
+### IV. Photo-First Capture
+Mobile phone is the only required hardware. iPhone LiDAR and 360° cameras are enhancements, not prerequisites. A real estate agent with an Android phone must be able to capture and publish a walkthrough in under 30 minutes.
+
+### V. API-First Architecture
+Every feature exposed via REST API before UI. InteriorScan is a reconstruction-as-a-service platform that happens to have a web UI, not a walled garden. White-label and embeddable viewers are first-class use cases.
+
+### VI. TypeScript Strict
+`strict: true` + `noUncheckedIndexedAccess: true`. No `any` without explicit justification. Zod for runtime validation. neverthrow for error handling in business logic.
+
+### VII. Test-First (NON-NEGOTIABLE)
+TDD mandatory: write failing test → user approves test → verify test fails → implement → verify test passes. No untested API endpoints, no untested business logic.
+
+### VIII. Open Formats
+All reconstruction outputs (mesh, point cloud, floor plan) must be exportable in open formats: OBJ, E57, LAS/LAZ, DXF, IFC (P4+). Proprietary lock-in is antithetical to this project's mission.
+
+## Additional Constraints
+
+- **Stack**: Next.js 16 App Router, Drizzle ORM, PostgreSQL, Valkey, three.js
+- **Monorepo**: Turborepo + pnpm (tpl-next-saas template)
+- **Billing**: Stripe only — no other payment/subscription SaaS
+- **Lint/Format**: Biome 2.x ONLY — zero ESLint, zero Prettier
+- **Testing**: Vitest v4 + Playwright
+- **Design**: WCAG 2.2 AA minimum, d0a1 design palettes
+- **Language**: Code/docs/commits in English. Team speaks Spanish.
+
+## Governance
+
+- Constitution supersedes all other practices
+- Amendments require documentation, approval, and migration plan
+- All PRs/reviews must verify compliance
+- Retro-propagation: patterns validated in production must be PR'd back to `agentic-standards`
+
+**Version**: 1.0.0 | **Ratified**: 2026-05-28 | **Last Amended**: 2026-05-28