diff --git a/docs/diagrams/exports/png/platform_technical_architecture.png b/docs/diagrams/exports/png/platform_technical_architecture.png new file mode 100644 index 000000000..8275f27a0 Binary files /dev/null and b/docs/diagrams/exports/png/platform_technical_architecture.png differ diff --git a/docs/diagrams/exports/svg/platform_technical_architecture.svg b/docs/diagrams/exports/svg/platform_technical_architecture.svg new file mode 100644 index 000000000..4e3cc6a99 --- /dev/null +++ b/docs/diagrams/exports/svg/platform_technical_architecture.svg @@ -0,0 +1 @@ +ExternalDataBackground JobsRails EngineClientHTTP

Browser

Controllers

Views & Stimulus

Policies & RBAC

Models

Sidekiq Workers

Notifications - Noticed

PostgreSQL + PostGIS

Elasticsearch

Redis

Active Storage

Email Service

Geocoding API

Action Cable

 \ No newline at end of file diff --git a/docs/diagrams/source/platform_technical_architecture.mmd b/docs/diagrams/source/platform_technical_architecture.mmd new file mode 100644 index 000000000..d9d4942f7 --- /dev/null +++ b/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 diff --git a/docs/scripts/export_pdfs.sh b/docs/scripts/export_pdfs.sh new file mode 100755 index 000000000..a6aa93dff --- /dev/null +++ b/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." + diff --git a/docs/scripts/render_slides.sh b/docs/scripts/render_slides.sh new file mode 100755 index 000000000..f9390ac39 --- /dev/null +++ b/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" + diff --git a/docs/table_of_contents.md b/docs/table_of_contents.md index 7a9493a95..23ac0abd2 100644 --- a/docs/table_of_contents.md +++ b/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) diff --git a/docs/workshop/capstone/README.md b/docs/workshop/capstone/README.md new file mode 100644 index 000000000..c20b823e3 --- /dev/null +++ b/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 + diff --git a/docs/workshop/capstone/rubric.md b/docs/workshop/capstone/rubric.md new file mode 100644 index 000000000..a9c6164ff --- /dev/null +++ b/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 + diff --git a/docs/workshop/capstone/submission_template.md b/docs/workshop/capstone/submission_template.md new file mode 100644 index 000000000..c5c48f571 --- /dev/null +++ b/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 + diff --git a/docs/workshop/cheat_sheets/commands_cheat_sheet.md b/docs/workshop/cheat_sheets/commands_cheat_sheet.md new file mode 100644 index 000000000..ce61c8c9d --- /dev/null +++ b/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 + diff --git a/docs/workshop/checklists/preflight_checklist.md b/docs/workshop/checklists/preflight_checklist.md new file mode 100644 index 000000000..d8a35962b --- /dev/null +++ b/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 + diff --git a/docs/workshop/facilitator_notes/module_00.md b/docs/workshop/facilitator_notes/module_00.md new file mode 100644 index 000000000..f012595df --- /dev/null +++ b/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 + diff --git a/docs/workshop/facilitator_notes/module_01.md b/docs/workshop/facilitator_notes/module_01.md new file mode 100644 index 000000000..f02b3bdbc --- /dev/null +++ b/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 + diff --git a/docs/workshop/facilitator_notes/module_02.md b/docs/workshop/facilitator_notes/module_02.md new file mode 100644 index 000000000..2466a81b1 --- /dev/null +++ b/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 + diff --git a/docs/workshop/facilitator_notes/module_03.md b/docs/workshop/facilitator_notes/module_03.md new file mode 100644 index 000000000..e44f57021 --- /dev/null +++ b/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 + diff --git a/docs/workshop/facilitator_notes/module_04.md b/docs/workshop/facilitator_notes/module_04.md new file mode 100644 index 000000000..997a7c6e6 --- /dev/null +++ b/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 + diff --git a/docs/workshop/facilitator_notes/module_05.md b/docs/workshop/facilitator_notes/module_05.md new file mode 100644 index 000000000..e87086c82 --- /dev/null +++ b/docs/workshop/facilitator_notes/module_05.md @@ -0,0 +1,11 @@ +# Facilitator Notes — Module 05 (I18n & UI) — 40–60 min + +Key Points +- Mobility translated attributes + ActionText; localized mailers/notifiers +- `i18n-tasks` workflow: normalize, missing, add-missing, health +- Stimulus & Turbo basics; progressive enhancement + +Timing +- 15–20 min: concepts + examples +- 20–30 min: Lab 04 kickoff + support + diff --git a/docs/workshop/facilitator_notes/module_06.md b/docs/workshop/facilitator_notes/module_06.md new file mode 100644 index 000000000..3fe77a841 --- /dev/null +++ b/docs/workshop/facilitator_notes/module_06.md @@ -0,0 +1,11 @@ +# Facilitator Notes — Module 06 (Jobs, Notifications, Search) — 40–60 min + +Key Points +- Sidekiq workers: retries, idempotency, logging; Sidekiq Web UI +- Noticed: Action Cable + mailers, parameterized mailers, localization +- ES basics: indexing, queries, health; stubbing/mocking in tests when needed + +Timing +- 15–20 min: concepts + examples +- 20–30 min: Lab 05 kickoff + support + diff --git a/docs/workshop/facilitator_notes/module_07.md b/docs/workshop/facilitator_notes/module_07.md new file mode 100644 index 000000000..3ac565f76 --- /dev/null +++ b/docs/workshop/facilitator_notes/module_07.md @@ -0,0 +1,11 @@ +# Facilitator Notes — Module 07 (Testing, CI, Security) — 40–60 min + +Key Points +- Request‑first testing; automatic test configuration; metadata tags +- CI‑local runs; lint, Brakeman, bundler‑audit; i18n health +- Controller→request spec conversion patterns + +Timing +- 15–20 min: concepts + examples +- 20–30 min: Lab 06 kickoff + support + diff --git a/docs/workshop/facilitator_notes/module_08.md b/docs/workshop/facilitator_notes/module_08.md new file mode 100644 index 000000000..8895af2a3 --- /dev/null +++ b/docs/workshop/facilitator_notes/module_08.md @@ -0,0 +1,11 @@ +# Facilitator Notes — Module 08 (Deployments & Day‑2 Ops) — 40–60 min + +Key Points +- Dokku deploy model: build, release, health checks; env/secrets +- Provision services: Postgres+PostGIS, Redis, ES; Action Cable/WebSockets +- Day‑2: monitoring/logging, migrations, backups, rollbacks; incident response basics + +Timing +- 15–20 min: concepts + examples +- 20–30 min: Lab 07 kickoff + support + diff --git a/docs/workshop/facilitator_notes_intro_workshop.md b/docs/workshop/facilitator_notes_intro_workshop.md new file mode 100644 index 000000000..c946e75bb --- /dev/null +++ b/docs/workshop/facilitator_notes_intro_workshop.md @@ -0,0 +1,62 @@ +# Facilitator Notes — 3‑Hour Intro Workshop + +Use this as a timeboxed guide for the mixed developer/IT audience. Keep energy high and focus on actionable understanding with clear jump‑offs to deeper modules. + +## Agenda (180 minutes) +- 0:00–0:05 — Welcome, logistics, goals +- 0:05–0:15 — Course map and outcomes (Module 00) +- 0:15–0:55 — Big‑Picture Architecture (Module 01) + - 0:15–0:35 — Diagram walkthrough (services, data flows, privacy gates) + - 0:35–0:55 — Q&A + jumping‑off paths into systems docs +- 0:55–1:30 — Repo & Conventions + Live Local Walkthrough + - 0:55–1:10 — Conventions (enums, migrations, policies, i18n) + - 1:10–1:30 — Start services, run tests, inspect logs/Sidekiq +- 1:30–1:40 — Break +- 1:40–2:10 — Events + Invitations High‑Level Tour + - Show representative flows (models, policies, tokens, notifiers, Stimulus, i18n) +- 2:10–2:35 — Guided Lab: Hello Engine (Lab 01) + - In pairs; facilitator floats for unblockers +- 2:35–2:55 — Wrap‑up & Next Steps + - Preflight checklist homework; skim Module 02/03 +- 2:55–3:00 — Final Q&A / Parking lot + +## Materials Checklist +- Slides or printed agenda +- Links handy: + - Workshop index: `docs/workshop/index.md` + - Big‑Picture diagram: `docs/diagrams/exports/*/platform_technical_architecture.*` + - Commands cheat sheet: `docs/workshop/cheat_sheets/commands_cheat_sheet.md` + - Lab 01: `docs/workshop/labs/lab_01_hello_engine.md` + +## Live Demo Script (suggested) +- Open the TOC and workshop index; frame the course +- Show the big‑picture diagram; emphasize privacy gates and background jobs +- Terminal: + - `./bin/dc-up` + - `bin/dc-run bin/ci` + - `bin/dc-run bin/i18n health` + - `./bin/render_diagrams --force` (if time permits) +- App: + - Load home page; briefly show an event and RSVP buttons + - If available, visit `/sidekiq` as a platform manager + +## Common Pitfalls & Remediations +- Missing `bin/dc-run`: remind that anything touching DB/Redis/ES needs it +- RSpec `-v` confusion: use `--format documentation` for detailed output +- Controller vs request specs: default to request specs in engines +- i18n gaps: run `bin/dc-run bin/i18n add-missing` then translate + +## Backup Plans +- If Docker resources are constrained, demonstrate on facilitator machine and hand out lab steps +- If ES is unavailable, skip ES step and acknowledge it will be covered in Module 06 + +## Discussion Prompts +- Which components matter most for your role (IT vs dev)? +- Where would you add monitoring first in your environment? +- What’s your policy for feature flags and incremental rollout? + +## Homework Reminders +- Complete Preflight Checklist +- Skim Module 02 & 03 +- Optional: try Lab 02 setup and bring questions + diff --git a/docs/workshop/index.md b/docs/workshop/index.md new file mode 100644 index 000000000..043575514 --- /dev/null +++ b/docs/workshop/index.md @@ -0,0 +1,34 @@ +# Community Engine Developer/IT Workshop + +Welcome! This workshop series orients developers and IT operators from local development through production operations with the Community Engine. + +## Audience & Format +- Audience: mixed developers and IT operators +- Format: 8 modules (2–3 hours each) + optional office hours +- Prereqs: Docker Desktop (or compatible), Git, a modern code editor, and basic terminal skills + +## Learning Outcomes +- Run the full stack locally with Docker, and validate services +- Understand the architecture: web, jobs, search, storage, privacy/policies +- Build and test features using the project’s TDD patterns +- Internationalize UI, deliver notifications, and index/search content +- Deploy to Dokku, operate day‑2 tasks (monitoring, backups, incidents) + +## Structure +- Modules: overview lectures + guided demos + labs +- Labs: bite‑sized tasks to apply concepts +- Checklists: preflight, deployment, and incident response +- Cheat sheets: commands, testing, i18n, Docker + +## Quick Links +- Checklist: Preflight Environment — ./checklists/preflight_checklist.md +- Cheat Sheet: Commands — ./cheat_sheets/commands_cheat_sheet.md +- Lab 01: Hello Engine — ./labs/lab_01_hello_engine.md +- Big‑Picture Diagram — ../diagrams/source/platform_technical_architecture.mmd + +## Modules +- Module 00: Orientation — ./module_00_orientation.md +- Module 01: Big Picture Architecture — ./module_01_big_picture_architecture.md +- Module 02: Local Setup (Docker) — ./module_02_local_setup.md +- Modules 03–08: See syllabus in Module 00 + diff --git a/docs/workshop/intro_agenda_printable.md b/docs/workshop/intro_agenda_printable.md new file mode 100644 index 000000000..78ee063f3 --- /dev/null +++ b/docs/workshop/intro_agenda_printable.md @@ -0,0 +1,32 @@ +# Intro Workshop Agenda (Printable, 1 Page) + +Audience: Developers + IT | Duration: 3 hours (180 minutes) + +- Welcome & Goals (5 min) + - Introductions, objectives, housekeeping + +- Course Map & Outcomes (10 min) + - Modules, labs, capstone, support/office hours + +- Big‑Picture Architecture (40 min) + - Core services: Rails app, jobs, Action Cable, DB/PostGIS, ES, Redis, Storage, Email + - Privacy & authorization gates (RBAC, platform privacy, invitation tokens) + - Jumping‑off docs and diagrams + +- Repo Conventions & Live Local Walkthrough (35 min) + - Conventions: string enums, migrations, Pundit, i18n, request‑first tests + - Start stack, run tests, scan i18n health; quick Sidekiq peek + +- Break (10 min) + +- Events + Invitations Overview (30 min) + - Representative end‑to‑end flow (models, policies, tokens, notifiers, UI) + - Where to dig deeper in modules + +- Guided Lab: Hello Engine (25 min) + - Run core commands; verify setup; render diagrams + +- Wrap‑Up & Next Steps (20 min) + - Preflight homework; Module 02–03 previews; Q&A + +Print Tips: Use “Fit to page” and standard margins. Avoid color-heavy backgrounds. diff --git a/docs/workshop/intro_slides_outline.md b/docs/workshop/intro_slides_outline.md new file mode 100644 index 000000000..18a497871 --- /dev/null +++ b/docs/workshop/intro_slides_outline.md @@ -0,0 +1,33 @@ +# Intro Workshop — Slide Outline + +Use this outline to prepare slides. Each bullet approximates one slide. + +1. Title — Community Engine Intro Workshop + - Audience, duration, goals +2. Course Map & Outcomes + - Modules, labs, capstone, support +3. Architecture Overview (1) + - High‑level services diagram (Platform Technical Architecture) +4. Architecture Overview (2) + - Privacy & authorization gates (RBAC, platform privacy, invitation tokens) +5. Repo Tour & Conventions (1) + - Rails engine layout; concerns; string enums +6. Repo Tour & Conventions (2) + - Testing defaults (request‑first), i18n norms, security practices +7. Live Local Walkthrough + - Start services; run tests; i18n health; Sidekiq +8. Events + Invitations Thread (1) + - Models & policies +9. Events + Invitations Thread (2) + - Tokens, notifications, Stimulus views +10. Lab 01 — Hello Engine + - Objectives and steps +11. Next Steps & Homework + - Preflight checklist; read ahead Modules 02–03 +12. Q&A / Contact + - Office hours; support channels + +Notes: +- Keep slides uncluttered; favor diagrams and command snippets +- Link to docs: workshop index, cheat sheets, lab 01, big‑picture diagram + diff --git a/docs/workshop/labs/lab_01_hello_engine.md b/docs/workshop/labs/lab_01_hello_engine.md new file mode 100644 index 000000000..510076bab --- /dev/null +++ b/docs/workshop/labs/lab_01_hello_engine.md @@ -0,0 +1,20 @@ +# Lab 01 — Hello Engine + +A short lab to verify your environment and get familiar with core commands. + +## Objectives +- Verify services start and tests run +- Render diagrams once to ensure tooling works + +## Steps +1. Start services: `./bin/dc-up` +2. Run test suite: `bin/dc-run bin/ci` +3. Check lint/security: `bin/dc-run bundle exec rubocop`; `bin/dc-run bundle exec brakeman --quiet --no-pager` +4. i18n health: `bin/dc-run bin/i18n health` +5. Render diagrams: `./bin/render_diagrams --force` + +## Expected Results +- Tests run without infrastructure connection errors +- i18n health reports OK or actionable missing keys +- Diagram exports present in `docs/diagrams/exports/{png,svg}` + diff --git a/docs/workshop/labs/lab_02_model_and_migration.md b/docs/workshop/labs/lab_02_model_and_migration.md new file mode 100644 index 000000000..f0114873d --- /dev/null +++ b/docs/workshop/labs/lab_02_model_and_migration.md @@ -0,0 +1,26 @@ +# Lab 02 — Model + Migration with Tests + +Create a simple model using migration helpers, add string enums, and write request‑first tests. + +## Objectives +- Create a `create_bt_table` migration using helpers +- Define a string enum on the model +- Write a request spec to exercise basic create/show + +## Steps +1. Generate migration and model skeleton (manual or via Rails generator inside dc‑run) +2. In the migration: + - Use `create_bt_table :example_items` block + - Add `t.string :status, default: "pending"` + - Add `t.bt_references :person, null: false` +3. In the model: + - `enum :status, { pending: "pending", active: "active" }` + - Validations for required fields +4. Write a request spec for `POST /example_items` and `GET /example_items/:id` +5. Run tests: `bin/dc-run bin/ci` (or targeted rspec command) + +## Tips +- Follow naming and engine prefix conventions in routes/controllers +- Prefer request specs over controller specs to avoid engine routing pitfalls +- Add missing translations with `bin/dc-run bin/i18n add-missing` + diff --git a/docs/workshop/labs/lab_03_policy_and_token_access.md b/docs/workshop/labs/lab_03_policy_and_token_access.md new file mode 100644 index 000000000..77ff37bb5 --- /dev/null +++ b/docs/workshop/labs/lab_03_policy_and_token_access.md @@ -0,0 +1,23 @@ +# Lab 03 — Policy & Token Access + +Practice adding an authorization rule and verifying event access via an invitation token. + +## Objectives +- Update or add a Pundit policy rule +- Verify token‑scoped access to a private event +- Exercise policy scope to include events visible via token + +## Steps +1. Identify a read rule to tighten (e.g., restrict show without token) +2. Update the corresponding policy and scope +3. Create a pending `EventInvitation` in a spec and pass its token as a param +4. Write a request spec asserting: + - Without token: 302 to sign‑in or 404 (depending on platform privacy) + - With valid token: 200 OK and content present +5. Run tests: `bin/dc-run bin/ci` + +## Tips +- Use request specs so engine routing and privacy hooks are exercised +- Reuse factories for Person, Event, and EventInvitation if available +- Review `EventsController` privacy override for token handling + diff --git a/docs/workshop/labs/lab_04_i18n_add_strings_and_health.md b/docs/workshop/labs/lab_04_i18n_add_strings_and_health.md new file mode 100644 index 000000000..3df357351 --- /dev/null +++ b/docs/workshop/labs/lab_04_i18n_add_strings_and_health.md @@ -0,0 +1,24 @@ +# Lab 04 — I18n: Add Strings & Health + +Add new localized strings to a view and a notifier/mailer, then validate coverage. + +## Objectives +- Add a new user‑facing string in a view and ensure it’s localized in all supported locales +- Localize a notifier/mailer title/body/subject and verify delivery strings +- Run `i18n-tasks` to normalize and ensure health across locales + +## Steps +1. Identify a view or partial with hard‑coded text and replace with `t('...')` key(s) +2. Add keys to `config/locales/en.yml`, then run: + - `bin/dc-run bin/i18n add-missing` + - `bin/dc-run bin/i18n normalize` + - `bin/dc-run bin/i18n health` +3. Mirror English strings to other locales (fr, es, etc.) so health passes +4. Update a notifier or mailer (e.g., EventInvitationNotifier/Mailer) to ensure title/body/subject use `I18n.t` +5. Run tests: `bin/dc-run bin/ci` + +## Tips +- Prefer existing namespaces and keep key names descriptive +- Ensure interpolation variables are covered in translations +- If ActionText rich text is involved, sanitize and test plain‑text fallbacks where needed + diff --git a/docs/workshop/labs/lab_05_notifier_and_job_with_es_query.md b/docs/workshop/labs/lab_05_notifier_and_job_with_es_query.md new file mode 100644 index 000000000..97f13bcc4 --- /dev/null +++ b/docs/workshop/labs/lab_05_notifier_and_job_with_es_query.md @@ -0,0 +1,31 @@ +# Lab 05 — Notifier + Job + ES Query + +Add a small notifier and job, then run a simple ES query to validate changes. + +## Objectives +- Implement or adjust a Noticed notifier delivering via Action Cable and email +- Write a Sidekiq job that enqueues based on a simple rule and logs outcomes +- Verify an ES query against indexed content + +## Steps +1. Notifier: + - Create/modify a notifier to set a localized title/body and a URL + - Ensure `deliver_by :email` uses a parameterized mailer with localized subject + - Add a minimal notification view partial if needed +2. Job: + - Add a worker that finds records meeting a simple condition (e.g., events starting soon) + - Enqueue the notifier for matching recipients; handle/ log failures + - Make job idempotent where practical +3. ES Query: + - Choose a searchable model; add or use an indexed field + - Issue a simple query and validate expected hit(s) +4. Tests: + - Add specs for notifier params and job behavior + - If ES is mocked, use a stubbed client or scoped query expectations +5. Run: `bin/dc-run bin/ci` + +## Tips +- Use existing event reminder jobs/notifiers as references +- Keep Sidekiq logs readable; prefer structured context in log messages +- For ES, keep queries minimal in tests or stub as appropriate + diff --git a/docs/workshop/labs/lab_06_controller_to_request_spec.md b/docs/workshop/labs/lab_06_controller_to_request_spec.md new file mode 100644 index 000000000..e9ee03014 --- /dev/null +++ b/docs/workshop/labs/lab_06_controller_to_request_spec.md @@ -0,0 +1,25 @@ +# Lab 06 — Controller → Request Spec Conversion + +Convert a brittle controller spec into a robust request spec aligned with engine routing. + +## Objectives +- Replace a controller spec with an equivalent request spec +- Use automatic host setup and auth metadata +- Fix path helper assertions that break under engine isolation + +## Steps +1. Pick a controller spec that exercises an engine controller action (or create a minimal one). +2. Create a new request spec mirroring the scenarios; add metadata like `:as_user` or `:as_platform_manager`. +3. Replace direct controller calls with HTTP verbs: + - `get better_together.some_path(params: { locale: I18n.default_locale })` +4. Assertions: + - Prefer `expect(response).to have_http_status(:ok)` and `include('/expected/path')` for redirects + - Avoid direct path helper comparisons in controller specs +5. Remove or mark the old controller spec pending; keep only the request spec. +6. Run: `bin/dc-run bin/ci` (or focus the file). + +## Tips +- Engine route names include the engine namespace (e.g., `better_together.*_path`). +- Automatic test configuration often sets up host platform and login when metadata is present. +- For redirects, compare `response.location` with `include('/resource')` instead of helper equality. + diff --git a/docs/workshop/labs/lab_07_dokku_deploy_and_rollback.md b/docs/workshop/labs/lab_07_dokku_deploy_and_rollback.md new file mode 100644 index 000000000..b05dd947e --- /dev/null +++ b/docs/workshop/labs/lab_07_dokku_deploy_and_rollback.md @@ -0,0 +1,38 @@ +# Lab 07 — Dokku Deploy + Rollback Runbook + +Draft and execute a lightweight runbook for deploying and rolling back a release on Dokku. + +## Objectives +- Configure app env and services +- Deploy a tagged release and verify health +- Perform a rollback using release history + +## Prerequisites +- Dokku server with Postgres+PostGIS, Redis, and Elasticsearch services available +- App created on Dokku and DNS/SSL configured + +## Runbook (Template) +1. Prepare + - Set env: `dokku config:set APP_NAME RAILS_ENV=production RACK_ENV=production` and secrets (DB URL, REDIS URL, ES URL, SMTP) + - Link services: `dokku postgres:link`, `dokku redis:link`, `dokku elasticsearch:link` +2. Deploy + - Push: `git push dokku main:master` or `git push dokku :master` + - Verify logs: `dokku logs APP_NAME -t` + - Check `/health` (if available) and homepage + - Verify `/sidekiq` as a platform manager +3. Migrate + - Run migration task: `dokku run APP_NAME bin/rails db:migrate` + - Confirm schema version +4. Rollback + - List releases: `dokku releases:list APP_NAME` + - Rollback: `dokku releases:deploy APP_NAME ` + - Verify app health and logs post‑rollback +5. Post‑deploy + - Watch Sidekiq queues and error rates for 15–30 minutes + - Update runbook with any deviations + +## Notes +- Ensure Action Cable/WebSocket proxy settings and timeouts are configured +- For ES snapshots, consult your ES plugin/cluster docs +- Keep secrets out of VCS; use `dokku config:set` or a secrets manager + diff --git a/docs/workshop/module_00_orientation.md b/docs/workshop/module_00_orientation.md new file mode 100644 index 000000000..29e9bf384 --- /dev/null +++ b/docs/workshop/module_00_orientation.md @@ -0,0 +1,35 @@ +# Module 00 — Orientation & Outcomes + +This module introduces the course goals, logistics, and how to use the workshop materials. + +## Goals +- Understand the overall course path and expected outcomes +- Learn how the workshop content is organized (modules, labs, checklists, cheat sheets) +- Prepare your environment using the preflight checklist + +## Syllabus (8 Weeks) +1. Orientation + Architecture (this week) +2. Local Dev Environment (Docker, services, smoke tests) +3. Data & Conventions (migrations, enums, concerns) +4. Authorization & Privacy (policies, RBAC, platform privacy & tokens) +5. I18n & UI (Mobility, ActionText, Stimulus) +6. Jobs, Notifications, Search (Sidekiq, Noticed, ES) +7. Testing, CI, Security (request‑first, lint, security checks) +8. Deployments & Day‑2 Ops (Dokku, backups, monitoring, incidents) + +## Expectations +- Time per session: 2–3 hours + optional office hours +- Weekly labs: small tasks to reinforce learning +- Capstone: small end‑to‑end feature (Weeks 6–8) + +## Materials +- Preflight Checklist — ../workshop/checklists/preflight_checklist.md +- Command Cheat Sheet — ../workshop/cheat_sheets/commands_cheat_sheet.md +- Diagrams — ../diagrams/source/ +- Table of Contents — ../table_of_contents.md + +## Homework (Before Module 02) +- Complete Preflight Checklist +- Clone repo; review `AGENTS.md` for commands & testing patterns +- Skim Events & Invitations docs for system overview + diff --git a/docs/workshop/module_01_big_picture_architecture.md b/docs/workshop/module_01_big_picture_architecture.md new file mode 100644 index 000000000..d6b2d98f7 --- /dev/null +++ b/docs/workshop/module_01_big_picture_architecture.md @@ -0,0 +1,32 @@ +# Module 01 — Big Picture Architecture + +This module introduces the platform’s high‑level architecture and provides jumping‑off points into domain systems. + +## Objectives +- Understand major components: web app, background jobs, Action Cable, search (ES), DB/PostGIS, storage, email +- Learn high‑level data flows and where privacy/authorization gates apply +- Know where to find deep‑dives and diagrams + +## Diagram: Platform Technical Architecture + +```mermaid +%% See editable source at: ../diagrams/source/platform_technical_architecture.mmd +``` + +**Diagram Files:** +- Source: ../diagrams/source/platform_technical_architecture.mmd +- PNG: ../diagrams/exports/png/platform_technical_architecture.png +- SVG: ../diagrams/exports/svg/platform_technical_architecture.svg + +## Jumping‑Off Points +- Systems overview: ../developers/systems/ +- Roles & permissions: ../shared/roles_and_permissions.md +- Production guides: ../production/ +- Notifications: ../developers/systems/notifications_system.md +- Events & Invitations: ../developers/systems/event_invitations_and_attendance.md + +## Discussion Prompts +- Where do tokens (platform vs event) alter access paths? +- What failure modes impact jobs vs requests (and how to monitor)? +- What belongs in request specs vs background job specs? + diff --git a/docs/workshop/module_02_local_setup.md b/docs/workshop/module_02_local_setup.md new file mode 100644 index 000000000..01b0a9180 --- /dev/null +++ b/docs/workshop/module_02_local_setup.md @@ -0,0 +1,28 @@ +# Module 02 — Local Setup (Docker) + +This module sets up the local environment, runs smoke tests, and covers required run patterns. + +## Objectives +- Start the full stack using project scripts +- Run tests, linting, and i18n tooling +- Know when to use `bin/dc-run` vs `bin/dc-run-dummy` + +## Steps +1. Verify prerequisites from the Preflight Checklist +2. Start services: `./bin/dc-up` (and `./bin/dc-restart` as needed) +3. Run tests: `bin/dc-run bin/ci` +4. Lint: `bin/dc-run bundle exec rubocop` +5. Security: `bin/dc-run bundle exec brakeman --quiet --no-pager` +6. i18n: `bin/dc-run bin/i18n all` +7. Open the app, confirm home page loads + +## Patterns +- Always wrap service-dependent commands with `bin/dc-run` +- Use `bin/dc-run-dummy` for dummy app Rails commands (migrations/console in test app) +- Prefer request specs; avoid controller specs unless necessary + +## Troubleshooting +- Services won’t start: check Docker resources and port conflicts +- Tests can’t reach DB/ES: ensure use of `bin/dc-run` +- Missing translations: run `bin/dc-run bin/i18n add-missing` + diff --git a/docs/workshop/module_03_data_and_conventions.md b/docs/workshop/module_03_data_and_conventions.md new file mode 100644 index 000000000..51dcb36ad --- /dev/null +++ b/docs/workshop/module_03_data_and_conventions.md @@ -0,0 +1,25 @@ +# Module 03 — Data & Conventions + +This module introduces project data conventions and patterns that keep the schema consistent and readable. + +## Objectives +- Use Better Together migration helpers (`create_bt_table`, `bt_*` column helpers) +- Apply string enums for human‑readable states +- Follow naming, UUIDs, and association conventions +- Write request‑first tests for model behavior + +## Key Conventions +- Migrations: always use helpers from `lib/better_together/` (see AGENTS.md Migration Standards) +- Primary keys: UUID by default via `create_bt_table` +- Associations: use `bt_references` for foreign keys; maintain engine prefixing +- Enums: string enums only (never integers) with full English words +- I18n: user‑facing strings live in locale files; models support translations where applicable + +## Reading List +- `AGENTS.md` → Migration Standards, String Enum Design Standards +- `docs/developers/systems/models_and_concerns.md` (if present) and relevant system docs +- `docs/diagrams/source/*_schema_erd.mmd` diagrams (events/content/etc.) + +## Hands‑On Lab +- Lab 02 — Model + Migration with Tests: `./labs/lab_02_model_and_migration.md` + diff --git a/docs/workshop/module_04_authorization_and_privacy.md b/docs/workshop/module_04_authorization_and_privacy.md new file mode 100644 index 000000000..606ff4147 --- /dev/null +++ b/docs/workshop/module_04_authorization_and_privacy.md @@ -0,0 +1,24 @@ +# Module 04 — Authorization & Privacy + +Understand role‑based access control, policies, platform privacy, and invitation tokens. + +## Objectives +- Apply Pundit policies and scopes consistently +- Understand platform privacy modes and their effects +- Use event invitation tokens to grant scoped access +- Test authorization paths via request specs + +## Topics +- Roles & permissions model; policy gates per action +- Platform privacy: public vs invite‑only; registration modes +- Event invitation tokens vs platform invitation codes +- Policy scopes for index listings (e.g., events with token access) + +## Reading List +- `docs/shared/roles_and_permissions.md` +- `docs/platform_organizers/host_management.md` (Privacy & Invitation Tokens section) +- `docs/developers/systems/event_invitations_and_attendance.md` + +## Hands‑On Lab +- Lab 03 — Policy & Token Access: `./labs/lab_03_policy_and_token_access.md` + diff --git a/docs/workshop/module_05_i18n_and_ui.md b/docs/workshop/module_05_i18n_and_ui.md new file mode 100644 index 000000000..439051409 --- /dev/null +++ b/docs/workshop/module_05_i18n_and_ui.md @@ -0,0 +1,31 @@ +# Module 05 — I18n & UI (Mobility, ActionText, Stimulus) + +This module focuses on internationalization (i18n) and the UI layer (ERB, Turbo partials, Stimulus). + +## Objectives +- Use Mobility + ActionText for translatable content +- Maintain locale coverage with `i18n-tasks` +- Apply UI conventions with Stimulus controllers and progressive enhancement +- Ensure user‑facing strings are fully localized + +## Topics +- Mobility basics: translated attributes and rich text fields +- i18n workflow: normalize, missing, add‑missing, health +- Views: ERB + partials, Turbo‑stream responses for small interactions +- Stimulus: targets/actions, unobtrusive behavior binding; safe DOM updates +- Email and Noticed templates: localized titles/bodies/subjects + +## Commands +- Normalize: `bin/dc-run bin/i18n normalize` +- Find missing: `bin/dc-run bin/i18n missing` +- Add missing: `bin/dc-run bin/i18n add-missing` +- Health: `bin/dc-run bin/i18n health` + +## Reading List +- `AGENTS.md` → Translations & Locales, Translation Normalization & Coverage +- `docs/developers/systems/i18n_mobility_localization_system.md` +- Example: invitation notifiers/mailers for localized copy + +## Hands‑On Lab +- Lab 04 — I18n: Add Strings & Health — `./labs/lab_04_i18n_add_strings_and_health.md` + diff --git a/docs/workshop/module_06_jobs_notifications_search.md b/docs/workshop/module_06_jobs_notifications_search.md new file mode 100644 index 000000000..5abb16ba9 --- /dev/null +++ b/docs/workshop/module_06_jobs_notifications_search.md @@ -0,0 +1,29 @@ +# Module 06 — Jobs, Notifications, Search + +Background processing with Sidekiq, user notifications with Noticed (Action Cable + Email), and Elasticsearch basics. + +## Objectives +- Create and schedule robust background jobs +- Deliver localized notifications via Noticed (in‑app + email) +- Understand Elasticsearch indexing and querying basics +- Add tests for jobs, notifiers, and ES queries + +## Topics +- Sidekiq workers, retries, idempotency, and logging +- Noticed notifications: channels, parameterized mailers, Action Cable feeds +- Elasticsearch lifecycle: indexing hooks, query patterns, health checks +- Observability: Sidekiq Web UI, logs, and failure triage + +## Commands +- Jobs: use app logs and Sidekiq UI (`/sidekiq`) while authenticated as a platform manager +- Mailers: inspect logs/test delivery adapters +- ES health: curl or Rails console snippets if permitted in your environment + +## Reading List +- `docs/developers/systems/notifications_system.md` +- Event reminder/update notifiers and jobs in the codebase +- `docs/developers/systems/*` search‑related docs (if present) + +## Hands‑On Lab +- Lab 05 — Notifier + Job + ES Query — `./labs/lab_05_notifier_and_job_with_es_query.md` + diff --git a/docs/workshop/module_07_testing_ci_security.md b/docs/workshop/module_07_testing_ci_security.md new file mode 100644 index 000000000..00ba69afe --- /dev/null +++ b/docs/workshop/module_07_testing_ci_security.md @@ -0,0 +1,36 @@ +# Module 07 — Testing, CI, Security + +Request‑first testing, CI habits, and security hygiene to keep changes safe and verifiable. + +## Objectives +- Prefer request specs for controller behavior in an engine +- Use automatic test configuration helpers and metadata tags +- Run CI-equivalent locally with project scripts +- Enforce linting and application security checks pre‑merge + +## Testing Patterns +- Request specs exercise full engine routing and privacy hooks; avoid controller specs unless necessary. +- Use automatic configuration helpers (see `spec/support/automatic_test_configuration.rb`) and metadata tags: + - `:as_platform_manager`, `:as_user`, `:no_auth`, `:skip_host_setup` +- When a controller spec is unavoidable, avoid URL helpers in assertions (use string includes) and configure URL helpers explicitly. + +## Commands +- Full suite: `bin/dc-run bin/ci` +- Focused spec: `bin/dc-run bundle exec rspec spec/path/to/file_spec.rb` +- Line focus: `bin/dc-run bundle exec rspec spec/path/to/file_spec.rb:123` +- Verbose descriptions: `--format documentation` (do not use `-v` which shows rspec version) + +## CI & Quality Gates +- Lint: `bin/dc-run bundle exec rubocop` +- Security (code): `bin/dc-run bundle exec brakeman --quiet --no-pager` +- Security (deps): `bin/dc-run bundle exec bundler-audit --update` +- i18n: `bin/dc-run bin/i18n all` + +## Reading List +- `AGENTS.md` → Testing Requirements, Commands, Security Requirements +- `spec/support/automatic_test_configuration.rb` → automatic host setup and auth +- Testing architecture notes in `AGENTS.md` (Request vs Controller Specs) + +## Hands‑On Lab +- Lab 06 — Controller → Request Spec Conversion — `./labs/lab_06_controller_to_request_spec.md` + diff --git a/docs/workshop/module_08_deployments_and_day2_ops.md b/docs/workshop/module_08_deployments_and_day2_ops.md new file mode 100644 index 000000000..2ac9f01ae --- /dev/null +++ b/docs/workshop/module_08_deployments_and_day2_ops.md @@ -0,0 +1,29 @@ +# Module 08 — Deployments & Day‑2 Ops (Dokku) + +Deploy with confidence and operate the platform: secrets, services, monitoring, backups, and incident response. + +## Objectives +- Prepare and deploy to Dokku (or similar PaaS) +- Configure secrets/env, DB/PostGIS, Redis, Elasticsearch, Sidekiq, Action Cable +- Operate day‑2: monitoring/logs, migrations, rollbacks, backups/restores + +## Deploy Concepts +- Build & release: container build or buildpacks; release health checks +- App config: `DOKKU_CONFIG`/env; secrets for DB/Redis/ES/SMTP +- Services: provision Postgres+PostGIS, Redis, and Elasticsearch plugins/services +- Networking: SSL/TLS, WebSockets (Action Cable), ports, proxy timeouts + +## Day‑2 Ops +- Monitoring: Sidekiq Web UI (`/sidekiq`), app logs, error trackers (if configured) +- Migrations: run with release tasks; schema backup before risky changes +- Backups: schedule DB backups; ES snapshots (or export) as needed +- Rollbacks: use platform release history; maintain a runbook + +## Reading List +- `docs/production/*` (Dokku deployment, external services configuration) +- `AGENTS.md` → Docker environment usage, security requirements +- Notifiers/jobs docs for background processing expectations + +## Hands‑On Lab +- Lab 07 — Dokku Deploy + Rollback Runbook — `./labs/lab_07_dokku_deploy_and_rollback.md` + diff --git a/docs/workshop/slides/intro_slides.md b/docs/workshop/slides/intro_slides.md new file mode 100644 index 000000000..5a0fc1bac --- /dev/null +++ b/docs/workshop/slides/intro_slides.md @@ -0,0 +1,68 @@ +# Community Engine — Intro Workshop + +> Audience: Developers + IT ‱ Duration: 3 hours + +--- + +## Course Map & Outcomes + +- Modules, labs, capstone, office hours +- Goal: from local dev → production ops + +--- + +## Architecture Overview + +![Platform Technical Architecture](../../diagrams/exports/png/platform_technical_architecture.png) + +Notes: +- Web app, jobs, Action Cable, DB/PostGIS, ES, Redis, Storage, Email + +--- + +## Privacy & Authorization + +- RBAC (roles/permissions) +- Platform privacy modes +- Invitation tokens (platform vs event) + +--- + +## Repo & Conventions + +- Rails engine layout; concerns +- String enums; migration helpers +- Request‑first testing; i18n rules + +--- + +## Live Local Walkthrough + +- `./bin/dc-up` +- `bin/dc-run bin/ci` +- `bin/dc-run bin/i18n health` +- Sidekiq Web UI + +--- + +## Events + Invitations (Thread) + +- Models, policies, tokens +- Notifiers + mailers +- Stimulus UI & Turbo + +--- + +## Lab 01 — Hello Engine + +- Verify services and tests +- Render diagrams + +--- + +## Next Steps & Homework + +- Preflight checklist +- Skim Modules 02–03 +- Optional: start Lab 02 + diff --git a/docs/workshop/slides/module_00.md b/docs/workshop/slides/module_00.md new file mode 100644 index 000000000..8abbbe89f --- /dev/null +++ b/docs/workshop/slides/module_00.md @@ -0,0 +1,36 @@ +# Module 00 — Orientation + +> Duration: 20–30 minutes + +--- + +## Outcomes + +- Understand course map and learning goals +- Know how to use modules, labs, checklists, cheat sheets +- Complete preflight before Module 02 + +--- + +## Agenda + +- Course map and expectations +- Materials overview (index, checklist, cheat sheet) +- Q&A + +--- + +## Materials + +- Workshop Index: `docs/workshop/index.md` +- Preflight Checklist: `docs/workshop/checklists/preflight_checklist.md` +- Commands Cheat Sheet: `docs/workshop/cheat_sheets/commands_cheat_sheet.md` + +--- + +## Next Steps + +- Complete preflight +- Skim Module 02 and 03 +- Optional: preview Lab 02 + diff --git a/docs/workshop/slides/module_01.md b/docs/workshop/slides/module_01.md new file mode 100644 index 000000000..be9351c9d --- /dev/null +++ b/docs/workshop/slides/module_01.md @@ -0,0 +1,37 @@ +# Module 01 — Big Picture Architecture + +> Duration: 40–60 minutes + +--- + +## Objectives + +- Understand platform services and data flows +- Recognize privacy/authorization gates +- Know where to find system deep‑dives + +--- + +## Architecture Diagram + +![Platform Technical Architecture](../../diagrams/exports/png/platform_technical_architecture.png) + +Notes: +- Web app, jobs, Action Cable, DB/PostGIS, ES, Redis, Storage, Email + +--- + +## Privacy & Authorization + +- RBAC roles/permissions +- Platform privacy modes +- Invitation tokens (event vs platform) + +--- + +## Resources + +- Systems: `docs/developers/systems/` +- Roles & Permissions: `docs/shared/roles_and_permissions.md` +- Production: `docs/production/` + diff --git a/docs/workshop/slides/module_02.md b/docs/workshop/slides/module_02.md new file mode 100644 index 000000000..f1d980dab --- /dev/null +++ b/docs/workshop/slides/module_02.md @@ -0,0 +1,30 @@ +# Module 02 — Local Setup (Docker) + +> Duration: 40–60 minutes + +--- + +## Objectives + +- Start full stack using project scripts +- Run tests, linting, security, i18n tools +- Understand `bin/dc-run` vs `bin/dc-run-dummy` + +--- + +## Commands + +- `./bin/dc-up` +- `bin/dc-run bin/ci` +- `bin/dc-run bundle exec rubocop` +- `bin/dc-run bundle exec brakeman --quiet --no-pager` +- `bin/dc-run bin/i18n all` + +--- + +## Troubleshooting + +- Docker resources and port conflicts +- Use `bin/dc-run` for DB/Redis/ES tasks +- Add missing translations then re-run health + diff --git a/docs/workshop/slides/module_03.md b/docs/workshop/slides/module_03.md new file mode 100644 index 000000000..e9b4933cf --- /dev/null +++ b/docs/workshop/slides/module_03.md @@ -0,0 +1,29 @@ +# Module 03 — Data & Conventions + +> Duration: 40–60 minutes + +--- + +## Key Conventions + +- Migration helpers: `create_bt_table`, `bt_*`, UUIDs, engine prefixes +- String enums with full words (never ints) +- Associations with `bt_references` +- Request‑first tests for model behavior + +--- + +## Lab 02 — Model + Migration + +- Create table via helpers +- Add string enum +- Write a request spec +- Run: `bin/dc-run bin/ci` + +--- + +## Resources + +- AGENTS.md: Migration & Enum Standards +- Schema ERDs: `docs/diagrams/source/*_schema_erd.mmd` + diff --git a/docs/workshop/slides/module_04.md b/docs/workshop/slides/module_04.md new file mode 100644 index 000000000..ddfe02766 --- /dev/null +++ b/docs/workshop/slides/module_04.md @@ -0,0 +1,27 @@ +# Module 04 — Authorization & Privacy + +> Duration: 40–60 minutes + +--- + +## Topics + +- Pundit policies & scopes; metadata tags in tests +- Platform privacy vs registration; event invitation tokens +- Index scopes that honor token access + +--- + +## Lab 03 — Policy & Token Access + +- Tighten read rule; update scope +- Create pending EventInvitation in spec; pass token +- Assert 302/404 without token; 200 with valid token + +--- + +## Resources + +- Roles & Permissions: `docs/shared/roles_and_permissions.md` +- Host Management (privacy): `docs/platform_organizers/host_management.md` + diff --git a/docs/workshop/slides/module_05.md b/docs/workshop/slides/module_05.md new file mode 100644 index 000000000..af4b85001 --- /dev/null +++ b/docs/workshop/slides/module_05.md @@ -0,0 +1,28 @@ +# Module 05 — I18n & UI + +> Duration: 40–60 minutes + +--- + +## Topics + +- Mobility translated attributes + ActionText +- i18n tasks: normalize, missing, add-missing, health +- Stimulus & Turbo; progressive enhancement +- Localized mailers & notifiers + +--- + +## Lab 04 — I18n Add Strings & Health + +- Replace hard-coded strings with `t()` +- Add keys, run add-missing/normalize/health +- Update other locales; rerun health + +--- + +## Resources + +- I18n System: `docs/developers/systems/i18n_mobility_localization_system.md` +- AGENTS.md: Translations & Locales + diff --git a/docs/workshop/slides/module_06.md b/docs/workshop/slides/module_06.md new file mode 100644 index 000000000..ef107f8f2 --- /dev/null +++ b/docs/workshop/slides/module_06.md @@ -0,0 +1,27 @@ +# Module 06 — Jobs, Notifications, Search + +> Duration: 40–60 minutes + +--- + +## Topics + +- Sidekiq workers: retries, idempotency, logging +- Noticed: Action Cable + mailers; parameterized mailers +- Elasticsearch: indexing & queries; health checks + +--- + +## Lab 05 — Notifier + Job + ES Query + +- Implement notifier with localized title/body & URL +- Write job that triggers notifier; log outcomes +- Verify a simple ES query + +--- + +## Resources + +- Notifications System: `docs/developers/systems/notifications_system.md` +- Event jobs/notifiers in codebase + diff --git a/docs/workshop/slides/module_07.md b/docs/workshop/slides/module_07.md new file mode 100644 index 000000000..5c3b64536 --- /dev/null +++ b/docs/workshop/slides/module_07.md @@ -0,0 +1,27 @@ +# Module 07 — Testing, CI, Security + +> Duration: 40–60 minutes + +--- + +## Patterns + +- Request‑first specs; automatic test configuration; metadata tags +- CI-local: `bin/dc-run bin/ci` ; lint/security/i18n gates +- Controller→request spec migration tips + +--- + +## Lab 06 — Controller → Request Spec + +- Create request spec mirroring scenarios +- Use metadata for auth/host setup +- Prefer status expectations and string includes for redirects + +--- + +## Resources + +- AGENTS.md: Testing Requirements & patterns +- `spec/support/automatic_test_configuration.rb` + diff --git a/docs/workshop/slides/module_08.md b/docs/workshop/slides/module_08.md new file mode 100644 index 000000000..edfbd884d --- /dev/null +++ b/docs/workshop/slides/module_08.md @@ -0,0 +1,35 @@ +# Module 08 — Deployments & Day‑2 Ops (Dokku) + +> Duration: 40–60 minutes + +--- + +## Deploy Concepts + +- Build & release model; health checks +- Env/secrets; services: Postgres+PostGIS, Redis, ES +- Action Cable/WebSockets; proxy timeouts + +--- + +## Day‑2 Ops + +- Monitoring/logging; Sidekiq Web UI +- Migrations and backup plans +- Rollbacks and incident response basics + +--- + +## Lab 07 — Deploy + Rollback Runbook + +- Configure env and link services +- Deploy tag; verify health +- Roll back to previous release; confirm recovery + +--- + +## Resources + +- Production docs: `docs/production/` +- Lab runbook: `docs/workshop/labs/lab_07_dokku_deploy_and_rollback.md` +