whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-05-platform-requirements/lesson-02-defining-platform-requirements.md

@@ -0,0 +1,416 @@
+# Module 05: Platform Requirements
+
+## Lesson 2: Defining Platform Requirements
+
+**How to document the boundaries that shape your design**
+
+---
+
+## The Five Sections
+
+Every platform requirements document covers five areas:
+
+1. **Platforms** — Where the product lives
+2. **Integrations** — What systems connect
+3. **Constraints** — What's impossible or expensive
+4. **Complexity & Challenges** — Where difficulty exists
+5. **Knowledge Gaps** — What we don't know yet
+
+Let's walk through each one.
+
+---
+
+## Section 1: Platforms
+
+**The fundamental question: Where will this product exist?**
+
+### What to capture:
+
+- **Web** — Desktop browsers, mobile browsers, or both?
+- **Mobile Native** — iOS, Android, or both?
+- **Desktop Applications** — Windows, macOS, Linux?
+- **Other** — Smart TV, kiosk, wearable, embedded?
+
+### Why it matters for design:
+
+| Platform | Design Implications |
+|----------|-------------------|
+| Web only | No native gestures, browser limitations |
+| Mobile native | Touch-first, offline expectations |
+| Desktop app | Keyboard shortcuts, multi-window |
+| Cross-platform | Responsive design, consistent experience |
+
+### Example (Dog Week):
+
+```
+Platforms:
+- Primary: Progressive Web App (PWA)
+- Mobile: iOS and Android via PWA
+- Desktop: Web browser (Chrome, Safari, Firefox, Edge)
+- Offline: Core features must work offline (PWA service worker)
+```
+
+### Questions to ask:
+
+- "What devices will users primarily use?"
+- "Do we need to work offline?"
+- "Are there browser or OS version requirements?"
+- "Is a native mobile app required, or will web work?"
+
+---
+
+## Section 2: Integrations
+
+**What systems must connect to your product?**
+
+### Categories:
+
+**Authentication:**
+- OAuth providers (Google, Apple, Microsoft)
+- Enterprise SSO (SAML, LDAP)
+- Existing user databases
+- Social login
+
+**Payments:**
+- Payment processors (Stripe, PayPal, Klarna)
+- Subscription management
+- Invoice systems
+- Currency handling
+
+**Third-Party APIs:**
+- Maps and location
+- Email and SMS
+- Analytics
+- Cloud storage
+
+**Internal Systems:**
+- Legacy databases
+- Existing applications
+- Corporate tools
+- Data warehouses
+
+### Example (Dog Week):
+
+```
+Integrations:
+
+Authentication:
+- Supabase Auth (primary)
+- Google OAuth (optional social login)
+- Email/password fallback
+
+Data:
+- Supabase PostgreSQL database
+- Supabase Storage for images
+
+Future Considerations:
+- Calendar sync (Google Calendar, Apple Calendar)
+- Veterinarian appointment APIs (Phase 2)
+```
+
+### Why it matters for design:
+
+Each integration shapes what's possible:
+
+- **OAuth available?** Design smooth single-click login
+- **Calendar sync?** Design around existing schedule patterns
+- **Legacy system?** Work within its data model constraints
+
+### Questions to ask:
+
+- "What does the user already use that we should connect to?"
+- "Are there existing systems this must integrate with?"
+- "What authentication does the organization already use?"
+- "What third-party services are already in place?"
+
+---
+
+## Section 3: Constraints
+
+**What's technically impossible, too expensive, or simply not available?**
+
+### Categories:
+
+**Technical Constraints:**
+- Hosting limitations (shared hosting, limited resources)
+- No real-time capability (polling only)
+- Limited API rate limits
+- Legacy system restrictions
+
+**Budget Constraints:**
+- No budget for native apps
+- Can't afford enterprise APIs
+- Limited cloud resources
+- No dedicated infrastructure
+
+**Team Expertise:**
+- No mobile development experience
+- No security expertise
+- Limited API experience
+- No DevOps capability
+
+**Timeline Constraints:**
+- Must launch in 3 months
+- Phased rollout required
+- Seasonal deadline (holiday launch)
+
+**Regulatory Constraints:**
+- GDPR compliance
+- HIPAA requirements
+- Financial regulations
+- Accessibility laws
+
+### Example (Dog Week):
+
+```
+Constraints:
+
+Technical:
+- PWA approach (no native iOS/Android budget)
+- Supabase free tier initially (limited concurrent connections)
+
+Budget:
+- Bootstrap phase (minimal external spending)
+- No paid third-party APIs initially
+
+Team:
+- Solo developer initially
+- No dedicated mobile expertise
+
+Regulatory:
+- GDPR compliance required (Swedish users)
+- Child data considerations (family members might include minors)
+
+Timeline:
+- MVP in 8 weeks
+- Full launch in 16 weeks
+```
+
+### Why it matters for design:
+
+Constraints directly shape solutions:
+
+| Constraint | Design Adaptation |
+|------------|------------------|
+| No real-time | Design with polling, show "last updated" |
+| Limited budget | Simpler interactions, fewer features |
+| No mobile dev | PWA instead of native app |
+| GDPR required | Clear consent flows, data controls |
+
+### Questions to ask:
+
+- "What's technically not possible right now?"
+- "What would be too expensive to build?"
+- "What skills does the team lack?"
+- "What regulatory requirements apply?"
+- "What's the timeline we're working with?"
+
+---
+
+## Section 4: Complexity & Challenges
+
+**Where will implementation be difficult?**
+
+This section surfaces risks before they become blockers.
+
+### What to document:
+
+**High Complexity Integrations:**
+- Legacy systems with poor documentation
+- APIs with rate limits or unreliable uptime
+- Systems requiring custom middleware
+
+**Unproven Technology:**
+- New frameworks the team hasn't used
+- Cutting-edge features with limited support
+- Platform features in beta
+
+**Challenging Requirements:**
+- Real-time sync across devices
+- Offline-first with conflict resolution
+- Complex data migrations
+
+### Example (Dog Week):
+
+```
+Complexity & Challenges:
+
+Medium Complexity:
+- Push notifications across platforms (PWA limitations on iOS)
+- Offline sync with conflict resolution for schedules
+
+Lower Complexity:
+- User authentication (Supabase handles this well)
+- Basic CRUD operations for tasks and events
+
+Challenges:
+- iOS PWA push notifications are limited
+- Calendar sync requires OAuth complexity
+- Image optimization for slow connections
+```
+
+### Rating scale:
+
+- **Low** — Well-understood, team has experience
+- **Medium** — Achievable but requires research
+- **High** — Significant unknowns, may need spikes
+- **Unknown** — Needs investigation before commitment
+
+### Questions to ask:
+
+- "How complex is this integration really?"
+- "Has the team done this before?"
+- "What's the challenge level?"
+- "Are there unknowns that need research?"
+
+---
+
+## Section 5: Knowledge Gaps
+
+**What don't we know yet?**
+
+This is the most important section. It surfaces what needs investigation.
+
+### What to document:
+
+**Technical Unknowns:**
+- "Can the legacy API handle our expected load?"
+- "Does the payment processor support our currency?"
+- "Will the OAuth provider work with our platform?"
+
+**Performance Unknowns:**
+- "How will the app perform on slow networks?"
+- "What happens with 10,000 concurrent users?"
+- "Can images load fast enough on mobile?"
+
+**Integration Unknowns:**
+- "Does the third-party API have the endpoints we need?"
+- "What's the data format of the legacy system?"
+- "Is real-time sync technically feasible?"
+
+### Example (Dog Week):
+
+```
+Knowledge Gaps:
+
+Needs Research:
+- PWA push notification behavior on iOS 17+
+- Supabase performance with complex RLS policies
+- Image CDN options within budget
+
+Needs Spike:
+- Offline sync conflict resolution patterns
+- Calendar integration OAuth flows
+
+Needs Team Decision:
+- React Native vs PWA long-term strategy
+- Self-hosted vs Supabase managed
+```
+
+### Why this matters:
+
+**Knowledge gaps become development tasks.**
+
+While you focus on design, the development agent can:
+- Research the unknowns
+- Spike the complex integrations
+- Test the assumptions
+- Report back with findings
+
+This is parallel work. Design doesn't stop while technical investigation happens.
+
+### Questions to ask:
+
+- "What do we not know yet?"
+- "What assumptions haven't been validated?"
+- "What needs a proof-of-concept?"
+- "What might surprise us later?"
+
+---
+
+## The Complete Document
+
+Here's what a finished platform-requirements.md looks like:
+
+```markdown
+# Platform Requirements
+
+## Platforms
+- Primary: Progressive Web App (PWA)
+- Mobile: iOS and Android via PWA
+- Desktop: Web browser (Chrome, Safari, Firefox, Edge)
+- Offline: Core features must work offline
+
+## Integrations
+- Authentication: Supabase Auth, Google OAuth optional
+- Database: Supabase PostgreSQL
+- Storage: Supabase Storage
+- Future: Calendar sync, veterinarian APIs
+
+## Constraints
+- Technical: PWA approach, Supabase free tier initially
+- Budget: Bootstrap phase, no paid APIs
+- Team: Solo developer, no dedicated mobile expertise
+- Regulatory: GDPR compliance, child data considerations
+- Timeline: MVP in 8 weeks
+
+## Complexity & Challenges
+- Medium: Push notifications, offline sync
+- Low: Authentication, basic CRUD
+- Challenges: iOS PWA limitations, OAuth complexity
+
+## Knowledge Gaps
+- Research: iOS 17+ PWA behavior, Supabase RLS performance
+- Spike: Offline sync patterns, calendar OAuth
+- Decision: React Native vs PWA long-term
+```
+
+---
+
+## Where It Lives
+
+`A-Product-Brief/platform-requirements.md`
+
+**Why with the Product Brief?**
+
+Because platform requirements are strategic context. They're not technical specifications — they're the boundaries that shape all design decisions.
+
+Just like the Product Brief, this document gets referenced throughout the project. When you're designing, you check it. When developers have questions, they check it. When scope discussions happen, everyone checks it.
+
+---
+
+## The Handoff
+
+Once this document exists:
+
+1. **Hand off to development** — Technical investigation begins
+2. **Reference in design** — Every decision respects these boundaries
+3. **Update as you learn** — New discoveries get documented
+
+**This is a living document.** As knowledge gaps get investigated, the document gets updated. As the project evolves, constraints may change. Keep it current.
+
+---
+
+## What You've Learned
+
+- The five sections of platform requirements
+- How to document each section effectively
+- Why constraints inform rather than limit design
+- How knowledge gaps become parallel development work
+- Where the document lives and how it's used
+
+---
+
+## What's Next
+
+In the tutorial, you'll create your own platform-requirements.md. Saga will guide you through each section, asking the right questions to surface your project's specific boundaries.
+
+---
+
+**[Continue to Tutorial: Create Platform Requirements →](tutorial-05.md)**
+
+---
+
+[← Back to Lesson 1](lesson-01-why-boundaries-matter.md) | [Back to Module Overview](module-05-platform-requirements-overview.md)
+
+*Part of Module 05: Platform Requirements*

