hermes
3db7e47994
- 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
131 lines
6.6 KiB
Markdown
131 lines
6.6 KiB
Markdown
# InteriorScan MVP — Implementation Plan
|
|
|
|
> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
|
|
|
|
**Goal:** Build an interior photogrammetry SaaS that turns apartment photos into navigable 3D walkthroughs (Doom-map style).
|
|
|
|
**Architecture:** Turborepo monorepo (tpl-next-saas template). Next.js 16 App Router for web UI + dashboard. GPU worker (Node.js) orchestrates COLMAP/OpenMVS processing pipeline. three.js FPS viewer for walkthrough navigation. PostgreSQL + Drizzle for data. Valkey for queues/sessions. Stripe for billing.
|
|
|
|
**Tech Stack:** Next.js 16 · Drizzle ORM · PostgreSQL · Valkey · three.js · COLMAP · OpenMVS · Stripe · Biome · Vitest
|
|
|
|
---
|
|
|
|
## Constitution Check
|
|
|
|
| Principle | Status | Notes |
|
|
|---|---|---|
|
|
| I. Self-Hosted First | ✅ PASS | All infra self-hosted except Stripe |
|
|
| II. Progressive Experience | ✅ PASS | WebGL → 360° fallback, mobile tap-to-walk |
|
|
| III. FPS-Grade Immersion | ✅ PASS | WASD + mouse primary, tap-to-walk secondary |
|
|
| IV. Photo-First Capture | ✅ PASS | Mobile photos as baseline, LiDAR enhancement |
|
|
| V. API-First Architecture | ✅ PASS | API endpoints defined before UI |
|
|
| VI. TypeScript Strict | ✅ PASS | strict + noUncheckedIndexedAccess |
|
|
| VII. Test-First | ⚠ CONDITIONAL | TDD for business logic; 3D viewer tested via Playwright E2E |
|
|
| VIII. Open Formats | ✅ PASS | OBJ export in MVP, E57/DXF/IFC in P4+ |
|
|
|
|
⚠ VII conditional: 3D rendering correctness is validated via E2E visual regression, not unit tests. Business logic (upload, processing, auth) follows strict TDD.
|
|
|
|
---
|
|
|
|
## Data Model
|
|
|
|
See `data-model.md` (separate document — same directory).
|
|
|
|
---
|
|
|
|
## Phase 1: Monorepo Scaffold + Core Infra (Shared)
|
|
|
|
- [ ] T001 Create monorepo from tpl-next-saas template
|
|
- [ ] T002 Configure Drizzle schema with InteriorScan tables (projects, photos, walkthroughs, processing_jobs, users, teams, subscriptions)
|
|
- [ ] T003 Run migration: `pnpm db:migrate`
|
|
- [ ] T004 [P] Add seed data: 1 user, 1 team, 3 project statuses
|
|
- [ ] T005 [P] Set up Valkey connection for job queue
|
|
- [ ] T006 [P] Configure Docker Compose (postgres + valkey + web)
|
|
|
|
**Checkpoint**: Migration green, `pnpm dev` starts without errors, health endpoint returns 200.
|
|
|
|
---
|
|
|
|
## Phase 2: Photo Upload & Processing Pipeline (P1) 🎯 MVP Core
|
|
|
|
### 2A: Upload API
|
|
|
|
- [ ] T007 Write failing test: POST /api/v1/projects with photos returns 201 + project ID
|
|
- [ ] T008 Implement project creation endpoint with Zod validation
|
|
- [ ] T009 Write failing test: Upload 3 JPEGs → stored in object storage, DB has photo records
|
|
- [ ] T010 Implement photo upload with deduplication (perceptual hash)
|
|
- [ ] T011 Write failing test: GET /api/v1/projects/:id returns status + progress
|
|
- [ ] T012 Implement project status endpoint
|
|
|
|
**Checkpoint**: Upload 40 photos via API → receive project ID → poll status → see "queued".
|
|
|
|
### 2B: Processing Worker
|
|
|
|
- [ ] T013 Set up `apps/processor/` — Node.js worker with BullMQ/Valkey job queue
|
|
- [ ] T014 Write failing test: Job queued → worker picks up → runs COLMAP SfM → produces sparse point cloud
|
|
- [ ] T015 Implement COLMAP SfM step (feature extraction + matching + sparse reconstruction)
|
|
- [ ] T016 Write failing test: SfM output → OpenMVS dense reconstruction → mesh file produced
|
|
- [ ] T017 Implement OpenMVS dense reconstruction step (MVS + meshing + texturing)
|
|
- [ ] T018 Write failing test: Mesh + textures → tiled output for three.js streaming
|
|
- [ ] T019 Implement mesh processing + tiling step (LOD generation, Draco compression, texture atlas)
|
|
- [ ] T020 Implement progress reporting (Valkey pub/sub → web UI)
|
|
- [ ] T021 Write failing test: Processing failure → job marked failed → user notified
|
|
- [ ] T022 Implement error handling + retry logic
|
|
|
|
**Checkpoint**: Upload 40 photos → processing completes → produces OBJ mesh + tiled three.js output. Total time <60 min for 100 photos on GPU.
|
|
|
|
---
|
|
|
|
## Phase 3: 3D Viewer — FPS Walkthrough (P1) 🎯 MVP Core
|
|
|
|
- [ ] T023 Create `packages/viewer/` — three.js + Vite library package
|
|
- [ ] T024 Implement FPS camera controller (WASD + mouse look, collision detection, gravity)
|
|
- [ ] T025 Implement tap-to-walk controller (mobile: tap destination → navmesh pathfinding)
|
|
- [ ] T026 Implement mesh loader (tiled LODeD mesh streaming, Draco decompression)
|
|
- [ ] T027 Implement texture loading (progressive: low-res first, high-res on demand)
|
|
- [ ] T028 Implement mini-map overlay (bird's eye view with player position)
|
|
- [ ] T029 Implement measurement overlay toggle (room dimensions on walls/floor)
|
|
- [ ] T030 Implement WebGL fallback detection → 360° photo carousel mode
|
|
- [ ] T031 Implement touch controls (gyroscope look, pinch-zoom, two-finger walk)
|
|
- [ ] T032 Write Playwright E2E test: load walkthrough → verify 3D renders → verify WASD movement → verify tap-to-walk
|
|
|
|
**Checkpoint**: Open walkthrough link → walk through reconstructed space at 30+ FPS. WASD works. Click-to-walk works. Mini-map shows position.
|
|
|
|
---
|
|
|
|
## Phase 4: Web UI — Dashboard & Sharing (P1 + P2)
|
|
|
|
- [ ] T033 Create project creation flow (multi-step: name/address → photo upload → processing)
|
|
- [ ] T034 Create processing status page (progress bar, ETA, stage indicator)
|
|
- [ ] T035 Create walkthrough view page (embedded viewer + share controls)
|
|
- [ ] T036 Implement share link generation (public, no auth required)
|
|
- [ ] T037 Implement oEmbed embed code generator
|
|
- [ ] T038 Create dashboard grid (project cards with thumbnail, status, date)
|
|
- [ ] T039 Create project settings (edit name, address, delete)
|
|
|
|
**Checkpoint**: Agent creates project → uploads photos → sees processing progress → walkthrough appears → shares link → visitor navigates without login.
|
|
|
|
---
|
|
|
|
## Phase 5: Auth, Teams & Billing (P3)
|
|
|
|
- [ ] T040 Set up better-auth with email + Google OAuth
|
|
- [ ] T041 Implement RBAC (owner/admin/member/viewer per team)
|
|
- [ ] T042 Create subscription tiers (Free: 3/month, Pro: 25/month, Enterprise: unlimited)
|
|
- [ ] T043 Implement Stripe checkout + webhook
|
|
- [ ] T044 Implement usage tracking + quota enforcement middleware
|
|
|
|
**Checkpoint**: User signs up → creates 3 projects on Free → gets upgrade prompt → pays via Stripe → quota increases.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Launch
|
|
|
|
- [ ] T045 Landing page with demo walkthrough embedded
|
|
- [ ] T046 Pricing page with 3 tiers
|
|
- [ ] T047 Email notifications (processing complete, processing failed, quota warning)
|
|
- [ ] T048 Mobile-responsive dashboard with bottom nav
|
|
- [ ] T049 Accessibility audit (WCAG 2.2 AA): keyboard nav, screen reader, contrast
|
|
- [ ] T050 Performance audit (Core Web Vitals, first mesh load <5s on 4G)
|
|
|
|
**Checkpoint**: Real tester (monyi's friends) create walkthrough from phone photos in <1h total. Lighthouse 90+. |