whiteport-design-studio 0.1.0

package/docs/learn-wds/module-06-platform-architecture/tutorial-06.md

@@ -0,0 +1,358 @@
+# Tutorial 06: Platform Architecture
+
+**Let Idunn translate your product vision into technical architecture - you speak design, she speaks code**
+
+---
+
+## Overview
+
+You've designed the experience. Now you need the technical foundation to make it real. But you're a designer, not a developer - how do you define databases, APIs, and system architecture?
+
+**You don't.** Idunn does.
+
+You just describe your product in design language. Idunn translates it into Platform PRD.
+
+**Time:** 30-45 minutes  
+**Prerequisites:** Module 05 completed (Trigger Map ready)  
+**What you'll create:** Platform PRD & Architecture Document
+
+---
+
+## What You'll Learn
+
+- What a Platform PRD is (and why it matters)
+- How to describe your product's technical needs without being technical
+- How Idunn helps you think through platform decisions
+- What questions she'll ask (so you're not surprised)
+
+---
+
+## What is Platform PRD?
+
+**Platform PRD** = The technical blueprint developers need to build your product.
+
+It includes:
+- **System Architecture:** How the pieces fit together
+- **Data Models:** What information needs to be stored
+- **APIs & Integrations:** How systems talk to each other
+- **Technical Requirements:** Performance, security, scalability
+
+**Your superpower:** You don't need to know how to write this. You just need to know **what your product does**.
+
+---
+
+## Step 1: Understand Your Role (2 min)
+
+**Your job as designer:**
+- Describe what users need to do
+- Explain what data they create/view/edit
+- Identify third-party services you want (payments, auth, analytics)
+- Share any technical constraints you know about
+
+**Idunn's job:**
+- Ask clarifying questions about technical needs
+- Translate your product into architecture decisions
+- Document data models, APIs, system diagrams
+- Flag technical risks and recommend solutions
+
+**You bring product knowledge. She brings technical expertise.**
+
+---
+
+## What to Expect: The Conversation
+
+**Here's how a real session with Idunn looks:**
+
+### Idunn's Opening
+```
+Hi! I'm Idunn, your technical architect agent.
+
+I see you've completed your Product Brief and Trigger Map. 
+Let's translate your product vision into technical architecture.
+
+I'll ask questions about your product in design language. 
+You answer naturally - no need for technical terms.
+
+Ready? Let's start with the basics.
+```
+
+### Example Questions Idunn Asks
+
+**About Your Product:**
+```
+Idunn: "What's the core thing users create or manage in your product?"
+
+You: "Users create weekly schedules for family dog care - walks, 
+      feeding, vet appointments, etc."
+
+Idunn: "Got it. Do these schedules need to be:
+        - Private (only one family)?
+        - Shared (multiple families can see each other's)?
+        - Collaborative (family members edit together)?"
+
+You: "Collaborative - all family members edit the same schedule."
+
+Idunn: "Perfect. That tells me we need real-time sync and user permissions."
+```
+
+**About Users & Authentication:**
+```
+Idunn: "How do you envision users signing up?"
+
+You: "Email and password should work. Google login would be nice too."
+
+Idunn: "Great! Should users be able to:
+        - Invite family members?
+        - Have different roles (admin vs. regular member)?"
+
+You: "Yes! The person who creates the schedule is the admin. 
+      They can invite family and remove members if needed."
+
+Idunn: "Understood. I'll design a role-based permission system."
+```
+
+**About Data & Features:**
+```
+Idunn: "You mentioned tasks like 'walks' and 'feeding'. 
+        What information does each task need?"
+
+You: "Task title, who's assigned, what time/date, and whether 
+      it's done or not."
+
+Idunn: "Should tasks repeat? Like 'walk dog every morning'?"
+
+You: "Oh yes! That would be super helpful."
+
+Idunn: "I'll add recurring task patterns. Should we notify 
+        the assigned person before the task is due?"
+
+You: "Definitely!"
+
+Idunn: "I'll include a notification system in the architecture."
+```
+
+### Built-in Guidance from Idunn
+
+**When you're unsure:**
+```
+You: "I'm not sure if we need that..."
+
+Idunn: "No problem! Let me explain the trade-offs:
+
+       WITH real-time sync:
+       ✅ Family sees changes instantly
+       ✅ No confusion about who's doing what
+       ❌ Slightly more complex to build
+       ❌ Requires internet connection
+
+       WITHOUT real-time sync:
+       ✅ Simpler to build
+       ✅ Can work offline
+       ❌ Family might have outdated info
+       ❌ Conflicts if two people edit at once
+
+       For family coordination, real-time is usually worth it.
+       What feels right for your users?"
+```
+
+**When technical terms come up:**
+```
+Idunn: "I'll use a REST API for communication between app and server."
+
+You: "What's a REST API?"
+
+Idunn: "Think of it as a waiter in a restaurant:
+        - Your app (customer) asks for something
+        - The API (waiter) takes the request to the server (kitchen)
+        - The server prepares the response (food)
+        - The API brings it back to your app
+
+        You don't need to know how it works - just that it's 
+        the standard way apps communicate with databases."
+```
+
+**When prioritizing features:**
+```
+Idunn: "Based on your Product Brief, I see you want:
+        - Task scheduling (core)
+        - Notifications (important)
+        - Calendar sync (nice-to-have)
+        - Vet appointment reminders (nice-to-have)
+
+        For the Platform PRD, I'll design all of these.
+        
+        But I'll flag which are 'MVP' (must-have) vs. 
+        'Phase 2' (add later) so developers know priorities.
+        
+        Does that split make sense?"
+
+You: "Yes, but actually calendar sync is really important."
+
+Idunn: "Got it - moving calendar sync to MVP. I'll update the 
+        architecture to prioritize that integration."
+```
+
+### What Idunn Creates While You Talk
+
+As you answer, Idunn is:
+- ✍️ Documenting data models ("Task" entity with fields)
+- 🏗️ Sketching system architecture (app, API, database, notifications)
+- 🔐 Planning authentication flow (login, permissions, roles)
+- 🔗 Identifying integrations (Google Calendar, email notifications)
+- ⚠️ Flagging technical risks ("Real-time sync needs WebSocket support")
+
+**You'll see progress updates:**
+```
+Idunn: "✅ Data model drafted - 3 main entities (User, Family, Task)
+        ✅ Authentication flow designed - Social login + email
+        🔄 Working on notification system architecture..."
+```
+
+---
+
+## Step 2: Activate Idunn (2 min)
+
+```
+@idunn
+
+I'm ready to create the Platform PRD for [Your Product Name].
+
+I have:
+- Product Brief (done)
+- Trigger Map (done)
+
+Please help me define the technical architecture.
+```
+
+**Idunn will respond** and start asking questions about your product's technical needs.
+
+---
+
+## Step 3: Answer Idunn's Questions (20-30 min)
+
+Idunn will guide you through understanding your platform needs. She asks questions like:
+
+### About Data
+- "What information do users create?"
+- "What needs to be saved vs. temporary?"
+- "Do users share data with each other?"
+
+**Example answers (you don't need technical terms):**
+- "Users create weekly schedules for dog care tasks"
+- "Schedules need to be saved permanently and shared with family"
+- "Each task has: title, assigned person, date, completion status"
+
+### About Authentication
+- "How do users log in?"
+- "Do you want social login (Google, Apple)?"
+- "Are there different user roles?"
+
+**Example answers:**
+- "Email + password, plus Google login"
+- "Two roles: Admin (can assign tasks) and Family Member (can complete tasks)"
+
+### About Integrations
+- "Do you need notifications?"
+- "Payment processing?"
+- "Calendar sync?"
+
+**Example answers:**
+- "Yes! Send reminders before tasks are due"
+- "No payments needed"
+- "Would be nice to sync with phone calendar"
+
+### About Performance & Scale
+- "How many users do you expect?"
+- "Any real-time features?"
+- "Mobile app or web?"
+
+**Idunn translates this into:**
+- Database schemas
+- API specifications
+- System architecture diagrams
+- Technical requirements docs
+
+---
+
+## Step 4: Review & Refine (10 min)
+
+Idunn will show you the Platform PRD. Don't panic if it looks technical - you don't need to understand every detail.
+
+**What to check:**
+- ✅ Does it capture all the features you designed?
+- ✅ Are the user roles correct?
+- ✅ Did she understand your data needs?
+- ✅ Are integrations you wanted included?
+
+**Ask questions like:**
+- "Can you explain this part in design terms?"
+- "How does this support [specific feature]?"
+- "What if we want to add [feature] later?"
+
+**Idunn will clarify** and update the PRD until it's right.
+
+---
+
+## Step 5: Save Your Platform PRD (2 min)
+
+Idunn will save the Platform PRD to your project:
+
+```
+/docs/3-platform-prd/
+├── 01-platform-architecture.md
+├── 02-data-models.md
+├── 03-api-specifications.md
+└── 04-technical-constraints.md
+```
+
+**You now have** everything developers need to understand the technical foundation.
+
+---
+
+## Common Questions
+
+**Q: Do I need to learn technical terms?**  
+**A:** No. Speak in design/product language. Idunn translates.
+
+**Q: What if I don't know the answer to her questions?**  
+**A:** Say so! Idunn will explain the implications and suggest options.
+
+**Q: Can developers change the architecture later?**  
+**A:** Yes. This is a starting point. Developers may refine it.
+
+**Q: Do I need to review APIs and database schemas?**  
+**A:** Only if you want to. Focus on whether it supports your design.
+
+---
+
+## What You've Accomplished
+
+🎉 **You just created a Platform PRD** - something that usually requires technical architects!
+
+**You didn't need to:**
+- ❌ Learn database design
+- ❌ Understand API protocols
+- ❌ Draw system architecture diagrams
+- ❌ Write technical specifications
+
+**You just:**
+- ✅ Described your product in design terms
+- ✅ Answered Idunn's questions
+- ✅ Reviewed to ensure it supports your design
+
+**That's the WDS superpower:** You focus on design. The agents handle the technical translation.
+
+---
+
+## Next Steps
+
+**Ready to design the UX?**  
+→ [Module 08: Initialize Scenario](../module-08-initialize-scenario/tutorial-08.md)
+
+**Want to skip Platform PRD for now?**  
+You can come back to this after UX design if you prefer.
+
+---
+
+**Pro Tip:** Even if you're not building the platform yourself, having this PRD helps you communicate with developers and make informed design decisions. You'll know what's technically feasible without becoming a developer yourself.
+