Case Study: E-Map Floor Plan Management
This case study demonstrates the specification framework through a complete feature example: adding floor plan management (E-Map) capability to a video surveillance platform.
High-Level Specification (Proposal)
The proposal captures business intent, scope, and impact assessment.
markdown
# Change Proposal: E-Map Floor Plan Management
## Why
Organizations managing surveillance deployments across multi-floor buildings
need visual context to understand device placement and quickly access cameras
based on physical location. Current system provides logical organization
(groups/sites) but lacks visual floor plan mapping.
## What Changes
- Floor plan upload and storage (PNG, JPG, SVG)
- Device placement on floor plans with drag-and-drop
- Multiple floor plans per group (multi-floor buildings)
- Zone/area definition with custom labels
- Click-to-view functionality (device icon → live video)
- Role-based access control (Admin edit, others view-only)
- GraphQL API for floor plan operations
## Impact
### Affected Specs
- NEW: spatial-context/emap-management
- MODIFIED: authorization/rbac-permissions (add floor plan permissions)
- MODIFIED: device-management/metadata (add position attributes)
### Breaking Changes
- None (additive feature)
### Migration
- No data migration required
- Feature flag for gradual rolloutKey Characteristics:
- Answers "why" before "what"
- Identifies affected specifications explicitly
- Assesses breaking changes and migration needs
Design Document
The design document captures architectural decisions with rationale and trade-offs.
markdown
# Design Document: E-Map Floor Plan Management
## Decisions
### Decision 1: Percentage-Based Positioning
**Choice:** Store device positions as percentage coordinates (0-100%)
rather than absolute pixel coordinates.
**Rationale:**
- Floor plans displayed at different resolutions across devices
- Percentage-based positioning scales naturally with image resizing
- Simplifies rendering logic across web and mobile
**Alternatives Considered:**
- Pixel-based: Would require recalculating positions on resize
- Grid-based: Would limit precision
**Trade-offs:**
- Minor rounding errors at extreme zoom (acceptable)
### Decision 2: Embedded Device Positions
**Choice:** Store DevicePositions as JSON within FloorPlan record,
not separate table.
**Rationale:**
- Typical floor plans have 5-50 devices (fits single record)
- Single-item operations reduce database costs
- Simplified queries (no joins)
**Trade-offs:**
- Record size limit (~200 devices per floor plan)
- Acceptable for use case; can migrate if needed
### Decision 3: Image Storage Strategy
**Choice:** Object storage with presigned URLs (1-hour expiry).
**Rationale:**
- Cost-effective for binary storage
- Secure temporary access without backend proxy
- Scales to millions of images
## Risks
### Risk 1: Large Images
Users may upload oversized floor plans causing slow loads.
**Mitigation:**
- 10MB file size limit
- Server-side compression (max 4000x4000)
- Thumbnails in list viewKey Characteristics:
- Each decision follows Choice → Rationale → Alternatives → Trade-offs
- Risks identified with mitigations
- Technical depth without implementation details
Domain Specification
Domain specifications define requirements using scenario-based format.
markdown
# Spatial Context: E-Map Management
## Requirement: Floor Plan Upload
The system SHALL allow authorized users to upload floor plan images.
### Scenario: Upload valid floor plan image
- WHEN user uploads PNG, JPG, or SVG file
- AND file size is less than 10MB
- AND dimensions between 500x500 and 8000x8000 pixels
- THEN system SHALL store image in object storage
- AND create FloorPlan record with metadata
- AND return FloorPlanID and image URL
### Scenario: Reject oversized image
- WHEN user uploads image exceeding 10MB
- THEN system SHALL reject with error "FILE_TOO_LARGE"
- AND display "Floor plan image must be smaller than 10MB"
## Requirement: Device Placement
The system SHALL allow positioning devices on floor plans.
### Scenario: Place device on floor plan
- WHEN user drags device icon to position on floor plan
- THEN system SHALL store position as (x%, y%) coordinates
- AND position SHALL persist in FloorPlan.DevicePositions
- AND device icon SHALL appear at position when displayed
### Scenario: View device from floor plan
- WHEN user clicks device icon on floor plan
- THEN system SHALL display popover with device name and status
- AND provide "View Live" button to open video stream
## Requirement: Role-Based Access
### Scenario: Admin can edit floor plans
- WHEN user with Admin role accesses floor plan
- THEN system SHALL display editor controls
- AND allow modification operations
### Scenario: Viewer has read-only access
- WHEN user with Viewer role accesses floor plan
- THEN system SHALL display floor plan in read-only mode
- AND hide editing controls
- BUT allow clicking devices to view feeds (if permitted)Key Characteristics:
- WHEN/THEN scenario format (machine-parseable)
- SHALL/SHOULD/MAY requirement levels
- Grouped by capability area
Implementation Tasks
Tasks derived from specifications, organized by domain.
markdown
# Implementation Tasks: E-Map Floor Plan Management
## 1. Backend Foundation
- [ ] 1.1 Define database schema for FloorPlan entity
- [ ] 1.2 Create domain model (FloorPlan, DevicePosition, Zone)
- [ ] 1.3 Implement repository interface and storage adapter
- [ ] 1.4 Add unit tests (target: 70% coverage)
## 2. API Layer
- [ ] 2.1 Define GraphQL schema (types, queries, mutations)
- [ ] 2.2 Implement resolvers with authorization checks
- [ ] 2.3 Add integration tests for API endpoints
## 3. Image Storage
- [ ] 3.1 Implement image upload with validation
- [ ] 3.2 Generate presigned URLs for retrieval
- [ ] 3.3 Configure lifecycle policy for cleanup
## 4. Authorization
- [ ] 4.1 Add floor plan permissions to policy
- [ ] 4.2 Implement group-based access checks
- [ ] 4.3 Add authorization unit tests
## 5. Frontend - List View
- [ ] 5.1 Create route and view component
- [ ] 5.2 Implement floor plan list with thumbnails
- [ ] 5.3 Add search/filter functionality
- [ ] 5.4 Connect to GraphQL queries
## 6. Frontend - Editor
- [ ] 6.1 Create canvas component with zoom/pan
- [ ] 6.2 Implement drag-and-drop device placement
- [ ] 6.3 Implement zone drawing tool
- [ ] 6.4 Add auto-save with debouncing
## 7. Testing
- [ ] 7.1 Unit tests for components and stores
- [ ] 7.2 E2E tests for critical flows
- [ ] 7.3 Authorization edge case tests
## 8. Documentation
- [ ] 8.1 API documentation
- [ ] 8.2 User guide sectionKey Characteristics:
- Numbered for reference and tracking
- Grouped by domain/component
- Derived directly from specifications
- Actionable and atomic
Specification Traceability
The E-Map feature demonstrates complete traceability:
Intent: "Organizations need visual floor plan mapping"
│
├── Proposal (proposal.md)
│ └── Identifies 3 affected specs
│
├── Design Document (design.md)
│ └── 7 architectural decisions with rationale
│
├── Domain Specs
│ ├── spatial-context/emap-management (NEW)
│ ├── authorization/rbac-permissions (MODIFIED)
│ └── device-management/metadata (MODIFIED)
│
└── Implementation Tasks (tasks.md)
└── 8 task groups, ~40 individual tasksEvery implementation task traces back through domain specs, design decisions, and high-level proposal to the original intent. This traceability enables:
- Impact Analysis: Change to requirement → identify affected tasks
- Audit Trail: Why was this code written? → trace to specification
- AI Context: Agent receives complete specification chain for implementation
Post-Deployment Insights
After Phase 0 deployment, the PM immediately requested deep feature development for Phase 0.5+. Key insights from this rapid expansion:
Insight 1: Specification Framework Enables Rapid Response
- PM structured complex expansion using established Why/What/How template
- AI generated comprehensive feature requirements within hours, not weeks
- Acceptance criteria quality matched senior engineer output
Insight 2: Knowledge Base Multiplies AI Effectiveness
- Competitor analysis (Verkada, Avigilon Alta) in AI-accessible format informed feature design
- Context engineering (structured prompts, domain knowledge) critical for quality output
Insight 3: Field Feedback Without Rationale Creates Gaps
- Sydney feedback validated MVP but lacked rationale for prioritization
- Without documented demand sources, difficult to justify scope decisions
Insight 4: E-Map as Platform Component
- Floorplan has potential to become core feature, replacing Site as primary navigation
- Development team lacks authority to modify Site specification
- Cross-team specification visibility would enable architectural evolution
Insight 5: Specification Gaps Discovered During Development
- Product spec lacked resource limits (e.g., max floorplans per site) - discovered during implementation
- No analytics/telemetry planning in original spec - tracking events are optional but valuable for product decisions
- Recommendation: Spec templates should include "Limits & Constraints" and "Telemetry Events" sections
Insight 6: Feature Requirements Without Business Rationale Create Design Blind Spots
- PM proposed adding real-time Alarm notifications to Floorplan/GlobalView during initial specification
- However, could not articulate why this feature was needed instead of educating users to handle events through the existing Alarm page
- Technical concerns: Relying solely on Web Frontend to capture events when the page is open is not a high-coverage strategy
- Events are missed when users don't have the page open
- Cannot guarantee real-time delivery and reliability
- Unclear responsibility separation from existing Alarm system
- Recommendation: Spec templates should include "Existing Alternative Analysis" section requiring justification for why current features cannot meet the need
References
- OpenSpec - Specification-driven development framework
- Claude Code Documentation - Official documentation for CLAUDE.md and AI guidance files
- Effective Context Engineering for AI Agents - Anthropic's guide to context engineering