Add workshop materials and technical architecture diagram

docs/diagrams/source/platform_technical_architecture.mmd

@@ -0,0 +1,58 @@
+flowchart TB
+  subgraph Client
+    B[Browser]
+  end
+
+  subgraph WebApp[Rails Engine]
+    C[Controllers]
+    V[Views & Stimulus]
+    P[Policies & RBAC]
+    M[Models]
+  end
+
+  subgraph Jobs[Background Jobs]
+    SJ[Sidekiq Workers]
+    N[Notifications - Noticed]
+  end
+
+  subgraph Data
+    DB[(PostgreSQL + PostGIS)]
+    ES[(Elasticsearch)]
+    REDIS[(Redis)]
+    AS[(Active Storage)]
+  end
+
+  subgraph External
+    SMTP[Email Service]
+    GEO[Geocoding API]
+  end
+
+  AC[Action Cable]
+
+  B -->|HTTP| C
+  C --> P
+  C --> M
+  C --> V
+  V --> B
+  C --> AC
+
+  M --> DB
+  M --> ES
+  M --> AS
+  SJ --> DB
+  SJ --> ES
+  SJ --> AS
+  SJ --> N
+  N --> SMTP
+  AC --> REDIS
+  SJ --> GEO
+
+  classDef web fill:#e3f2fd,stroke:#90caf9
+  classDef jobs fill:#fff3e0,stroke:#ffb74d
+  classDef data fill:#e8f5e9,stroke:#81c784
+  classDef ext fill:#f3e5f5,stroke:#ba68c8
+
+  class C,V,P,M,AC web
+  class SJ,N jobs
+  class DB,ES,REDIS,AS data
+  class SMTP,GEO ext

