Architecture Decision Records (ADRs)

🎯 Why Document Decisions?

Architecture Decision Records capture significant choices made during textbook development, including:

Context: Why we needed to decide
Decision: What we chose
Alternatives: What else we considered
Rationale: Why this choice won
Consequences: Trade-offs and implications

ADRs Provide:

✅ Transparency: Understand why, not just what
✅ Onboarding: New contributors learn reasoning
✅ Consistency: Future decisions reference past patterns
✅ Accountability: Decisions can be reviewed and revised

📋 All ADRs

ADR-001: Docusaurus for Textbook Delivery

Status: ✅ Accepted | Date: 2025-11-29

Decision: Use Docusaurus (v3.x with TypeScript) as the textbook platform

Context:

Hackathon requires deploying book to GitHub Pages
Need dual sidebars (textbook chapters + methodology showcase)
Must support ROS 2 code examples (Python, C++, YAML, Bash, XML)
Students need professional, mobile-responsive experience

Alternatives Considered:

GitBook - Rejected (proprietary, not GitHub Pages)
MkDocs + Material - Rejected (limited sidebar flexibility)
mdBook - Rejected (no multi-sidebar support)
VuePress - Rejected (smaller community than Docusaurus)
Jupyter Book - Rejected (overkill for markdown-first content)

Rationale:

GitHub Pages deployment is first-class (official guide)
Dual sidebars support textbook + methodology showcase
React ecosystem enables future interactive components
50k+ GitHub stars, active development
Syntax highlighting for entire ROS 2 stack
Mermaid diagram support built-in

Consequences:

✅ Professional, responsive site with search
✅ Easy for contributors to add chapters (markdown)
✅ Automated deployment via GitHub Actions
⚠️ Node.js dependency (requires npm for local builds)
⚠️ React knowledge helpful for advanced customization

→ Read Full ADR-001

ADR-002: GitHub Pages Deployment Strategy

Status: ⚠️ Superseded by ADR-006 | Date: 2025-11-29

Decision: Use GitHub Actions to auto-deploy to GitHub Pages via actions/deploy-pages@v4

Context:

After choosing Docusaurus (ADR-001), need deployment strategy
Hackathon explicitly requires GitHub Pages
Must automate (no manual npm run deploy commands)
Free tier required (educational/hackathon context)

Alternatives Considered:

Netlify - Rejected (not GitHub Pages, hackathon requirement)
Vercel - Rejected (not GitHub Pages)
Manual gh-pages Branch - Rejected (no automation, error-prone)
Self-Hosted (AWS S3 + CloudFront) - Rejected (cost, complexity)
Read the Docs - Rejected (not GitHub Pages, Sphinx-centric)

Deployment Flow:

Push to main → GitHub Actions → Build → Deploy → Live Site
     (2-4 minutes total)

Rationale:

Official solution recommended by GitHub and Docusaurus
Push-to-deploy automation (no manual intervention)
Path filtering saves GitHub Actions minutes
Manual trigger capability (workflow_dispatch)
Build artifacts retained for debugging
Completely free for public repositories

Consequences:

✅ Push-to-deploy in 3-5 minutes
✅ Build failures prevent bad deploys
✅ Students can fork and deploy their own versions
⚠️ No PR preview deployments (would need Netlify for this)
⚠️ GitHub Pages 1GB site limit (unlikely to hit)

→ Read Full ADR-002

ADR-003: ROS 2 Humble as Primary Distribution

Status: ✅ Accepted | Date: 2025-11-29

Decision: Use ROS 2 Humble Hawksbill as the primary and required distribution for all textbook content

Context:

Textbook must select ROS 2 distribution supported through 2025-2027 academic years
Need long-term stability, wide hardware support, strong ecosystem
Must align with industry deployments

Alternatives Considered:

