Merge pull request #1 from benjaminhonorio/feature/github-pages-setup

Setup GitHub Pages and multi-scenario structure

Author: benjaminhonorio

.claude/CLAUDE.md

@@ -0,0 +1,45 @@
+# Project Instructions
+
+AWS Architecture learning scenarios for Solutions Architect certification prep.
+
+## Exam Reference
+
+[AWS Certified Solutions Architect - Associate (SAA-C03) Exam Guide](https://docs.aws.amazon.com/aws-certification/latest/examguides/solutions-architect-associate-03.html)
+
+## Creating Content
+
+### Mermaid Diagrams
+
+Follow [mermaid-style-guide.md](./mermaid-style-guide.md) for consistent styling:
+
+- Use `<br>` for line breaks (never `\n`)
+- Always add `color:#000` for text visibility
+- Add `linkStyle default stroke:#000,stroke-width:2px`
+- Use the color palette (VPC: `#e3f2fd`, Public: `#c8e6c9`, Private: `#fff9c4`, RDS: `#bbdefb`)
+
+### New Scenarios
+
+Follow [SCENARIO-GUIDELINES.md](./SCENARIO-GUIDELINES.md) for creating new learning scenarios:
+
+- Start with simple MVP, evolve naturally
+- Focus on the WHY behind each decision
+- Map to SAA exam domains
+- Use realistic business triggers
+
+## Project Structure
+
+```
+docs/                    # Docsify site (GitHub Pages)
+├── scenarios/
+│   └── techbooks/      # TechBooks scenario
+└── index.html
+
+.claude/                 # AI context and guides
+├── CLAUDE.md
+├── mermaid-style-guide.md
+└── SCENARIO-GUIDELINES.md
+```
+
+## Formatting
+
+Run `npm run format` to format markdown files with Prettier.

SCENARIO-GUIDELINES.md .claude/SCENARIO-GUIDELINES.mdSCENARIO-GUIDELINES.md renamed to .claude/SCENARIO-GUIDELINES.md

@@ -2,9 +2,13 @@
 
 ## Purpose
 
-Create realistic, evolving business scenarios that teach AWS Solutions Architect concepts through architecture design exercises. Each scenario should reinforce exam concepts through practical decisions and understanding trade-offs.
+Create realistic, evolving business scenarios that teach AWS Solutions Architect concepts through
+architecture design exercises. Each scenario should reinforce exam concepts through practical
+decisions and understanding trade-offs.
 
-> **Note:** These scenarios focus on **understanding architecture concepts** - following along with diagrams, reasoning through decisions, and learning the WHY. Actually deploying to AWS is optional and may incur costs.
+> **Note:** These scenarios focus on **understanding architecture concepts** - following along with
+> diagrams, reasoning through decisions, and learning the WHY. Actually deploying to AWS is optional
+> and may incur costs.
 
 ---
 
@@ -23,6 +27,7 @@ Day 1 MVP → Growth Pains → Reliability Needs → Scale Demands → Global Re
 ### 2. Focus on the WHY
 
 Every architectural decision should answer:
+
 - **Why this service?** (vs alternatives)
 - **Why now?** (business trigger)
 - **What problem does it solve?**
@@ -31,6 +36,7 @@ Every architectural decision should answer:
 ### 3. Map to SAA Exam Domains
 
 Ensure scenarios cover these exam domains:
+
 1. Design Secure Architectures
 2. Design Resilient Architectures
 3. Design High-Performing Architectures
@@ -44,16 +50,20 @@ Ensure scenarios cover these exam domains:
 
 ```
 aws-architecting/
-├── SCENARIO-GUIDELINES.md          # This file
-├── mermaid-style-guide.md          # Diagram styling reference
-└── {scenario-name}/
-    ├── docs/
-    │   ├── 00-scenario-overview.md
-    │   └── phases/
-    │       ├── phase-1-*.md
-    │       ├── phase-2-*.md
-    │       └── ...
-    └── diagrams/                    # Optional: generated images
+├── .claude/
+│   ├── CLAUDE.md                   # AI instructions
+│   ├── SCENARIO-GUIDELINES.md      # This file
+│   └── mermaid-style-guide.md      # Diagram styling reference
+└── docs/                           # Docsify site (GitHub Pages)
+    ├── index.html
+    ├── README.md                   # Landing page
+    ├── _sidebar.md
+    └── scenarios/
+        └── {scenario-name}/
+            ├── 00-overview.md
+            └── phases/
+                ├── phase-1-*.md
+                └── ...
 ```
 
 ### Phase Document Template
@@ -64,38 +74,48 @@ Each phase document should include:
 # Phase N: [Title]
 
 ## The Story So Far
+
 [Quick recap of current state]
 
 ## Business Trigger
+
 [What happened that requires this change?]
+
 - Customer complaints?
 - Outage?
 - Growth metrics?
 - New feature request?
 - Cost concerns?
 
 ## Architecture Decision
+
 [What are we building and WHY]
 
 ## Key Concepts for SAA Exam
+
 [Exam-relevant knowledge with depth]
 
 ### Concept 1
+
 - What it is
 - Why it matters
 - Common exam scenarios
 - Key numbers to remember
 
 ## Architecture Diagram
+
 [Mermaid diagram following style guide]
 
 ## (Optional) Hands-on Lab
+
 [Console/CLI walkthrough - include cost warnings if applicable]
 
 ## What Could Go Wrong?
+
 [Sets up the next phase's trigger]
 
 ## Exam Tips
+
 [Quick-reference bullets]
 ```
 
@@ -105,40 +125,45 @@ Each phase document should include:
 
 ### Typical 6-Phase Journey
 
-| Phase | Focus | Key Services | Exam Concepts |
-|-------|-------|--------------|---------------|
-| 1. MVP Launch | Get online fast | VPC, EC2, Security Groups | Networking basics, compute |
-| 2. Database Separation | Data durability | RDS, DB Subnet Groups | Managed services, backups |
-| 3. High Availability | Survive failures | Multi-AZ RDS, multiple AZs | HA vs FT, SLAs |
-| 4. Auto Scaling | Handle load | ALB, ASG, Launch Templates | Horizontal scaling, health checks |
-| 5. Going Global | Performance | CloudFront, Route 53, S3 | CDN, DNS, caching |
-| 6. Modernization | Optimize | Lambda, ElastiCache, SQS | Serverless, decoupling |
+| Phase                  | Focus            | Key Services               | Exam Concepts                     |
+| ---------------------- | ---------------- | -------------------------- | --------------------------------- |
+| 1. MVP Launch          | Get online fast  | VPC, EC2, Security Groups  | Networking basics, compute        |
+| 2. Database Separation | Data durability  | RDS, DB Subnet Groups      | Managed services, backups         |
+| 3. High Availability   | Survive failures | Multi-AZ RDS, multiple AZs | HA vs FT, SLAs                    |
+| 4. Auto Scaling        | Handle load      | ALB, ASG, Launch Templates | Horizontal scaling, health checks |
+| 5. Going Global        | Performance      | CloudFront, Route 53, S3   | CDN, DNS, caching                 |
+| 6. Modernization       | Optimize         | Lambda, ElastiCache, SQS   | Serverless, decoupling            |
 
 ### Business Triggers Library
 
 Use these realistic triggers to drive evolution:
 
 **Phase 1 → 2** (Database Separation)
+
 - "Database corrupted, no backup!"
 - "EC2 instance crashed, lost everything"
 - "Need to update app but scared to touch the server"
 
 **Phase 2 → 3** (High Availability)
+
 - "AZ outage took us offline for 4 hours"
 - "Customers complaining about downtime"
 - "Investor asking about our SLA"
 
 **Phase 3 → 4** (Auto Scaling)
+
 - "Black Friday traffic crashed the site"
 - "Paying for idle capacity at night"
 - "Manual scaling takes too long"
 
 **Phase 4 → 5** (Global)
+
 - "International customers complaining about slow loads"
 - "Image-heavy pages taking 5+ seconds"
 - "Expanding to new markets"
 
 **Phase 5 → 6** (Modernization)
+
 - "Monthly AWS bill too high"
 - "Want real-time features without managing servers"
 - "Need async processing for large uploads"
@@ -148,27 +173,39 @@ Use these realistic triggers to drive evolution:
 ## Scenario Ideas
 
 ### E-Commerce (TechBooks ✓)
+
 Online bookstore selling technical books
+
 - Good for: VPC, RDS, ALB, ASG, CloudFront
 
 ### SaaS Platform (Potential)
+
 Multi-tenant B2B application
+
 - Good for: Cognito, multi-account, tenant isolation
 
 ### Media Processing (Potential)
+
 Video/image processing pipeline
+
 - Good for: S3, Lambda, Step Functions, SQS, MediaConvert
 
 ### IoT Dashboard (Potential)
+
 Device telemetry and monitoring
+
 - Good for: IoT Core, Kinesis, DynamoDB, TimeStream
 
 ### Healthcare App (Potential)
+
 HIPAA-compliant patient portal
+
 - Good for: Security focus, encryption, compliance, VPC endpoints
 
 ### Startup to Enterprise (Potential)
+
 Growing company's internal tools
+
 - Good for: Organizations, Control Tower, multi-account
 
 ---
@@ -202,6 +239,7 @@ flowchart TB
 ```
 
 ### Key Rules
+
 1. Use `<br>` for line breaks (never `\n`)
 2. Always add `color:#000` for text visibility
 3. Add `linkStyle default stroke:#000,stroke-width:2px` for black arrows
@@ -212,18 +250,21 @@ flowchart TB
 ## Writing Tips
 
 ### For Exam Relevance
+
 - Include specific numbers (ports, limits, timeouts)
 - Compare similar services (ALB vs NLB, Multi-AZ vs Read Replicas)
 - Highlight "gotchas" and common misconceptions
 - Add "Exam Tip" callouts for key facts
 
 ### For Learning
+
 - Explain concepts before using them
 - Use analogies for complex topics
 - Show the problem before the solution
 - Include "What Could Go Wrong" to build intuition
 
 ### For Engagement
+
 - Give the scenario personality (founder's name, company culture)
 - Use realistic metrics and timelines
 - Include tough decisions with trade-offs

mermaid-style-guide.md .claude/mermaid-style-guide.mdmermaid-style-guide.md renamed to .claude/mermaid-style-guide.md

@@ -11,21 +11,22 @@ Reference for consistent diagram styling across all TechBooks architecture docum
 
 ## Color Palette
 
-| Purpose | Fill Color | With Text | Example |
-|---------|------------|-----------|---------|
-| **VPC / Container** | `#e3f2fd` | `fill:#e3f2fd,color:#000` | Light blue |
-| **Public Subnet** | `#c8e6c9` | `fill:#c8e6c9,color:#000` | Light green |
-| **Private Subnet** | `#fff9c4` | `fill:#fff9c4,color:#000` | Light yellow |
-| **Database / RDS** | `#bbdefb` | `fill:#bbdefb,color:#000` | Blue |
-| **Warning / Problem** | `#ffcdd2` | `fill:#ffcdd2,color:#000` | Light red |
-| **Success / Good** | `#c8e6c9` | `fill:#c8e6c9,color:#000` | Light green |
-| **Neutral / Future** | `#f5f5f5` | `fill:#f5f5f5,color:#000` | Light gray |
-| **Highlight** | `#fff3e0` | `fill:#fff3e0,color:#000` | Light orange |
-| **Info** | `#e8f5e9` | `fill:#e8f5e9,color:#000` | Very light green |
+| Purpose               | Fill Color | With Text                 | Example          |
+| --------------------- | ---------- | ------------------------- | ---------------- |
+| **VPC / Container**   | `#e3f2fd`  | `fill:#e3f2fd,color:#000` | Light blue       |
+| **Public Subnet**     | `#c8e6c9`  | `fill:#c8e6c9,color:#000` | Light green      |
+| **Private Subnet**    | `#fff9c4`  | `fill:#fff9c4,color:#000` | Light yellow     |
+| **Database / RDS**    | `#bbdefb`  | `fill:#bbdefb,color:#000` | Blue             |
+| **Warning / Problem** | `#ffcdd2`  | `fill:#ffcdd2,color:#000` | Light red        |
+| **Success / Good**    | `#c8e6c9`  | `fill:#c8e6c9,color:#000` | Light green      |
+| **Neutral / Future**  | `#f5f5f5`  | `fill:#f5f5f5,color:#000` | Light gray       |
+| **Highlight**         | `#fff3e0`  | `fill:#fff3e0,color:#000` | Light orange     |
+| **Info**              | `#e8f5e9`  | `fill:#e8f5e9,color:#000` | Very light green |
 
 ## Style Syntax Examples
 
 ### Basic node with color
+
 ```mermaid
 flowchart LR
     A["Node Label"] --> B["Another Node"]
@@ -34,20 +35,23 @@ flowchart LR
 ```
 
 ### Multi-line labels
+
 ```mermaid
 flowchart TB
     EC2["EC2 Instance<br>t3.micro<br>Public Subnet"]
     style EC2 fill:#fff9c4,color:#000
 ```
 
 ### Dashed border (for future/placeholder items)
+
 ```mermaid
 flowchart LR
     Future["Reserved for<br>Future Use"]
     style Future fill:#f5f5f5,color:#000,stroke-dasharray: 5 5
 ```
 
 ### Subgraph styling
+
 ```mermaid
 flowchart TB
     subgraph VPC["VPC: 10.0.0.0/16"]
@@ -71,6 +75,7 @@ flowchart LR
 ```
 
 **Styling specific links (by index):**
+
 ```mermaid
 flowchart LR
     A --> B
@@ -84,25 +89,26 @@ flowchart LR
 ```
 
 **Link style options:**
-| Property | Example | Description |
-|----------|---------|-------------|
-| `stroke` | `stroke:#000` | Line color |
-| `stroke-width` | `stroke-width:2px` | Line thickness |
-| `stroke-dasharray` | `stroke-dasharray:5,5` | Dashed line |
+
+| Property           | Example                 | Description    |
+| ------------------ | ----------------------- | -------------- |
+| `stroke`           | `stroke:#000`           | Line color     |
+| `stroke-width`     | `stroke-width:2px`      | Line thickness |
+| `stroke-dasharray` | `stroke-dasharray:5,5`  | Dashed line    |
 
 ## AWS Component Colors
 
-| Component | Recommended Style |
-|-----------|-------------------|
-| VPC | `fill:#e3f2fd,color:#000` |
-| Public Subnet | `fill:#c8e6c9,color:#000` |
+| Component      | Recommended Style         |
+| -------------- | ------------------------- |
+| VPC            | `fill:#e3f2fd,color:#000` |
+| Public Subnet  | `fill:#c8e6c9,color:#000` |
 | Private Subnet | `fill:#fff9c4,color:#000` |
-| EC2 | `fill:#fff9c4,color:#000` |
-| RDS | `fill:#bbdefb,color:#000` |
-| S3 | `fill:#c8e6c9,color:#000` |
-| Load Balancer | `fill:#e1f5fe,color:#000` |
+| EC2            | `fill:#fff9c4,color:#000` |
+| RDS            | `fill:#bbdefb,color:#000` |
+| S3             | `fill:#c8e6c9,color:#000` |
+| Load Balancer  | `fill:#e1f5fe,color:#000` |
 | Security Group | `fill:#e8f5e9,color:#000` |
-| Error/Problem | `fill:#ffcdd2,color:#000` |
+| Error/Problem  | `fill:#ffcdd2,color:#000` |
 
 ## Template