📝 docs: add comprehensive project documentation with TOGAF EA principles

CLAUDE.md

@@ -6,6 +6,93 @@ This document defines the expectations, standards, and development practices for
 
 **Luminous** is a digital family command center designed for large, portrait-mounted touchscreens. It provides a calm, glanceable view of household schedules, tasks, and reminders.
 
+For comprehensive project documentation, see:
+- [Project Overview](./docs/PROJECT-OVERVIEW.md) - Complete product specification
+- [Architecture](./docs/ARCHITECTURE.md) - Technical architecture documentation
+- [Roadmap](./docs/ROADMAP.md) - Development phases and milestones
+- [Architecture Decision Records](./docs/adr/) - Key design decisions
+
+---
+
+## TOGAF Enterprise Architecture Principles
+
+Luminous follows TOGAF (The Open Group Architecture Framework) principles for enterprise architecture. All architectural decisions must align with these principles.
+
+### Architecture Development Method (ADM)
+
+We follow TOGAF ADM phases in our development process:
+
+| Phase | Description | Luminous Application |
+|-------|-------------|---------------------|
+| **Preliminary** | Framework and principles | Establish guidelines (this document) |
+| **A: Vision** | Architecture vision | Project overview and goals |
+| **B: Business** | Business architecture | Feature capabilities and processes |
+| **C: Information** | Data architecture | Domain models and data flows |
+| **C: Application** | Application architecture | Component design and boundaries |
+| **D: Technology** | Technology architecture | Technology stack decisions |
+| **E: Opportunities** | Solutions and migration | Roadmap phases |
+| **F: Migration** | Planning | Phase transitions |
+| **G: Governance** | Implementation governance | Code reviews, ADRs |
+| **H: Change** | Architecture change | Version updates, migrations |
+
+### Core Architecture Principles
+
+#### Business Principles
+
+| ID | Principle | Description |
+|----|-----------|-------------|
+| BP-1 | **Family-Centric Design** | All features must serve real family coordination needs |
+| BP-2 | **Zero Distraction** | The product differentiates by what it omits |
+| BP-3 | **Inclusive by Default** | Design for all ages and abilities |
+| BP-4 | **Privacy as a Feature** | Users own and control their data |
+
+#### Data Principles
+
+| ID | Principle | Description |
+|----|-----------|-------------|
+| DP-1 | **Cloud-First with Local Cache** | Primary data in Azure; local caching for offline support |
+| DP-2 | **User Data Ownership** | Users can export their data; multi-tenant isolation guaranteed |
+| DP-3 | **Single Source of Truth** | CosmosDB as source; partition isolation per family |
+| DP-4 | **Data Minimization** | Collect only what's necessary |
+
+#### Application Principles
+
+| ID | Principle | Description |
+|----|-----------|-------------|
+| AP-1 | **Modular Composability** | Features evolve independently |
+| AP-2 | **Cross-Platform Consistency** | Unified experience across platforms |
+| AP-3 | **Graceful Degradation** | Partial failures shouldn't block usage |
+| AP-4 | **Performance on Constraints** | Optimize for modest hardware |
+
+#### Technology Principles
+
+| ID | Principle | Description |
+|----|-----------|-------------|
+| TP-1 | **Azure-Native Stack** | Leverage Azure PaaS services; .NET/Angular/native mobile |
+| TP-2 | **Commodity Hardware** | ARM and x86 support for displays; any device for mobile |
+| TP-3 | **Standards-Based Integration** | OAuth 2.0/OIDC, REST APIs, OpenAPI contracts |
+| TP-4 | **Infrastructure as Code** | Bicep with AVMs for reproducible deployments |
+
+### Architecture Governance
+
+1. **All significant decisions require an ADR**
+   - New technology choices
+   - Architectural pattern changes
+   - Integration approaches
+   - Data model changes
+
+2. **ADRs must follow the template** in `/docs/adr/ADR-000-template.md`
+
+3. **Review process**
+   - ADRs proposed via pull request
+   - Minimum one reviewer approval
+   - Discussion period before acceptance
+
+4. **Principle compliance checks** in code reviews:
+   - Does this change align with architecture principles?
+   - Does it follow the bounded context boundaries?
+   - Is it appropriately documented?
+
 ---
 
 ## Core Development Principles