ROS 2 Iron - Rejected (EOL Nov 2024, already deprecated)
ROS 2 Jazzy - Rejected (not released during authoring, immature ecosystem)
ROS 1 Noetic - Rejected (EOL May 2025, legacy platform)
Multi-Distribution Support - Rejected (2x maintenance burden)

Rationale:

Humble LTS support until May 2027 (full overlap with textbook usage)
Jetson JetPack 5.x fully supports Humble on Ubuntu 22.04
MoveIt 2, Nav2, ros2_control all stable on Humble
Industry standard (Boston Dynamics, Figure AI use Humble)

Consequences:

✅ Code examples work unchanged through 2027
✅ All hardware tiers support Humble natively
✅ 1000+ packages available via apt
⚠️ Newer features from Iron/Jazzy unavailable

→ Read Full ADR-003

ADR-004: Multi-Simulation Platform Strategy

Status: ✅ Accepted | Date: 2025-11-29

Decision: Adopt multi-simulation strategy with Gazebo Classic, NVIDIA Isaac Sim, and Unity (optional)

Context:

Physical AI needs simulation before deploying to expensive robots
Different chapters need different simulation capabilities (physics vs photorealism)
Students have varying hardware (cloud-only, Jetson, gaming PC)

Alternatives Considered:

Gazebo-Only - Rejected (insufficient photorealism for vision AI)
Isaac Sim-Only - Rejected (hardware barrier, overkill for foundations)
Unity-Only - Rejected (ROS 2 integration clunky)
PyBullet/MuJoCo - Rejected (no sensor simulation, headless only)

Rationale:

Gazebo Classic: Foundation chapters (2-3), fast iteration, lightweight
Isaac Sim: Vision AI chapters (7-9), photorealistic rendering for YOLO/SAM
Unity: Optional for Chapter 9 VLA training (ML-Agents)

Workflow Coverage:

Chapter	Platform	Why
2: ROS 2	Gazebo	Fast iteration
4: Perception	Isaac Sim	Photorealistic cameras
5: SLAM	Gazebo	Nav2 tutorials use it
7: Vision AI	Isaac Sim	Realistic textures

Consequences:

✅ Right tool for each job
✅ Hardware accessibility (Gazebo for low-end)
✅ Industry skills (students learn 2-3 platforms)
⚠️ Learning curve multiplication (3 UIs)
⚠️ Setup complexity (3 install guides)

→ Read Full ADR-004

ADR-005: Assessment Methodology - Action-Based Evaluation

Status: ✅ Accepted | Date: 2025-11-29

Decision: Use "Assessment by Action" - deployable ROS 2 artifacts instead of traditional exams

Assessment Structure:

Hands-On Labs (50% of grade) - Deployable ROS 2 packages per chapter
Automated Acceptance Tests (30% of grade) - GitHub Actions runs behavioral tests
Capstone Project (20% of grade) - Voice-commanded humanoid butler

Context:

Traditional CS assessments (multiple-choice exams) don't measure robotics practical skills
Industry employers want portfolios (GitHub repos), not test scores
Need fairness across hardware tiers (cloud-only vs physical robots)

Alternatives Considered:

