EPIC-16: Floor Plans & Utility Tracking (2.5D)

[steilerDev]

Epic: Floor Plans & Utility Tracking (2.5D)

Epic ID: EPIC-16
Priority: Should Have
Description: A 2.5D floor plan system that lets homeowners draw walls, place doors/windows, define surface layers (insulation, cladding, finishes), and route utilities (electrical, plumbing, HVAC, data) through those layers. The system provides a hierarchical drill-down from lot to building to floor to wall cross-section to individual material layer, with utility routing at the layer level.

Use Case

Standalone documentation tool for recording the physical layout and construction composition of a building. Primary use case: documenting an existing old house with irregular geometry (no right angles, no accurate architectural drawings available). The goal is capturing what's inside each wall/ceiling/floor — materials, layers, utility routes — with photo evidence per layer. This is a standalone feature with no integration to work items or budget.

Architectural Decisions

ADR	Title	Summary
ADR-020	Konva.js for 2D Canvas Rendering	Pure-JS canvas library (no native binaries), React bindings via react-konva, server-side coordinate storage
ADR-021	Polymorphic Surface Layers	Single surface_layers table with parent_type + parent_id columns to attach layers to walls, ceilings, or floor surfaces
ADR-022	JSON Path Segments for Utility Routing	path_data column stores array of path segments (`{type: "M"
ADR-023	View Hierarchy & Navigation Model	Lot → Building → Floor → Wall/Ceiling/Floor Surface → Layer drill-down with breadcrumb navigation

View Hierarchy

Lot View (/plans)
  └─ Building Detail (/plans/buildings/:buildingId)
       └─ Floor Plan (/plans/floors/:floorId)
            ├─ Wall Cross-Section (/plans/floors/:floorId/wall/:wallId)
            │    └─ Layer Detail (/plans/layers/:layerId)
            ├─ Ceiling Surface (/plans/floors/:floorId/ceiling)
            │    └─ Layer Detail (/plans/layers/:layerId)
            └─ Floor Surface (/plans/floors/:floorId/floor-surface)
                 └─ Layer Detail (/plans/layers/:layerId)

Phases & Stories

Phase 1: Foundation (7 stories)

• FP-1: Schema & Migration #753 — FP-1: Schema & Migration
• FP-2: Material & Utility Type Catalogs #754 — FP-2: Material & Utility Type Catalogs
• FP-3: Lots & Buildings CRUD #755 — FP-3: Lots & Buildings CRUD
• FP-4: Floors CRUD & Building Detail #756 — FP-4: Floors CRUD & Building Detail
• FP-5: Lot View Canvas #757 — FP-5: Lot View Canvas
• FP-23: Undo/Redo for Canvas Operations #926 — FP-23: Undo/Redo for Canvas Operations (new — spec review)
• FP-24: Scale/Measurement System #927 — FP-24: Scale/Measurement System (new — spec review)

Phase 2: Floor Plan Core (4 stories)

• FP-6: Floor Plan Canvas (Read-Only) #758 — FP-6: Floor Plan Canvas (Read-Only)
• FP-7: Wall Drawing Interaction (with Precise Dimension Input) #759 — FP-7: Wall Drawing Interaction
• FP-8: Rooms CRUD & Labels #760 — FP-8: Rooms CRUD & Labels
• FP-9: Doors & Windows #761 — FP-9: Doors & Windows

Phase 3: Layers & Cross-Sections (4 stories)

• FP-10: Surface Layers Backend #762 — FP-10: Surface Layers Backend
• FP-11: Wall Cross-Section View #763 — FP-11: Wall Cross-Section View
• FP-12: Ceiling & Floor Surface Layers #764 — FP-12: Ceiling & Floor Surface Layers
• FP-25: Layer Photo Documentation #928 — FP-25: Layer Photo Documentation (new — spec review)

Phase 4: Utilities (5 stories)

• FP-13: Utility Lines Backend #765 — FP-13: Utility Lines Backend
• FP-14: Layer Detail View (Read-Only) #766 — FP-14: Layer Detail View (Read-Only)
• FP-15: Utility Drawing Interaction #767 — FP-15: Utility Drawing Interaction
• FP-16: Utility Terminals #768 — FP-16: Utility Terminals
• FP-17: Connection Guides #770 — FP-17: Connection Guides

Phase 5: Multi-Floor & Special Structures (3 stories)

• FP-18: Cross-Floor Connections #771 — FP-18: Cross-Floor Connections
• FP-19: Stairs #772 — FP-19: Stairs
• FP-20: Ceiling Shapes (Vaults, Slopes, Polygons) #773 — FP-20: Ceiling Shapes (Vaults, Slopes, Polygons)

Phase 6: Polish (2 stories)

• FP-21: Utility Overlay on Floor Plan #774 — FP-21: Utility Overlay on Floor Plan
• FP-22: Responsive View-Only, Dark Mode & Print #775 — FP-22: Responsive View-Only, Dark Mode & Print

New Dependencies

• konva — 2D canvas rendering library (pure JS, no native binaries)
• react-konva — React bindings for Konva

Migration

• 0026_floor_plans.sql — 16 new tables: lots, lot_utility_intakes, buildings, floors, rooms, walls, wall_openings, wall_materials, surface_layers, utility_types, utility_lines, utility_terminals, connection_guides, cross_floor_connections, stairs, ceiling_shapes

Deferred Items (Out of Scope)

• Work item / room / wall integration (future epic)
• DXF/SVG export of floor plans (future epic)
• DXF/IFC import from CAD software (future epic)

Dependencies

• EPIC-02 (App Shell) — navigation, routing
• EPIC-01 (Auth) — authentication

Goals

• Enable homeowners to document their building's physical layout
• Track wall construction details (materials, insulation, finishes) layer by layer
• Route and document utility installations through wall/ceiling/floor layers
• Capture photo evidence per surface layer
• Provide a visual, interactive editing experience on desktop with support for irregular geometry (free-form angles, precise dimension input)
• Ensure mobile users can view (but not edit) floor plans

Spec Review Changes Applied

Changes from spec review (see spec review document for full rationale):

1. Migration number corrected from 0019 to 0026
2. Table count corrected from 14 to 16
3. Removed "extends Section 2.3/2.4/3.4" framing — this is a standalone documentation feature
4. Added FP-23 (Undo/Redo), FP-24 (Scale/Measurement), FP-25 (Layer Photos) as new stories
5. Photo attachments moved from "Deferred" to in-scope (FP-25)
6. FP-7 updated for old-house use case (free-form angles, dimension text input)
7. FP-22 scope reduced: stripped ARIA/accessibility ACs, kept responsive+dark mode+print only