docs/scripts/export_pdfs.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Export specified Markdown files to PDF using pandoc if available.
+# Usage: docs/scripts/export_pdfs.sh [files...]
+
+if [ $# -eq 0 ]; then
+  echo "Usage: $(basename "$0") file1.md [file2.md ...]" >&2
+  echo "Example: $(basename "$0") docs/workshop/intro_agenda_printable.md" >&2
+  exit 2
+fi
+
+if ! command -v pandoc >/dev/null 2>&1; then
+  echo "pandoc is not installed. Please install pandoc to export PDFs." >&2
+  echo "Alternatively, open the Markdown in your editor/viewer and print to PDF." >&2
+  exit 1
+fi
+
+for f in "$@"; do
+  if [ ! -f "$f" ]; then
+    echo "File not found: $f" >&2
+    exit 3
+  fi
+  out="${f%.md}.pdf"
+  echo "Exporting $f -> $out"
+  pandoc "$f" -o "$out" --from=markdown --pdf-engine=xelatex || pandoc "$f" -o "$out"
+done
+
+echo "PDF export complete."
+

docs/scripts/render_slides.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Render slides with reveal-md if available. Falls back to instructions.
+
+SLIDES_MD=${1:-docs/workshop/slides/intro_slides.md}
+OUT_DIR=${2:-docs/workshop/slides/dist}
+PDF_OUT=${3:-docs/workshop/slides/dist/intro_slides.pdf}
+
+mkdir -p "$OUT_DIR"
+
+if command -v reveal-md >/dev/null 2>&1; then
+  echo "Using system reveal-md to render static HTML..."
+  reveal-md "$SLIDES_MD" --static "$OUT_DIR"
+elif command -v npx >/dev/null 2>&1; then
+  echo "Using npx reveal-md to render static HTML..."
+  npx -y reveal-md "$SLIDES_MD" --static "$OUT_DIR"
+else
+  echo "Neither reveal-md nor npx is available. Skipping HTML render." >&2
+fi
+
+# Attempt PDF export (requires Puppeteer/Chromium in reveal-md). This may fail in restricted envs.
+if command -v reveal-md >/dev/null 2>&1; then
+  echo "Attempting PDF export via reveal-md (may require Chromium)..."
+  if ! reveal-md "$SLIDES_MD" --print "$PDF_OUT"; then
+    echo "WARN: reveal-md PDF export failed. Use a browser to print:"
+    echo "  Open ${OUT_DIR}/intro_slides.html?print-pdf and Save as PDF"
+  fi
+elif command -v npx >/dev/null 2>&1; then
+  echo "Attempting PDF export via npx reveal-md (may require Chromium)..."
+  if ! npx -y reveal-md "$SLIDES_MD" --print "$PDF_OUT"; then
+    echo "WARN: reveal-md PDF export failed. Use a browser to print:"
+    echo "  Open ${OUT_DIR}/intro_slides.html?print-pdf and Save as PDF"
+  fi
+fi
+
+echo "Slides rendering complete (if tools available). Output: $OUT_DIR"
+

docs/table_of_contents.md

@@ -102,6 +102,44 @@ Welcome to the comprehensive documentation for the Better Together Community Eng
 *Mermaid diagrams and visual system documentation*
 - [📝 README](diagrams/README.md) - Diagram system overview
 
+#### 🧭 **Workshop** - [`workshop/`](workshop/)
+- [📘 Index](workshop/index.md) - Course overview and materials
+- [🖨️ Intro Agenda (Printable)](workshop/intro_agenda_printable.md)
+- [🖼️ Intro Slides Outline](workshop/intro_slides_outline.md)
+- [🎞️ Intro Slides (Reveal.js Markdown)](workshop/slides/intro_slides.md)
+  - [Slides: Module 00](workshop/slides/module_00.md)
+  - [Slides: Module 01](workshop/slides/module_01.md)
+  - [Slides: Module 02](workshop/slides/module_02.md)
+  - [Slides: Module 03](workshop/slides/module_03.md)
+  - [Slides: Module 04](workshop/slides/module_04.md)
+  - [Slides: Module 05](workshop/slides/module_05.md)
+  - [Slides: Module 06](workshop/slides/module_06.md)
+  - [Slides: Module 07](workshop/slides/module_07.md)
+  - [Slides: Module 08](workshop/slides/module_08.md)
+- [🧑‍🏫 Facilitator Notes: Intro Workshop](workshop/facilitator_notes_intro_workshop.md)
+  - [📝 Per‑Module Notes](workshop/facilitator_notes/)
+- [🧭 Module 00: Orientation](workshop/module_00_orientation.md)
+- [🏗️ Module 01: Big Picture Architecture](workshop/module_01_big_picture_architecture.md)
+- [💻 Module 02: Local Setup (Docker)](workshop/module_02_local_setup.md)
+- [🧱 Module 03: Data & Conventions](workshop/module_03_data_and_conventions.md)
+- [🔐 Module 04: Authorization & Privacy](workshop/module_04_authorization_and_privacy.md)
+- [🌍 Module 05: I18n & UI](workshop/module_05_i18n_and_ui.md)
+- [📣 Module 06: Jobs, Notifications, Search](workshop/module_06_jobs_notifications_search.md)
+- [🧪 Module 07: Testing, CI, Security](workshop/module_07_testing_ci_security.md)
+- [🚀 Module 08: Deployments & Day‑2 Ops](workshop/module_08_deployments_and_day2_ops.md)
+- [✅ Preflight Checklist](workshop/checklists/preflight_checklist.md)
+- [⌨️ Commands Cheat Sheet](workshop/cheat_sheets/commands_cheat_sheet.md)
+- [🧪 Lab 01: Hello Engine](workshop/labs/lab_01_hello_engine.md)
+- [🧪 Lab 02: Model + Migration](workshop/labs/lab_02_model_and_migration.md)
+- [🧪 Lab 03: Policy & Token Access](workshop/labs/lab_03_policy_and_token_access.md)
+- [🧪 Lab 04: I18n Add Strings & Health](workshop/labs/lab_04_i18n_add_strings_and_health.md)
+- [🧪 Lab 05: Notifier + Job + ES Query](workshop/labs/lab_05_notifier_and_job_with_es_query.md)
+- [🧪 Lab 06: Controller → Request Spec](workshop/labs/lab_06_controller_to_request_spec.md)
+- [🧪 Lab 07: Dokku Deploy + Rollback](workshop/labs/lab_07_dokku_deploy_and_rollback.md)
+- [🎓 Capstone Overview](workshop/capstone/README.md)
+- [📏 Capstone Rubric](workshop/capstone/rubric.md)
+- [🧩 Capstone Submission Template](workshop/capstone/submission_template.md)
+
 ##### **Diagram Sources** - [`diagrams/source/`](diagrams/source/)
 *Mermaid (.mmd) source files*
 - [👤 Accounts Flow](diagrams/source/accounts_flow.mmd)
@@ -196,3 +234,5 @@ This table of contents is automatically maintained. When adding new documentatio
 *Last Updated: August 22, 2025*
 *Documentation Structure: Stakeholder-Focused Organization*
 *Diagram Integration: GitHub-compatible Mermaid rendering with multi-format exports*
+- [🛠️ Slide Render Script](../docs/scripts/render_slides.sh)
+- [🛠️ PDF Export Script](../docs/scripts/export_pdfs.sh)

docs/workshop/capstone/README.md

@@ -0,0 +1,28 @@
+# Capstone — End‑to‑End Feature
+
+Build and deploy a small feature from spec to production, demonstrating TDD, i18n, security, and operability.
+
+## Objectives
+- Design and implement a scoped feature (1–2 models or UI dimensions, not a rewrite)
+- Follow TDD (acceptance criteria → failing tests → minimum code → refactor)
+- Provide i18n coverage and security checks
+- Deploy to staging (or Dokku) and demonstrate end‑to‑end behavior
+
+## Example Project Ideas
+- Events: add an “attending with guests” count field with validation + UI + tests
+- Search: add a simple filter/sort for events or posts; include ES query and tests
+- Notifications: add an organizer-only reminder notifier for a new action
+- I18n: transform a small feature’s text surfaces into fully localized strings, including mailers
+
+## Deliverables
+- Short design note: intent, scope, data changes (if any), risks
+- Tests (request/model/job/notifier as applicable)
+- Feature implementation and localized strings
+- Deployment notes (env/secrets, migration plan if any)
+- Demo walkthrough and logs/screenshots
+
+## Timeline
+- Week 6: Pick and scope; write acceptance criteria
+- Week 7: Implement with tests; mid‑week check‑in
+- Week 8: Deploy; demo; peer feedback
+

docs/workshop/capstone/rubric.md

@@ -0,0 +1,19 @@
+# Capstone Rubric
+
+Each team’s capstone is scored across criteria that reflect project standards.
+
+## Scoring (0–4 each; total 32)
+- Requirements (AC): clear acceptance criteria, realistic scope
+- Tests: request-first approach; coverage of critical paths; readable
+- Code Quality: follows conventions, string enums, concerns; minimal complexity
+- Internationalization: all user-facing strings localized; i18n health passes
+- Security: Brakeman/bundler-audit clean; safe patterns (no unsafe constantization)
+- Operations: deploy plan documented; env/secrets noted; migration plan if applicable
+- Observability: Sidekiq/notifications logs visible; error handling reasonable
+- Demo: coherent narrative; shows end-to-end behavior; answers Q&A clearly
+
+## Guidance
+- Favor smaller, well‑tested scope over under‑tested ambition
+- Include performance and access control considerations if relevant
+- Provide a short “risks & follow‑ups” section for realism
+

docs/workshop/capstone/submission_template.md

@@ -0,0 +1,44 @@
+# Capstone Submission Template
+
+Use this template to structure your submission.
+
+## 1. Title & Team
+- Feature name
+- Team members and roles
+
+## 2. Problem & Goals
+- What problem does this feature solve?
+- Success criteria (acceptance criteria)
+
+## 3. Design & Scope
+- Architecture notes (models, controllers, jobs, search, UI)
+- Data model changes (migrations) — include enum and naming conventions
+- Privacy/authorization considerations
+
+## 4. Implementation
+- Key commits and files changed
+- i18n coverage (keys added, locales updated)
+- Security notes (Brakeman/bundler‑audit status)
+
+## 5. Tests
+- Request specs and other relevant tests
+- How to run the suite (focused commands if needed)
+
+## 6. Deployment Plan
+- Env/secrets required
+- Migration strategy (if applicable)
+- Post‑deploy checks (logs, Sidekiq, health endpoints)
+
+## 7. Observability & Operations
+- Logging and error handling approach
+- Metrics/monitoring (if any)
+- Rollback plan
+
+## 8. Demo Guide
+- Steps to demonstrate the feature end‑to‑end
+- Screenshots or expected outputs (optional)
+
+## 9. Risks & Follow‑Ups
+- Known limitations
+- Future enhancements
+

docs/workshop/cheat_sheets/commands_cheat_sheet.md

@@ -0,0 +1,30 @@
+# Commands Cheat Sheet
+
+Use these commands during workshops and daily development.
+
+## Core
+- Run tests: `bin/dc-run bin/ci`
+- RSpec (file): `bin/dc-run bundle exec rspec spec/path/to/file_spec.rb`
+- RSpec (line): `bin/dc-run bundle exec rspec spec/path/to/file_spec.rb:123`
+- Lint: `bin/dc-run bundle exec rubocop`
+- Security: `bin/dc-run bundle exec brakeman --quiet --no-pager`
+- I18n normalize: `bin/dc-run bin/i18n normalize`
+- I18n health: `bin/dc-run bin/i18n health`
+
+## Docker & Services
+- Up services: `./bin/dc-up`
+- Restart: `./bin/dc-restart`
+- Logs: `./bin/dc-logs`
+
+## Diagrams
+- Render all: `./bin/render_diagrams --force`
+- Render specific: `./bin/render_diagrams events_flow.mmd`
+
+## Rails (Dummy App Context)
+- Console: `bin/dc-run-dummy rails console`
+- Migrate: `bin/dc-run-dummy rails db:migrate`
+
+## Notes
+- Always use `bin/dc-run` for commands that need DB/Redis/ES
+- RSpec does not support hyphenated line ranges
+

docs/workshop/checklists/preflight_checklist.md

@@ -0,0 +1,24 @@
+# Preflight Checklist
+
+Use this checklist before attending Module 02.
+
+## System
+- Docker Desktop (or equivalent) installed and running
+- 8 GB RAM free (recommended), 4 CPU cores available (recommended)
+- Git installed; SSH keys configured (optional)
+- Code editor with Markdown and Ruby support
+
+## Repository
+- Clone repository
+- Install pre‑commit hooks (optional)
+- Read `AGENTS.md` command guide and testing rules
+
+## Network & Ports
+- Ensure Elasticsearch, Postgres, Redis default ports are free if used directly
+- Corporate proxies configured (if applicable)
+
+## Quick Verification
+- `./bin/dc-up` starts without errors
+- `bin/dc-run bin/ci` runs and reports spec progress
+- `bin/dc-run bin/i18n health` reports healthy or lists actionable items
+

docs/workshop/facilitator_notes/module_00.md

@@ -0,0 +1,11 @@
+# Facilitator Notes — Module 00 (Orientation) — 20–30 min
+
+Key Points
+- Course map, learning outcomes, expectations, labs, capstone
+- Materials: index, checklist, cheat sheet, diagram map
+- Homework: complete preflight; skim Modules 02–03
+
+Timing
+- 10 min: outcomes + structure
+- 10–20 min: materials tour + Q&A
+

docs/workshop/facilitator_notes/module_01.md

@@ -0,0 +1,11 @@
+# Facilitator Notes — Module 01 (Big Picture Architecture) — 40–60 min
+
+Key Points
+- Services map: web app, jobs, Action Cable, DB/PostGIS, ES, Redis, Active Storage, Email
+- Privacy gates: RBAC, platform privacy, invitation tokens; scope of token access
+- Jumpers: systems docs and diagrams for each domain
+
+Timing
+- 20–30 min: diagram walkthrough
+- 10–15 min: Q&A + map to docs
+

docs/workshop/facilitator_notes/module_02.md

@@ -0,0 +1,12 @@
+# Facilitator Notes — Module 02 (Local Setup) — 40–60 min
+
+Key Points
+- `bin/dc-run` and `bin/dc-run-dummy` patterns
+- Run tests, lint, security, i18n health; common startup issues
+- Logs and Sidekiq basics; verify app page load
+
+Timing
+- 10 min: command patterns
+- 20–30 min: live walkthrough
+- 10–20 min: troubleshooting and Q&A
+

docs/workshop/facilitator_notes/module_03.md

@@ -0,0 +1,11 @@
+# Facilitator Notes — Module 03 (Data & Conventions) — 40–60 min
+
+Key Points
+- Migration helpers (`create_bt_table`, `bt_*`), UUIDs, engine prefixes
+- String enums (human‑readable); validations and associations
+- Request‑first tests for model behavior
+
+Timing
+- 15–20 min: conventions walkthrough
+- 20–30 min: Lab 02 kickoff + support
+

docs/workshop/facilitator_notes/module_04.md

@@ -0,0 +1,11 @@
+# Facilitator Notes — Module 04 (Authorization & Privacy) — 40–60 min
+
+Key Points
+- Pundit policies and scopes; metadata tags for auth in tests
+- Platform privacy modes vs registration mode; event invitation tokens scope
+- Index scope patterns (e.g., events visible via token)
+
+Timing
+- 15–20 min: concepts + examples
+- 20–30 min: Lab 03 kickoff + support
+