Add workshop materials and technical architecture diagram

- Introduced a new technical architecture diagram for the platform in Mermaid format.
- Expanded the table of contents to include a comprehensive workshop section with modules, labs, and checklists.
- Created multiple lab documents covering various topics such as model creation, authorization, internationalization, and background jobs.
- Added a commands cheat sheet for quick reference during workshops.
- Developed a preflight checklist to ensure participants are prepared before the workshop.
- Structured workshop modules to guide participants through local setup, data conventions, authorization, and more.

Author: rsmithlal

docs/diagrams/exports/png/platform_technical_architecture.png

@@ -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/diagrams/exports/svg/platform_technical_architecture.svg

@@ -102,6 +102,23 @@ 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
+- [🧭 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)
+- [✅ 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)
+
 ##### **Diagram Sources** - [`diagrams/source/`](diagrams/source/)
 *Mermaid (.mmd) source files*
 - [👤 Accounts Flow](diagrams/source/accounts_flow.mmd)

docs/diagrams/source/platform_technical_architecture.mmd

@@ -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/table_of_contents.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/cheat_sheets/commands_cheat_sheet.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
+

docs/workshop/checklists/preflight_checklist.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}`
+

docs/workshop/index.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`
+

docs/workshop/labs/lab_01_hello_engine.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
+