Traditional Written Exams - Rejected (doesn't measure practical skills)
Written Lab Reports - Rejected (report ≠ working code)
GitHub + Code Review - Partially accepted (use for capstone)
Video Demonstrations - Supplementary (require video + code)
Automated Testing Only - Partially accepted (combine with human review)

Rationale:

Every assessment = working robot code (employable artifacts)
Aligns with "Embodiment-First Instruction" principle
Hardware-tiered grading prevents "rich student advantage"
Portfolio-ready work for job applications

Grading Tiers:

Tier	Hardware	Max Score
0	Cloud (Gazebo)	90% (A-)
1	Jetson	95%
2+	Physical robot	100%

Consequences:

✅ Portfolio-ready work for job applications
✅ Immediate feedback via automated tests
✅ Skills transfer directly to industry
⚠️ Git learning curve for students
⚠️ Test maintenance for instructors

→ Read Full ADR-005

ADR-006: Deployment Strategy Evolution - Vercel over GitHub Pages

Status: ✅ Accepted | Date: 2025-11-29 Supersedes: ADR-002

Decision: Migrate to Vercel as primary deployment platform, GitHub Pages as fallback

Context:

Original plan was GitHub Pages (hackathon requirement)
Encountered GitHub Actions deployment failures due to account restrictions
Need reliable deployment without Git hosting dependencies

Alternatives Considered:

Continue with GitHub Pages - Rejected (account issues, unclear resolution)
Netlify - Good alternative, but Vercel has better DX for React ecosystem
Cloudflare Pages - Good option, less mature Docusaurus support
AWS S3 + CloudFront - Rejected (cost, complexity)
Self-Hosted VPS - Rejected (monthly cost, maintenance)

Rationale:

Vercel CLI bypasses Git entirely (solves GitHub account issue)
Zero-config Docusaurus support (auto-detects, deploys in 90 seconds)
Free for open-source with unlimited bandwidth
Preview deployments available (if Git integration enabled later)

Deployment Flow:

cd physical-ai-textbook
vercel --prod  # 90 seconds → live site

Consequences:

✅ Immediate deployment despite GitHub issues
✅ 10x faster than GitHub Actions (90s vs 5-10min)
✅ Better debugging (Vercel logs clearer)
⚠️ Platform dependency (locked into Vercel)
⚠️ Two deployment paths to document (Vercel + GitHub Pages fallback)

→ Read Full ADR-006

ADR-007: Mermaid for Architecture Diagrams

Status: ✅ Accepted | Date: 2025-11-29

Decision: Use Mermaid as primary diagramming language for all architectural, sequence, state, and flow diagrams

Context:

Textbook needs extensive technical diagrams (system architecture, state machines, sequences)
Must be version control friendly (text-based, diff-able in Git)
Must integrate with Docusaurus/Markdown without external tools
Must be maintainable and accessible

Alternatives Considered:

PlantUML - Rejected (requires Java + Graphviz, server dependency)
Graphviz (DOT) - Rejected (build tool dependency, not Docusaurus-native)
Draw.io - Rejected (binary XML, not version control friendly)
Excalidraw - Rejected (GUI-based, not code)
ASCII Art - Rejected (limited expressiveness, accessibility issues)

Rationale:

Native Docusaurus Support: @docusaurus/theme-mermaid plugin built-in
Markdown-Native: Code blocks render automatically
No Build Step: Renders client-side, no preprocessing
Rich Diagram Types: Flowcharts, sequences, states, classes, Gantt, ER
GitHub Integration: GitHub/GitLab render Mermaid automatically

Example Usage:

```mermaid
graph LR
    A[Perception] --> B[Planning]
    B --> C[Control]
```

Consequences:

✅ Zero build overhead
✅ Fast authoring (write diagrams in same file as content)
✅ Git-friendly (clean diffs, easy code reviews)
✅ Dark mode support (themes match Docusaurus)
⚠️ Layout limitations (auto-layout only, can't manually position)
⚠️ Browser requirement (requires JavaScript)

→ Read Full ADR-007

📊 ADR Statistics

By Category

Tooling & Infrastructure: 4 ADRs (Docusaurus, GitHub Pages→Vercel, Mermaid)
Platform & Architecture: 3 ADRs (ROS 2 Humble, Multi-Simulation, Assessment)

By Status

Accepted: 6 ADRs (001, 003, 004, 005, 006, 007)
Superseded: 1 ADR (002 - replaced by 006)
Proposed: 0 ADRs
Deprecated: 0 ADRs

Timeline

2025-11-29: All 7 ADRs created during initial textbook development

🎯 When to Create an ADR

ADRs are created during the /sp.plan phase when decisions meet ALL three criteria:

1. Impact

Does this decision have long-term consequences?

Framework choice
Data model design
API contracts
Security approach
Platform selection

2. Alternatives

Are there multiple viable options with different trade-offs?

Docusaurus vs GitBook vs MkDocs
GitHub Pages vs Netlify vs Vercel
Python vs C++ for ROS 2 nodes
Gazebo vs Unity vs Isaac for simulation

3. Scope

Does it influence system design across multiple chapters?

Toolchain version selection (affects all chapters)
Code standards (Black formatter, docstring style)
Assessment strategy (quizzes vs projects vs both)

If ALL three are true → /sp.adr <decision-title>

📝 How to Create an ADR

During planning, Claude suggests ADRs automatically:

📋 Architectural decision detected: Docusaurus for Textbook Delivery
   Document reasoning and tradeoffs? Run `/sp.adr docusaurus-selection`

Manual Creation

/sp.adr <decision-title>

Example:

/sp.adr ros2-humble-vs-iron

What Happens:

Creates history/adr/XXX-<slug>.md
Prompts for context, alternatives, rationale
Documents trade-offs and consequences
Links to related specs/plans
Sets status (Proposed → Accepted/Rejected)

🔄 ADR Lifecycle

graph LR
    A[Problem Identified] --> B{Significant?}
    B -->|No| C[Document in Plan]
    B -->|Yes| D[Create ADR]
    D --> E[Proposed]
    E --> F{Reviewed?}
    F -->|Approved| G[Accepted]
    F -->|Rejected| H[Rejected]
    G --> I{Still Valid?}
    I -->|Yes| G
    I -->|No| J[Deprecated]
    J --> K[New ADR Supersedes]

    style G fill:#4CAF50
    style H fill:#F44336
    style J fill:#FF9800

Status Meanings:

Proposed: Under discussion, not yet approved
Accepted: Decision made, actively in use
Rejected: Evaluated but not chosen
Deprecated: Was accepted, now outdated
Superseded: Replaced by newer ADR (link provided)

📚 Example Use Cases

From Chapter Planning

Scenario: Planning Chapter 2 (ROS 2 Fundamentals)

Question: Which ROS 2 distribution to use?

Options: Humble (LTS), Iron (latest), Jazzy (future)
Decision: Humble Hawksbill
ADR: [Future] ADR-003: ROS 2 Humble as Primary Distribution

Question: Black vs autopep8 for Python formatting?

Documented in: plan.md (not significant enough for ADR)
Rationale: Community standard, consistent with ROS 2 ecosystem

From Implementation

Scenario: Implementing Chapter 4 (Perception)

Question: OpenCV Python bindings vs ROS 2 image_pipeline?

Options: Direct OpenCV (simpler) vs ROS 2 nodes (integrated)
Decision: ROS 2 image_pipeline
ADR: [Future] ADR-004: ROS 2 Image Pipeline for Perception

🔗 ADR Templates

All ADRs follow this structure:

# ADR-XXX: <Title>

## Status
[Proposed/Accepted/Rejected/Deprecated/Superseded] | YYYY-MM-DD

## Context
[Why we needed to make this decision...]

## Decision
[What we chose to do...]

## Alternatives Considered
### 1. [Option Name]
**Pros**: ...
**Cons**: ...
**Verdict**: Rejected because...

### 2. [Another Option]
...

## Rationale
[Why this decision wins...]

## Consequences
### Positive
- ✅ [Good outcome 1]
- ✅ [Good outcome 2]

### Negative
- ⚠️ [Trade-off 1]
- ⚠️ [Trade-off 2]

### Neutral
- ℹ️ [Neutral fact 1]

## References
- [Link to docs]
- [Link to related ADRs]

## Related ADRs
- [ADR-XXX: Related Decision]

---

**Decision Made By**: [Who]
**Date**: YYYY-MM-DD
**Reviewed By**: [Who]
**Status**: [Current Status]

🚀 Future ADRs

Planned (From Chapter Development)

ADR-003: ROS 2 Humble as Primary Distribution
- Context: Multiple ROS 2 versions available
- Needs: Stability vs latest features trade-off
ADR-004: Mermaid vs PlantUML for Diagrams
- Context: Need architecture diagrams in chapters
- Needs: Markdown integration vs diagram complexity
ADR-005: Gazebo Classic vs Gazebo (New)
- Context: Gazebo Classic reaching EOL in 2025
- Needs: Stability vs new physics features

Community-Proposed

Have an idea for a decision that should be documented? Open an issue: Propose ADR

📖 Learn More

About ADRs

Michael Nygard's ADR Template (original)
ADR Tools (command-line management)
When to Write an ADR (comprehensive guide)

Spec-Driven Workflow: How ADRs fit in planning
PHR Gallery: See PHRs that reference ADRs
Constitution: Quality standards for ADRs

💡 Best Practices

For Decision Makers

Don't Over-ADR: Not every choice needs an ADR (use plan.md for minor decisions)
Capture Alternatives: Even rejected options are valuable learning
Link Consequences: Be honest about trade-offs
Update Status: Mark as Deprecated when no longer valid
Cross-Reference: Link to related ADRs and PHRs

For Readers

Start with Context: Understand why before what
Study Alternatives: See what was considered and why it lost
Check Status: Accepted ADRs are current; Deprecated ones are historical
Follow Links: Related ADRs provide full picture
Question Decisions: ADRs can be challenged with new ADRs

📬 Feedback

Questions about an ADR or want to propose changes?

Open an issue: GitHub Issues
Reference the ADR number for context

ADRs are living documents. As the textbook evolves, so do our decisions. Transparency over perfection.

Last Updated: 2025-11-29 | Total ADRs: 2

🎯 Why Document Decisions?​

📋 All ADRs​

ADR-001: Docusaurus for Textbook Delivery​

ADR-002: GitHub Pages Deployment Strategy​

ADR-003: ROS 2 Humble as Primary Distribution​

ADR-004: Multi-Simulation Platform Strategy​

ADR-005: Assessment Methodology - Action-Based Evaluation​

ADR-006: Deployment Strategy Evolution - Vercel over GitHub Pages​

ADR-007: Mermaid for Architecture Diagrams​

📊 ADR Statistics​

By Category​

By Status​

Timeline​

🎯 When to Create an ADR​

1. Impact​

2. Alternatives​

3. Scope​

📝 How to Create an ADR​

Manual Creation​

🔄 ADR Lifecycle​

📚 Example Use Cases​

From Chapter Planning​

From Implementation​

🔗 ADR Templates​

🚀 Future ADRs​

Planned (From Chapter Development)​

Community-Proposed​

📖 Learn More​

About ADRs​

Related Methodology Pages​

💡 Best Practices​

For Decision Makers​

For Readers​

📬 Feedback​

🎯 Why Document Decisions?

📋 All ADRs

ADR-001: Docusaurus for Textbook Delivery

ADR-002: GitHub Pages Deployment Strategy

ADR-003: ROS 2 Humble as Primary Distribution

ADR-004: Multi-Simulation Platform Strategy

ADR-005: Assessment Methodology - Action-Based Evaluation

ADR-006: Deployment Strategy Evolution - Vercel over GitHub Pages

ADR-007: Mermaid for Architecture Diagrams

📊 ADR Statistics

By Category

By Status

Timeline

🎯 When to Create an ADR

1. Impact

2. Alternatives

3. Scope

📝 How to Create an ADR

Manual Creation

🔄 ADR Lifecycle

📚 Example Use Cases

From Chapter Planning

From Implementation

🔗 ADR Templates

🚀 Future ADRs

Planned (From Chapter Development)

Community-Proposed

📖 Learn More

About ADRs

Related Methodology Pages

💡 Best Practices

For Decision Makers

For Readers

📬 Feedback