package/docs/learn/module-05-platform-requirements/module-05-platform-requirements-overview.md

@@ -0,0 +1,186 @@
+# Module 05: Platform Requirements
+
+**Time: 30 min | Agent: Saga | Phase: Strategy**
+
+---
+
+## What You'll Learn
+
+How to define the technical boundaries that inform your design decisions before you start designing.
+
+---
+
+## Why This Matters
+
+Imagine designing a beautiful real-time collaboration feature... then learning the backend can't support WebSockets.
+
+Or specifying an offline-first mobile experience... when the client only has budget for a web app.
+
+**Knowing the tech stack is a necessity for UX work — not optional.**
+
+You can't design well in ignorance. The platform shapes the experience.
+
+---
+
+## Not Architecture — Boundaries
+
+You're not designing the database. You're not specifying API endpoints. That's development work.
+
+You're understanding what's possible so your designs are grounded in reality.
+
+---
+
+## What You'll Discover
+
+### 1. Platforms
+
+Where will this product live?
+
+- Web only?
+- Mobile (iOS, Android, both)?
+- Desktop application?
+- All of the above?
+
+Each platform has different capabilities and constraints.
+
+### 2. Integrations
+
+What systems must we connect to?
+
+- Authentication (OAuth, SSO, custom)?
+- Payment processing?
+- Third-party APIs?
+- Legacy systems?
+- External databases?
+
+### 3. Constraints
+
+What's technically impossible or expensive?
+
+- Hosting limitations?
+- Budget constraints?
+- Team expertise?
+- Timeline restrictions?
+- Regulatory requirements?
+
+### 4. Complexity & Challenges
+
+Investigate integrations from a strategic standpoint:
+
+- How complex is this integration really?
+- What's the challenge level?
+- Is this well-understood or experimental?
+- Are there unknowns that need research?
+
+### 5. Knowledge Gaps
+
+What do we **not** know yet?
+
+- Unproven technology?
+- Missing documentation?
+- No team expertise?
+- Needs a spike or proof-of-concept?
+
+**Surface these gaps explicitly.** They become development tasks to investigate in parallel.
+
+---
+
+## The Saga Method
+
+Saga helps you think through boundaries conversationally:
+
+> "What platforms are we targeting?"
+> "Are there any systems we need to integrate with?"
+> "What technical constraints should I know about?"
+> "Is there anything that feels risky or uncertain?"
+
+She'll probe deeper where needed, ensuring nothing gets missed.
+
+---
+
+## Output
+
+`A-Product-Brief/platform-requirements.md`
+
+This document lives with your Product Brief because it's part of the strategic foundation — not a technical specification.
+
+---
+
+## Handoff to Development
+
+Once platform requirements are documented, you can **hand them off to development** immediately.
+
+While you continue with UX design, Freya can also handle development tasks:
+
+- Research knowledge gaps
+- Spike complex integrations
+- Set up the development environment
+- Validate technical assumptions
+
+**Parallel work.** Design and platform prep happen simultaneously.
+
+---
+
+## What's NOT in This Document
+
+- Database schemas
+- API specifications
+- Code architecture
+- Technical implementation details
+
+Those come later, in BMM's architecture phase.
+
+---
+
+## Connection to Design
+
+Every boundary you discover shapes your design:
+
+| Boundary | Design Impact |
+|----------|---------------|
+| Web only | No native mobile gestures |
+| No real-time | Polling instead of live updates |
+| Tight budget | Simpler interactions |
+| Legacy integration | Work within existing patterns |
+
+---
+
+## Practice
+
+Think about your current project:
+
+1. What platforms are you designing for?
+2. What integrations are required?
+3. What constraints exist?
+4. What feels risky?
+
+Document these before you start designing.
+
+---
+
+## Lessons
+
+### [Lesson 1: Why Boundaries Matter](lesson-01-why-boundaries-matter.md)
+Designing in reality, not fantasy
+
+### [Lesson 2: Defining Platform Requirements](lesson-02-defining-platform-requirements.md)
+How to document the boundaries that shape your design
+
+---
+
+## Tutorial
+
+### [Tutorial 05: Create Your Platform Requirements](tutorial-05.md)
+Hands-on guide to documenting technical boundaries with Saga
+
+---
+
+## Next Module
+
+**[Module 06: Trigger Mapping →](../module-06-trigger-mapping/module-06-overview.md)**
+
+Now understand the user psychology that drives behavior.
+
+---
+
+*Part of the WDS Course: From Designer to Linchpin*