📝 docs: add comprehensive project documentation with TOGAF EA principles #2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Create docs/PROJECT-OVERVIEW.md with complete product specification - Executive summary and vision statement - Stakeholder personas and role matrix - Core UX principles (glanceable, zero-distraction, etc.) - Comprehensive functional scope (10 feature areas) - Non-functional requirements (reliability, performance, security) - Create docs/ARCHITECTURE.md with TOGAF-compliant architecture - Architecture principles (business, data, application, technology) - Business capability model and process maps - Data architecture with domain models and storage strategy - Application architecture with bounded contexts - Technology reference model and platform matrix - Security and integration architecture - Deployment architecture for self-hosting - Create docs/ROADMAP.md with phased implementation plan - Six development phases from Foundation to Ecosystem - Detailed scope items per phase with checklists - Dependency map and critical path - Risk register for technical and product risks - Create 7 Architecture Decision Records (ADRs): - ADR-001: TypeScript as Primary Language - ADR-002: React as UI Framework - ADR-003: Local-First Data Architecture - ADR-004: Two-Way Sync Initially Google-Only - ADR-005: Magic Import Requires Approval - ADR-006: Zero-Distraction Design Principle - ADR-007: Self-Hosting as Primary Model - Update CLAUDE.md with TOGAF EA principles and governance - Add links to new documentation - Add Architecture Development Method (ADM) phases - Add core architecture principles (BP, DP, AP, TP) - Add architecture governance process - Expand scopes for new functional areas
Major architectural pivot from local-first TypeScript/React to Azure-hosted multi-tenant SaaS platform: - Backend: C#/.NET 10 with Clean Architecture - Web/Display: TypeScript/Angular 19+ with Electron - Mobile: Native iOS (Swift/SwiftUI) and Android (Kotlin/Compose) - Cloud: Azure PaaS services (CosmosDB, Functions, App Service, B2C) - IaC: Bicep with Azure Verified Modules (AVMs) Updated documentation: - ARCHITECTURE.md: Complete Azure architecture with data models - PROJECT-OVERVIEW.md: Multi-tenant deployment model and device linking - ROADMAP.md: 6-phase implementation plan for new stack - CLAUDE.md: Updated principles and development commands New ADRs (ADR-001 through ADR-010): - .NET 10 backend, Angular web framework, Azure cloud platform - Native mobile apps, CosmosDB data store, multi-tenant architecture - Bicep/AVMs for IaC, Magic Import approval, Zero-distraction principle - Azure AD B2C for identity Removed superseded ADRs (TypeScript, React, local-first, self-hosting)
…tion Replace external identity provider with in-house passwordless-first authentication system supporting: - Passkeys (WebAuthn/FIDO2) as primary method - Hardware security keys (YubiKey, etc.) - Email OTP / Magic links for passwordless - Social sign-on (Google, Apple, Microsoft) - Email/password with MFA as fallback Updated documentation: - ADR-010: Complete rewrite for passwordless architecture - ARCHITECTURE.md: Updated security diagrams and requirements - ROADMAP.md: Updated auth tasks for passkey integration - CLAUDE.md: Updated auth scope description Key benefits: - Phishing-resistant authentication - Better UX with biometrics - No per-authentication costs - Full control over auth flows
trickpatty
approved these changes
Dec 21, 2025
trickpatty
added a commit
that referenced
this pull request
Dec 24, 2025
trickpatty
added a commit
that referenced
this pull request
Dec 24, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Create docs/PROJECT-OVERVIEW.md with complete product specification
Create docs/ARCHITECTURE.md with TOGAF-compliant architecture
Create docs/ROADMAP.md with phased implementation plan
Create 7 Architecture Decision Records (ADRs):
Update CLAUDE.md with TOGAF EA principles and governance