Upload docs/PRODUCT_ARCHITECTURE.md

docs/PRODUCT_ARCHITECTURE.md

@@ -0,0 +1,355 @@
+# InteriorFusion: AI Interior Designer — Product Architecture
+
+## Product Vision
+
+**"Any room photo → editable 3D design space in 30 seconds"**
+
+Transform interior design from a manual, weeks-long process into an AI-assisted, real-time creative tool. Users upload a room photo, and InteriorFusion creates a complete 3D scene they can redesign, refurnish, and redecorate — all before their coffee gets cold.
+
+---
+
+## Feature Matrix
+
+### Core Features
+
+| Feature | Description | Priority | Status |
+|---------|-------------|----------|--------|
+| **Photo Upload** | Upload any room photo | P0 | ✅ Prototype |
+| **3D Room Generation** | Generate complete 3D scene | P0 | ✅ Prototype |
+| **Furniture Editing** | Move/remove/scale objects | P0 | ✅ Design |
+| **Material Swap** | Change wall/floor/furniture materials | P0 | ✅ Design |
+| **Relight Room** | Adjust lighting, add light sources | P1 | 📝 Planned |
+| **Style Transfer** | Transform to different interior styles | P1 | 📝 Planned |
+| **Export to Blender** | One-click Blender import | P0 | ✅ Prototype |
+| **Export to UE5** | Direct Unreal Engine asset export | P1 | 📝 Planned |
+| **Export to Unity** | Unity package export | P1 | 📝 Planned |
+| **AR Preview** | View in real room via phone AR | P1 | 📝 Planned |
+| **Furniture Recommendations** | AI-suggested furniture from catalog | P2 | 📝 Planned |
+| **Room Style Quiz** | "What style is this room?" | P2 | 📝 Planned |
+| **Before/After Comparison** | Side-by-side design iterations | P1 | 📝 Planned |
+| **Design Share** | Share interactive 3D scenes via URL | P1 | 📝 Planned |
+| **Professional Report** | Generate PDF design proposal | P2 | 📝 Planned |
+
+### Interior Style Support
+
+| Style | Training Data | Quality Target |
+|-------|--------------|---------------|
+| **Modern** | 3D-FRONT + Pinterest | ⭐⭐⭐⭐⭐ |
+| **Scandinavian** | 3D-FRONT + InteriorNet | ⭐⭐⭐⭐⭐ |
+| **Luxury / High-end** | 3D-FRONT luxury subset | ⭐⭐⭐⭐ |
+| **Indian / Traditional** | Custom dataset + Pinterest | ⭐⭐⭐⭐ |
+| **Commercial / Office** | HM3D office scenes | ⭐⭐⭐⭐ |
+| **Industrial** | 3D-FRIND + InteriorNet | ⭐⭐⭐⭐ |
+| **Minimalist** | 3D-FRONT + curated | ⭐⭐⭐⭐ |
+| **Bohemian** | Pinterest + custom | ⭐⭐⭐ |
+| **Japanese** | Custom dataset | ⭐⭐⭐ |
+| **Art Deco** | Curated subset | ⭐⭐⭐ |
+
+### Room Type Support
+
+| Room Type | Supported | Notes |
+|-----------|-----------|-------|
+| **Living Room** | ✅ Full | Best supported |
+| **Bedroom** | ✅ Full | Full support |
+| **Kitchen** | ✅ Full | Appliances as objects |
+| **Dining Room** | ✅ Full | Table + chairs pattern |
+| **Home Office** | ✅ Full | Desk + chair + shelf |
+| **Bathroom** | ⚠️ Partial | Mirrors, fixtures simplified |
+| **Hallway** | ⚠️ Partial | Limited furniture |
+| **Outdoor Patio** | ❌ Not supported | Future scope |
+| **Commercial Retail** | 📝 Planned | v2.0 |
+| **Restaurant / Cafe** | 📝 Planned | v2.0 |
+
+---
+
+## Backend Architecture
+
+### Service Topology
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        API Gateway                            │
+│              (Rate limiting, Auth, SSL, CDN)                  │
+└─────────────────────────────────────────────────────────────┘
+                             │
+        ┌────────────────────┼────────────────────┐
+        │                    │                    │
+┌───────▼──────┐    ┌────────▼────────┐   ┌────▼─────┐
+│  REST API    │    │  WebSocket API   │   │ Webhook  │
+│  (FastAPI)   │    │  (Real-time      │   │ (Export  │
+│              │    │   progress)      │   │  notify) │
+└───────┬──────┘    └────────┬────────┘   └────┬─────┘
+        │                    │                  │
+┌───────▼────────────────────▼──────────────────▼─────────────┐
+│                     Task Queue (Redis/RabbitMQ)             │
+│              Priority: free < premium < enterprise            │
+└───────┬───────────────────────────────────────┬─────────────┘
+        │                                       │
+┌───────▼────────┐                    ┌────────▼────────┐
+│  GPU Workers   │                    │  CPU Workers    │
+│  (Ray/K8s)     │                    │  (Pre/Post proc) │
+│                │                    │                 │
+│  - Generation  │                    │  - Segmentation │
+│  - Rendering   │                    │  - Mesh cleanup │
+│  - Export      │                    │  - Format conv  │
+└────────────────┘                    └─────────────────┘
+```
+
+### GPU Orchestration (Ray + Kubernetes)
+
+```yaml
+# k8s/interiorfusion-gpu-worker.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: interiorfusion-gpu-worker
+spec:
+  replicas: 5
+  selector:
+    matchLabels:
+      app: interiorfusion-gpu
+  template:
+    spec:
+      containers:
+      - name: worker
+        image: stevee00/interiorfusion:latest
+        resources:
+          limits:
+            nvidia.com/gpu: 1
+            memory: "32Gi"
+            cpu: "8"
+        env:
+        - name: MODEL_SIZE
+          value: "L"
+        - name: BATCH_SIZE
+          value: "1"
+```
+
+### Queueing Strategy
+
+| Tier | Max Queue Time | Priority | GPU Allocation |
+|------|---------------|----------|---------------|
+| **Free** | 5 minutes | Low | Shared A10G |
+| **Pro** ($20/mo) | 30 seconds | Medium | Dedicated A10G |
+| **Enterprise** | 5 seconds | High | Dedicated A100 |
+| **Batch API** | 1 hour | Lowest | Spot instances |
+
+### Caching Strategy
+
+| Cache Layer | TTL | Size | Purpose |
+|-------------|-----|------|---------|
+| **CDN Edge** | 24h | Infinite | Generated GLB/PLY files |
+| **Redis Hot** | 1h | 10GB | Depth maps, segmentation |
+| **Redis Warm** | 24h | 50GB | Scene graphs, metadata |
+| **GPU VRAM** | 5m | Per-GPU | Model weights, active scenes |
+| **Disk Cache** | 7d | 1TB | Model checkpoints, datasets |
+
+### Vector Database (ChromaDB / Pinecone)
+
+Store:
+- Furniture embeddings for similarity search
+- Room style embeddings for style matching
+- User preference history for personalization
+
+Schema:
+```python
+{
+    "id": "furniture_12345",
+    "embedding": [768-dim vector],
+    "metadata": {
+        "type": "sofa",
+        "style": "scandinavian",
+        "dimensions": [2.0, 0.9, 0.8],
+        "material": "fabric",
+        "color": "gray",
+        "source": "ikea_catalog",
+    }
+}
+```
+
+---
+
+## Inference Service Architecture
+
+### Model Registry (HF Hub)
+
+```python
+# Model versions managed via HF Hub
+MODEL_REGISTRY = {
+    "InteriorFusion-S": {
+        "repo": "stevee00/InteriorFusion-S",
+        "size": "1.5B",
+        "speed": "5s",
+        "quality": "preview",
+    },
+    "InteriorFusion-L": {
+        "repo": "stevee00/InteriorFusion-L",
+        "size": "4B",
+        "speed": "15s",
+        "quality": "production",
+    },
+    "InteriorFusion-XL": {
+        "repo": "stevee00/InteriorFusion-XL",
+        "size": "10B",
+        "speed": "30s",
+        "quality": "research",
+    },
+}
+```
+
+### Auto-scaling Rules
+
+| Metric | Threshold | Action |
+|--------|-----------|--------|
+| Queue depth | > 10 tasks | Scale up GPU workers +2 |
+| Queue depth | < 2 tasks | Scale down GPU workers -1 |
+| Avg inference time | > 20s (L model) | Switch to S model for free tier |
+| GPU memory | > 90% | Clear LRU cache |
+| Error rate | > 5% | Alert + fallback to S model |
+| Cost/hour | > $100 | Enable spot instance preference |
+
+---
+
+## Rendering Pipeline
+
+### Real-time Preview (Gaussian Splatting)
+
+For the interactive 3D viewer:
+- Scene loaded as Gaussian splatting PLY
+- Web-based viewer using Three.js + GaussianSplatting
+- FPS target: 60fps on RTX 3060, 30fps on integrated GPU
+- Level-of-Detail: Reduce Gaussian count for distant objects
+
+### Production Quality (Path Tracing)
+
+For final export / marketing renders:
+- Export to Blender / UE5 / Unity
+- Use native path tracing (Cycles, Lumen, HDRP)
+- Bake lighting into lightmaps for static scenes
+- Real-time GI for dynamic objects
+
+### Web Viewer Architecture
+
+```html
+<!-- Simplified web viewer -->
+<interiorfusion-viewer
+  scene-url="https://cdn.interiorfusion.ai/scenes/abc123/scene.ply"
+  editable="true"
+  ar-support="true"
+  vr-support="false"
+>
+</interiorfusion-viewer>
+```
+
+Features:
+- Orbit controls (rotate, zoom, pan)
+- Object selection (click to select furniture)
+- Property panel (position, rotation, scale, material)
+- Material picker (swatches from PBR library)
+- Lighting control (time of day, intensity)
+- AR mode (place in real room via WebXR)
+
+---
+
+## Asset Management
+
+### Furniture Catalog
+
+| Source | Items | License | Integration |
+|--------|-------|---------|------------|
+| **IKEA API** | ~10,000 | Commercial | Direct purchase links |
+| **Wayfair API** | ~100,000 | Commercial | Affiliate links |
+| **3D-FUTURE** | ~10,000 | Research | Training + reference |
+| **Objaverse** | ~10M | Mixed | Generic placeholders |
+| **Custom Models** | User uploads | User-owned | Premium feature |
+
+### Material Library
+
+| Category | Count | Source |
+|----------|-------|--------|
+| **Wood** | 500 | CC0 Textures, Poliigon |
+| **Fabric / Upholstery** | 300 | Custom scans |
+| **Tile / Stone** | 200 | CC0 Textures |
+| **Paint** | 1000 | Sherwin-Williams, Benjamin Moore |
+| **Wallpaper** | 500 | Spoonflower, Wallcoverings |
+| **Metal** | 150 | CC0 Textures |
+| **Glass** | 50 | Custom |
+
+---
+
+## Business Model
+
+### Pricing Tiers
+
+| Tier | Price | Generations/mo | Quality | Export | API | Support |
+|------|-------|---------------|---------|--------|-----|---------|
+| **Free** | $0 | 5 | S model | GLB only | ❌ | Community |
+| **Pro** | $20/mo | 100 | L model | All formats | ✅ 100/day | Email |
+| **Studio** | $99/mo | 500 | XL model | All + batch | ✅ 1000/day | Priority |
+| **Enterprise** | Custom | Unlimited | XL + custom | All + white-label | ✅ Unlimited | Dedicated |
+
+### Revenue Streams
+
+1. **Subscription**: Monthly plans (primary revenue)
+2. **API Usage**: Per-generation pricing for integrations
+3. **Furniture Affiliates**: Commission on furniture purchases
+4. **Professional Services**: Custom training, fine-tuning
+5. **White-label**: Licensed SDK for furniture retailers
+6. **Data**: Anonymized trend reports (industry insights)
+
+---
+
+## Moat & Competitive Advantage
+
+### Technical Moat
+
+1. **Interior-specific architecture**: No competitor has scene-aware 3D generation
+2. **Proprietary dataset**: Curated 85K interior rooms, multi-modal
+3. **Training cost barrier**: $65K to replicate, 4 weeks on 32×A100
+4. **Integration depth**: Blender/UE/Unity/ComfyUI plugins (network effects)
+
+### Data Moat
+
+1. **User-generated scenes**: Every generation improves dataset
+2. **Feedback loop**: User edits provide preference signals
+3. **Style trends**: Real-time interior design trend detection
+4. **Furniture catalog**: Deep embedding of commercial products
+
+### Network Effects
+
+1. **Community models**: Users fine-tune and share LoRAs
+2. **Template library**: Popular room designs become templates
+3. **Plugin ecosystem**: Third-party tools extend capabilities
+
+---
+
+## Roadmap
+
+### Q3 2026 (Launch)
+- ✅ Single photo → 3D scene
+- ✅ GLB/PLY export
+- ✅ Gradio web app
+- ✅ Blender plugin
+- ✅ Basic editing (move, remove, replace)
+
+### Q4 2026 (Growth)
+- 📝 FastAPI backend + API
+- 📝 Mobile app (iOS/Android)
+- 📝 AR preview (ARKit / ARCore)
+- 📝 Furniture recommendations
+- 📝 Style transfer
+- 📝 Material swap UI
+
+### Q1 2027 (Scale)
+- 📝 ComfyUI nodes
+- 📝 Unreal Engine / Unity plugins
+- 📝 Batch generation API
+- 📝 Enterprise white-label
+- 📝 Video-to-3D extension
+
+### Q2 2027 (Maturity)
+- 📝 Multi-room generation
+- 📝 Floor plan import
+- 📝 Lighting design
+- 📝 HVAC/ electrical visualization
+- 📝 Construction document generation