@@ -55,24 +142,56 @@ All code must be:
 #### Directory Structure Expectations
 
 ```
+# .NET Backend (Clean Architecture)
 src/
-├── components/       # Reusable UI components
-├── features/         # Feature-based modules (vertical slices)
-├── domain/           # Domain models and business logic
-├── services/         # External service integrations
-├── hooks/            # Shared React hooks (if applicable)
-├── utils/            # Pure utility functions
-├── types/            # TypeScript type definitions
-└── config/           # Configuration and constants
+├── Luminous.Domain/           # Domain entities, value objects, interfaces
+├── Luminous.Application/      # Use cases, DTOs, application services
+├── Luminous.Infrastructure/   # Data access, external services, Azure integrations
+├── Luminous.Api/              # ASP.NET Core Web API, controllers
+└── Luminous.Functions/        # Azure Functions for background processing
+
+# Angular Web/Display Applications
+clients/
+├── web/                       # Main web application
+│   ├── src/app/
+│   │   ├── core/              # Singleton services, guards, interceptors
+│   │   ├── shared/            # Shared components, pipes, directives
+│   │   ├── features/          # Feature modules (lazy-loaded)
+│   │   └── models/            # TypeScript interfaces and types
+├── display/                   # Electron display application
+└── shared/                    # Shared Angular libraries
+
+# Native Mobile Applications
+mobile/
+├── ios/                       # Swift/SwiftUI iOS app
+└── android/                   # Kotlin/Compose Android app
+
+# Infrastructure as Code
+infra/
+├── modules/                   # Bicep modules wrapping AVMs
+├── environments/              # Parameter files per environment
+└── main.bicep                 # Main orchestration
 ```
 
 #### Component Guidelines
 
-- One component per file
-- Co-locate component tests, styles, and stories
-- Props should be typed and documented
-- Avoid prop drilling; use context or state management appropriately
-- Components should be presentational or container, not both
+**Angular (Web/Display)**
+- One component per file with co-located template and styles
+- Use standalone components (Angular 19+)
+- Inputs/Outputs should be typed and documented
+- Use services for state management, avoid deep component hierarchies
+- Components should be presentational or smart, not both
+
+**Native Mobile**
+- iOS: Follow SwiftUI patterns with ObservableObject for state
+- Android: Use Compose with ViewModel and StateFlow
+- Share API models via OpenAPI-generated clients
+
+**.NET Backend**
+- Follow Clean Architecture layer separation
+- Use MediatR for CQRS pattern
+- Repository pattern for data access
+- Domain entities should be persistence-ignorant
 
 ---
 
@@ -147,16 +266,39 @@ All commits MUST follow the format:
 
 Use scopes to indicate the affected area:
 
+**Features**
 - `calendar` - Calendar-related changes
 - `tasks` - Task/chore management
+- `routines` - Routine management
+- `rewards` - Rewards and gamification
+- `meals` - Meal planning and recipes
+- `lists` - List management
+- `profiles` - Profile and household management
 - `notes` - Notes and reminders
+- `import` - Magic import feature
+- `sync` - Real-time synchronization (SignalR)
+- `linking` - Device linking flow
+
+**Applications**
+- `api` - .NET API backend
+- `functions` - Azure Functions
+- `web` - Angular web application
+- `display` - Angular/Electron display application
+- `ios` - iOS native application
+- `android` - Android native application
+
+**Infrastructure**
 - `ui` - General UI components
-- `display` - Display/kiosk mode
-- `config` - Configuration
-- `api` - API/backend changes
-- `auth` - Authentication
-- `db` - Database changes
-- `infra` - Infrastructure
+- `auth` - Authentication (Passkeys/WebAuthn/OAuth)
+- `cosmos` - CosmosDB/data layer changes
+- `storage` - Blob storage changes
+- `infra` - Bicep/IaC infrastructure
+- `config` - Configuration and settings
+
+**Meta**
+- `docs` - Documentation
+- `adr` - Architecture Decision Records
+- `ci` - CI/CD pipeline changes
 
 ### Commit Examples
 
@@ -243,32 +385,91 @@ Luminous must be usable by all household members:
 
 ## Build & Development Commands
 
+### Local Development Setup
+
+```bash
+# Start local Azure emulators (CosmosDB, Storage, Redis)
+docker-compose up -d
+
+# .NET API
+cd src/Luminous.Api
+dotnet restore
+dotnet run
+
+# Angular Web App
+cd clients/web
+npm install
+npm start
+
+# Angular Display App (Electron)
+cd clients/display
+npm install
+npm run electron:dev
+```
+
+### .NET Backend Commands
+
+```bash
+# Build solution
+dotnet build
+
+# Run tests
+dotnet test
+
+# Run API with hot reload
+dotnet watch run --project src/Luminous.Api
+
+# Run Azure Functions locally
+func start --csharp
+```
+
+### Angular Frontend Commands
+
 ```bash
 # Install dependencies
 npm install
 
-# Run development server
-npm run dev
+# Development server
+npm start
 
 # Run tests
 npm test
 
-# Run tests in watch mode
-npm run test:watch
-
 # Build for production
 npm run build
 
 # Lint code
 npm run lint
 
-# Format code
-npm run format
-
 # Type check
 npm run typecheck
 ```
 
+### Infrastructure Commands
+
+```bash
+# Validate Bicep
+az bicep build --file infra/main.bicep
+
+# Deploy to Azure (dev environment)
+./infra/scripts/deploy.sh dev
+
+# Deploy to Azure (prod environment)
+./infra/scripts/deploy.sh prod
+```
+
+### Mobile Development
+
+```bash
+# iOS (requires macOS with Xcode)
+cd mobile/ios
+xcodebuild -scheme Luminous -sdk iphonesimulator
+
+# Android
+cd mobile/android
+./gradlew assembleDebug
+```
+
 ---
 
 ## Getting Help