docs/PRODUCT_ARCHITECTURE.md

# 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