# 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 0 — Property Setup via Catastro (Priority: P1) 🎯 MVP Entry

As a real estate agent, I enter a property address and InteriorScan fetches the building's exterior footprint from the Spanish Cadastro (INSPIRE WFS), so the 3D model starts with verified exterior walls before I upload any photos.

**Why this priority**: The Catastro provides the SSOT for exterior geometry — wall outlines, building height, and number of floors. This eliminates manual exterior wall drawing and ensures dimensional accuracy. Interior walls come from photos or user-uploaded floor plans.

**Independent Test**: Enter "C/ Altabix 24, Elche" → refcat is resolved → building polygon is displayed on a minimap → exterior walls are generated in the 3D scene.

**Acceptance Scenarios**:
1. **Given** I am creating a new project, **When** I type a Spanish address and submit, **Then** the system resolves it to a cadastral reference (refcat) and fetches the building footprint polygon from INSPIRE WFS.
2. **Given** a building footprint is fetched, **When** the 3D scene initializes, **Then** exterior walls appear at the correct dimensions matching the Catastro polygon, with the correct number of floors.
3. **Given** the Catastro lookup fails, **When** no polygon is found, **Then** the system falls back to manual wall drawing or DXF/SVG upload.

### 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 where potential buyers 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