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
This commit is contained in:
@@ -0,0 +1,121 @@
|
||||
# Feature Specification: InteriorScan MVP
|
||||
**Feature Branch**: `feat/001-interiorscan-mvp`
|
||||
**Status**: Draft — Awaiting Approval
|
||||
|
||||
## Vision Statement
|
||||
|
||||
**InteriorScan turns apartment photos into a navigable 3D space** — like a Doom map of a real home. Real estate agents photograph a property, upload to InteriorScan, and share a link where potential buyers walk through the space in first-person. This filters out properties that don't fit, saving both agents and buyers from unnecessary physical visits.
|
||||
|
||||
## User Scenarios & Testing
|
||||
|
||||
### User Story 1 — Upload & Process (Priority: P1) 🎯 MVP Core
|
||||
|
||||
As a real estate agent, I upload 30-100 photos of a property and InteriorScan reconstructs the interior as a 3D walkthrough, so I can share a link with potential buyers who navigate it like a first-person game.
|
||||
|
||||
**Why this priority**: Without reconstruction, nothing else matters. This is the core value proposition.
|
||||
|
||||
**Independent Test**: Upload photos → receive a shareable walkthrough URL. A visitor opens URL → navigates space in first-person.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
1. **Given** I am logged in, **When** I create a new project, upload 40+ JPEG photos of an interior, and submit for processing, **Then** the system accepts the upload, shows a processing status (queued → processing → complete), and within 60 minutes produces a 3D walkthrough.
|
||||
2. **Given** a walkthrough has completed processing, **When** I open the shareable link in a desktop browser, **Then** I see the reconstructed 3D space with WASD + mouse controls, collision detection, and texture-mapped walls/floors/ceilings.
|
||||
3. **Given** a walkthrough has completed processing, **When** I open the shareable link on a mobile browser, **Then** I see the reconstructed 3D space with tap-to-walk navigation and gyroscope look-around option.
|
||||
|
||||
### User Story 2 — Share & Embed (Priority: P1) 🎯 MVP Distribution
|
||||
|
||||
As a real estate agent, I can share a walkthrough link or embed the viewer on any listing page, so potential buyers encounter the 3D tour wherever they find the property.
|
||||
|
||||
**Why this priority**: The walkthrough is useless without distribution. Sharing and embedding are how real estate works.
|
||||
|
||||
**Independent Test**: Agent shares link → opens in new tab. Agent copies embed code → pastes on WordPress/listing → viewer renders.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
1. **Given** a completed walkthrough, **When** I click "Share", **Then** I get a copyable link and an oEmbed-embeddable iframe snippet.
|
||||
2. **Given** an embed snippet, **When** I paste it into a website, **Then** the InteriorScan viewer renders inline with all navigation controls functional.
|
||||
3. **Given** a shared link, **When** an unauthenticated visitor opens it, **Then** they can navigate the full walkthrough without signing up (public access).
|
||||
|
||||
### User Story 3 — Dashboard & Projects (Priority: P2)
|
||||
|
||||
As a real estate agent, I manage all my properties from a dashboard, so I can track processing status, edit metadata, and organize my portfolio.
|
||||
|
||||
**Why this priority**: Essential for retention but not for first-value. A single walkthrough proves the concept.
|
||||
|
||||
**Independent Test**: Agent creates 3 projects → sees them in dashboard → edits name/address → deletes one.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
1. **Given** I am logged in, **When** I visit the dashboard, **Then** I see a grid of my projects with thumbnail, name, address, processing status, and date.
|
||||
2. **Given** a project exists, **When** I edit its name or address, **Then** the changes persist and appear in the walkthrough metadata.
|
||||
3. **Given** I have 3 projects, **When** I delete one, **Then** it is removed from the dashboard and its data is scheduled for cleanup within 24h.
|
||||
|
||||
### User Story 4 — API Access (Priority: P2)
|
||||
|
||||
As a developer integrating InteriorScan, I can upload photos and retrieve walkthroughs via REST API, so I can embed reconstruction into my own platform.
|
||||
|
||||
**Why this priority**: API-first is a constitution principle, but the web UI validates the pipeline first. API follows proven flow.
|
||||
|
||||
**Independent Test**: `POST /api/v1/projects` with photos → `GET /api/v1/projects/:id` returns status → `GET /api/v1/projects/:id/walkthrough` returns viewer URL.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
1. **Given** I have an API key, **When** I POST photos to `/api/v1/projects`, **Then** I receive a project ID and a `Location` header for status polling.
|
||||
2. **Given** a project is processing, **When** I GET `/api/v1/projects/:id`, **Then** I receive `{status: "processing", progress: 45, estimatedCompletion: "..."}`.
|
||||
3. **Given** a project is complete, **When** I GET `/api/v1/projects/:id/walkthrough`, **Then** I receive the viewer URL and embed snippet.
|
||||
|
||||
### User Story 5 — Measurements & Floor Plans (Priority: P3)
|
||||
|
||||
As a buyer, I can see room dimensions overlaid on the walkthrough and download a floor plan, so I can evaluate if furniture fits without visiting.
|
||||
|
||||
**Why this priority**: Differentiates from pure 360° tours but requires accurate reconstruction. Comes after core pipeline is proven.
|
||||
|
||||
**Independent Test**: Open walkthrough → toggle measurements → see room dimensions in meters.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
1. **Given** a walkthrough with LiDAR data, **When** I toggle "Show Measurements", **Then** room dimensions appear as overlays on walls and floor (±5% accuracy).
|
||||
2. **Given** a completed walkthrough, **When** I click "Download Floor Plan", **Then** I receive a PDF/DXF floor plan with labeled rooms and dimensions.
|
||||
|
||||
### User Story 6 — Subscription & Billing (Priority: P3)
|
||||
|
||||
As an agent, I subscribe to a plan (Free/Pro/Enterprise) that determines how many walkthroughs I can create per month, so I only pay for what I use.
|
||||
|
||||
**Why this priority**: Revenue model, but not needed to validate the core pipeline.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
1. **Given** I am on the Free plan, **When** I attempt to create my 4th walkthrough, **Then** I see an upgrade prompt with Pro plan pricing.
|
||||
2. **Given** I upgrade to Pro, **When** payment is confirmed via Stripe, **Then** my walkthrough limit increases to 25/month and the badge updates.
|
||||
|
||||
## Edge Cases
|
||||
|
||||
- **Fewer than 20 photos**: System rejects with guidance on minimum coverage
|
||||
- **Corrupt/unreadable photos**: System skips corrupt files, warns user, continues with valid ones
|
||||
- **Processing failure**: System retries once, then marks as "failed" with error details and refund option
|
||||
- **Very large spaces (>200 photos)**: System queues with estimated time, processes in chunks
|
||||
- **Mobile browser without WebGL**: Fallback to 360° photo carousel (progressive enhancement)
|
||||
- **Duplicate photos**: System deduplicates by perceptual hash before processing
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional Requirements
|
||||
- **FR-001**: System MUST accept 20-500 JPEG/PNG photos per project via web upload or API
|
||||
- **FR-002**: System MUST reconstruct 3D mesh from photos using COLMAP/OpenMVS pipeline
|
||||
- **FR-003**: System MUST provide first-person navigation (WASD + mouse) in desktop browsers
|
||||
- **FR-004**: System MUST provide tap-to-walk navigation in mobile browsers
|
||||
- **FR-005**: System MUST generate shareable public links for completed walkthroughs
|
||||
- **FR-006**: System MUST provide oEmbed-embeddable iframe code
|
||||
- **FR-007**: System MUST show processing status: queued → processing → complete (with progress %)
|
||||
- **FR-008**: System MUST handle processing failures gracefully with retry + notification
|
||||
- **FR-009**: System MUST export walkthrough data in open formats (OBJ minimum)
|
||||
- **FR-010**: System MUST work on iPhone, Android, desktop Chrome, Firefox, Safari
|
||||
|
||||
### Non-Functional Requirements
|
||||
- **NFR-001**: Walkthrough viewer MUST load initial mesh in <5 seconds on 4G
|
||||
- **NFR-002**: Navigation MUST run at ≥30 FPS on mid-range 2024 devices
|
||||
- **NFR-003**: Processing MUST complete within 60 minutes for 100 photos
|
||||
- **NFR-004**: System MUST handle 10 concurrent processing jobs
|
||||
- **NFR-005**: Walkthrough links MUST work without authentication (public)
|
||||
- **NFR-006**: API MUST follow OpenAPI 3.1 spec with Zod-validated schemas
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- **SC-001**: First tester uploads 40 photos → walks through reconstructed kitchen in <10 min total
|
||||
- **SC-002**: Unauthenticated visitor opens shareable link → navigates fluently at 30+ FPS
|
||||
- **SC-003**: Processing pipeline produces visual quality comparable to Matterport's basic tier
|
||||
- **SC-004**: 3 of monyi's tester friends complete a walkthrough creation within 1 hour of onboarding
|
||||
Reference in New Issue
Block a user