diff --git a/mkdocs/DOCS_NEXT_STEPS.md b/mkdocs/DOCS_NEXT_STEPS.md
new file mode 100644
index 00000000..6b0547c6
--- /dev/null
+++ b/mkdocs/DOCS_NEXT_STEPS.md
@@ -0,0 +1,305 @@
+# Documentation Next Steps — Editorial & Material Theme Enhancement Plan
+
+**Date:** 2026-03-22
+**Branch:** v2
+**Status:** Planning → Execution
+
+---
+
+## Executive Summary
+
+The MkDocs documentation site is comprehensive (70+ pages, all with proper frontmatter, no stubs) and already uses many Material theme features well (grid cards, admonitions, code copy, mermaid diagrams, social cards, blog plugin, dark/light toggle). This plan focuses on **activating dormant Material theme capabilities** and **editorial polish** to take the docs from "complete" to "professional-grade."
+
+---
+
+## Step 1: mkdocs.yml Configuration Hardening
+
+**Goal:** Enable Material theme features that are available but not configured.
+
+### 1a. Add missing theme features
+```yaml
+features:
+ # Already enabled (keep):
+ - announce.dismiss
+ - content.action.edit
+ - content.action.view
+ - content.code.annotate
+ - content.code.copy
+ - content.tooltips
+ - navigation.footer
+ - navigation.indexes
+ - navigation.path
+ - navigation.prune
+ - navigation.tabs
+ - navigation.tabs.sticky
+ - navigation.top
+ - navigation.tracking
+ - search.highlight
+ - search.share
+ - search.suggest
+ - toc.follow
+
+ # ADD these:
+ - navigation.instant # SPA-like navigation (no full page reload)
+ - navigation.instant.prefetch # Prefetch pages on hover
+ - navigation.instant.progress # Show loading progress bar
+ - content.code.select # Line selection in code blocks
+ - content.tabs.link # Linked content tabs (sync across page)
+```
+
+### 1b. Fix consent banner
+The copyright references `#__consent` but no consent config exists. Add:
+```yaml
+extra:
+ consent:
+ title: Cookie consent
+ description: >
+ We use cookies to recognize your repeated visits and preferences,
+ as well as to measure the effectiveness of our documentation.
+ With your consent, you help us improve.
+ actions:
+ - accept
+ - reject
+ - manage
+```
+
+### 1c. Fix copyright year
+Change `2024` → `2024–2026` in the copyright line.
+
+### 1d. Fix edit_uri branch
+Change `edit_uri: src/branch/main/mkdocs/docs` → `edit_uri: src/branch/v2/mkdocs/docs`
+
+### 1e. Add abbreviations snippets
+Create `docs/includes/abbreviations.md` and reference via snippets:
+```yaml
+markdown_extensions:
+ - pymdownx.snippets:
+ auto_append:
+ - includes/abbreviations.md
+```
+
+Common abbreviations: API, JWT, RBAC, CSV, ORM, SMTP, CORS, SSL, TLS, DNS, CRUD, SSO, SPA, CLI, GUI, QR, GPS, GDPR, CDN, VPS, CGNAT, NAR, CRM, OG, DDoS, SSE, UUID, FOSS, HSTS, CSP
+
+### 1f. Add privacy plugin (optional, external resource proxying)
+```yaml
+plugins:
+ - privacy
+```
+
+---
+
+## Step 2: Page-Level Metadata Enhancement
+
+**Goal:** Add `tags`, `status`, and `search.boost` metadata to every page.
+
+### 2a. Tags
+The tags plugin is loaded but zero pages use tags. Add contextually appropriate tags to every page. Example tag taxonomy:
+
+- **Audience:** `admin`, `volunteer`, `user`, `operator`, `developer`
+- **Module:** `influence`, `map`, `media`, `payments`, `broadcast`, `social`
+- **Type:** `guide`, `reference`, `tutorial`, `concept`, `troubleshooting`
+- **Feature:** `campaigns`, `canvassing`, `shifts`, `gallery`, `landing-pages`, `newsletter`, `sms`, `chat`, `events`
+
+### 2b. Status badges
+Material supports `status: new` and `status: deprecated` on pages, shown as badges in the nav sidebar. Apply:
+- `status: new` — Recent features (Gallery Ads, People CRM, Achievements, Social Calendar, CrowdSec, SMS, Docs Comments, Payments)
+- `status: deprecated` — Legacy/archival content if any
+
+Requires adding to `extra:` in mkdocs.yml:
+```yaml
+extra:
+ status:
+ new: Recently added
+ deprecated: Legacy
+```
+
+### 2c. Search boost
+Boost important entry-point pages so they rank higher:
+```yaml
+---
+search:
+ boost: 2
+---
+```
+Apply to: Getting Started index, Installation, First Steps, Features at a Glance, FAQ/Troubleshooting.
+
+---
+
+## Step 3: Abbreviations Glossary
+
+**Goal:** Create a shared abbreviations file so that hovering over acronyms shows their meaning.
+
+Create `mkdocs/docs/includes/abbreviations.md`:
+```markdown
+*[API]: Application Programming Interface
+*[JWT]: JSON Web Token
+*[RBAC]: Role-Based Access Control
+*[CORS]: Cross-Origin Resource Sharing
+*[SMTP]: Simple Mail Transfer Protocol
+*[CSV]: Comma-Separated Values
+*[ORM]: Object-Relational Mapping
+*[SSL]: Secure Sockets Layer
+*[TLS]: Transport Layer Security
+*[DNS]: Domain Name System
+*[CRUD]: Create, Read, Update, Delete
+*[SSO]: Single Sign-On
+*[SPA]: Single Page Application
+*[CLI]: Command Line Interface
+*[GUI]: Graphical User Interface
+*[QR]: Quick Response (code)
+*[GPS]: Global Positioning System
+*[GDPR]: General Data Protection Regulation
+*[CDN]: Content Delivery Network
+*[VPS]: Virtual Private Server
+*[CGNAT]: Carrier-Grade Network Address Translation
+*[NAR]: National Address Register
+*[CRM]: Customer Relationship Management
+*[OG]: Open Graph
+*[DDoS]: Distributed Denial of Service
+*[SSE]: Server-Sent Events
+*[UUID]: Universally Unique Identifier
+*[FOSS]: Free and Open Source Software
+*[HSTS]: HTTP Strict Transport Security
+*[CSP]: Content Security Policy
+*[BullMQ]: Bull Message Queue
+*[FFprobe]: FFmpeg Probe (media metadata tool)
+*[FFmpeg]: Fast Forward Moving Picture Experts Group
+*[XMPP]: Extensible Messaging and Presence Protocol
+```
+
+---
+
+## Step 4: Custom 404 Page
+
+**Goal:** Branded 404 page instead of browser default.
+
+Create `mkdocs/docs/404.md`:
+```markdown
+---
+template: main.html
+title: Page Not Found
+hide:
+ - navigation
+ - toc
+ - footer
+search:
+ exclude: true
+---
+
+# Page Not Found
+
+The page you're looking for doesn't exist or has been moved.
+
+[Go to Documentation Home](docs/index.md){ .md-button .md-button--primary }
+[Search](docs/index.md){ .md-button }
+```
+
+---
+
+## Step 5: Content Fixes — Broken Links & Stale Warnings
+
+**Goal:** Fix all broken links, placeholder content, and stale warnings.
+
+### 5a. Fix broken "Coming soon" links
+- `docs/index.md`: Monitoring card links to `../blog/index.md` → link to `admin/services/monitoring.md`
+- `docs/index.md`: Contributing card links to `../blog/index.md` → create a contributing stub or remove placeholder
+
+### 5b. Fix Architecture page
+Remove "Under Construction" admonition. Flesh out with:
+- Mermaid system diagram
+- Database entity relationship summary
+- Authentication flow (already started)
+- Request lifecycle
+
+### 5c. Fix Troubleshooting page
+Remove "Under Construction" admonition. Add more entries from CLAUDE.md and production experience.
+
+### 5d. Fix Admin Guide roles table
+Only lists 5 roles but there are 11. Add missing roles:
+BROADCAST_ADMIN, CONTENT_ADMIN, MEDIA_ADMIN, PAYMENTS_ADMIN, EVENTS_ADMIN, SOCIAL_ADMIN
+
+### 5e. Social icons semantic fix
+GitHub icon links to Gitea — change icon to `fontawesome/brands/gitea` or `simple/gitea` if available, or use a generic `fontawesome/solid/code-branch`.
+
+---
+
+## Step 6: Cleanup Test/Orphan Files
+
+**Goal:** Remove files that shouldn't be in the docs directory.
+
+- `docs/test.md` (41KB test file)
+- `docs/test-page.md`
+- `docs/testing.md`
+- `docs/lander.md` (override template pointer — keep if used by index.md)
+- `docs/main.md` (override template pointer — keep if used)
+
+Verify `lander.md` and `main.md` are still needed by checking if any page uses `template: lander.html` or `template: main.html`.
+
+---
+
+## Step 7: Announcement Bar
+
+**Goal:** Use Material's announcement bar for version/status info.
+
+Create `mkdocs/docs/overrides/main.html` addition (or modify existing) with announcement block:
+```html
+{% block announce %}
+ Changemaker Lite v2 — Get started in 5 minutes
+{% endblock %}
+```
+
+Note: The existing `main.html` override is 35KB — check if it already has an announce block before modifying.
+
+---
+
+## Step 8: Blog Seeding
+
+**Goal:** Create 1–2 initial blog posts so the blog section isn't empty.
+
+Suggested posts:
+1. **"Introducing Changemaker Lite v2"** — Overview of the rebuild, what's new, philosophy
+2. **"Why Self-Hosted Campaign Tools Matter in 2026"** — Draws from the Philosophy page
+
+---
+
+## Step 9: Screenshot Audit
+
+**Goal:** Verify all `` references resolve to actual files. Take new screenshots with Playwright where missing or outdated.
+
+Pages referencing screenshots:
+- Getting Started index (dashboard.png)
+- First Steps (login.png, dashboard.png, settings-organization.png, campaigns.png, locations.png, shifts.png)
+- Dashboard (dashboard.png)
+- People & Access (users.png)
+- Settings (settings.png)
+- Campaigns (campaigns.png)
+
+---
+
+## Priority Order
+
+| Priority | Step | Impact | Effort |
+|----------|------|--------|--------|
+| **P0** | Step 1 (mkdocs.yml fixes) | High — broken consent, wrong branch, missing SPA nav | Low |
+| **P0** | Step 5 (broken links/content) | High — broken UX | Medium |
+| **P0** | Step 6 (cleanup test files) | Medium — professional appearance | Low |
+| **P1** | Step 3 (abbreviations) | Medium — reader comprehension | Low |
+| **P1** | Step 4 (404 page) | Medium — UX polish | Low |
+| **P1** | Step 2 (tags/status/boost) | Medium — discoverability | Medium-High |
+| **P2** | Step 7 (announcement bar) | Low-Medium — branding | Low |
+| **P2** | Step 8 (blog seeding) | Low — completeness | Medium |
+| **P2** | Step 9 (screenshot audit) | Medium — visual credibility | High |
+
+---
+
+## Material Theme Reference
+
+Key Material docs for implementers:
+- [Setting up tags](https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/)
+- [Setting up navigation](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/)
+- [Page status](https://squidfunk.github.io/mkdocs-material/reference/index/#setting-the-page-status)
+- [Search boosting](https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-boosting)
+- [Abbreviations](https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-abbreviations)
+- [Cookie consent](https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent)
+- [Custom 404](https://www.mkdocs.org/user-guide/custom-themes/#custom-theme)
+- [Announcement bar](https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-header/#announcement-bar)
diff --git a/mkdocs/docs/404.md b/mkdocs/docs/404.md
new file mode 100644
index 00000000..04278995
--- /dev/null
+++ b/mkdocs/docs/404.md
@@ -0,0 +1,25 @@
+---
+template: main.html
+title: Page Not Found
+hide:
+ - navigation
+ - toc
+ - footer
+search:
+ exclude: true
+---
+
+
+
+# :material-map-marker-question: Page Not Found
+
+The page you're looking for doesn't exist or has been moved.
+
+[Back to Documentation :material-arrow-left:](docs/index.md){ .md-button .md-button--primary }
+[Search the Docs :material-magnify:](docs/index.md){ .md-button }
+
+---
+
+*If you followed a link here, please [report the broken link](https://gitea.bnkops.com/admin/changemaker.lite/issues/new){ target="_blank" } so we can fix it.*
+
+
diff --git a/mkdocs/docs/assets/images/screenshots/admin/dashboard.png b/mkdocs/docs/assets/images/screenshots/admin/dashboard.png
index d095bd4d..9e009f91 100644
Binary files a/mkdocs/docs/assets/images/screenshots/admin/dashboard.png and b/mkdocs/docs/assets/images/screenshots/admin/dashboard.png differ
diff --git a/mkdocs/docs/assets/images/screenshots/admin/locations.png b/mkdocs/docs/assets/images/screenshots/admin/locations.png
index 152653c1..d3c7b592 100644
Binary files a/mkdocs/docs/assets/images/screenshots/admin/locations.png and b/mkdocs/docs/assets/images/screenshots/admin/locations.png differ
diff --git a/mkdocs/docs/assets/images/screenshots/admin/settings.png b/mkdocs/docs/assets/images/screenshots/admin/settings.png
index 0fdc8e2b..e21f0fca 100644
Binary files a/mkdocs/docs/assets/images/screenshots/admin/settings.png and b/mkdocs/docs/assets/images/screenshots/admin/settings.png differ
diff --git a/mkdocs/docs/assets/images/screenshots/admin/shifts.png b/mkdocs/docs/assets/images/screenshots/admin/shifts.png
index 05c0bbe8..2cae879d 100644
Binary files a/mkdocs/docs/assets/images/screenshots/admin/shifts.png and b/mkdocs/docs/assets/images/screenshots/admin/shifts.png differ
diff --git a/mkdocs/docs/assets/images/screenshots/admin/users.png b/mkdocs/docs/assets/images/screenshots/admin/users.png
index f5393d23..f044e263 100644
Binary files a/mkdocs/docs/assets/images/screenshots/admin/users.png and b/mkdocs/docs/assets/images/screenshots/admin/users.png differ
diff --git a/mkdocs/docs/assets/images/screenshots/getting-started/dashboard.png b/mkdocs/docs/assets/images/screenshots/getting-started/dashboard.png
index 42061840..9e009f91 100644
Binary files a/mkdocs/docs/assets/images/screenshots/getting-started/dashboard.png and b/mkdocs/docs/assets/images/screenshots/getting-started/dashboard.png differ
diff --git a/mkdocs/docs/assets/images/screenshots/getting-started/locations.png b/mkdocs/docs/assets/images/screenshots/getting-started/locations.png
index 152653c1..d3c7b592 100644
Binary files a/mkdocs/docs/assets/images/screenshots/getting-started/locations.png and b/mkdocs/docs/assets/images/screenshots/getting-started/locations.png differ
diff --git a/mkdocs/docs/assets/images/screenshots/getting-started/login.png b/mkdocs/docs/assets/images/screenshots/getting-started/login.png
index 7143e45e..1c08a762 100644
Binary files a/mkdocs/docs/assets/images/screenshots/getting-started/login.png and b/mkdocs/docs/assets/images/screenshots/getting-started/login.png differ
diff --git a/mkdocs/docs/assets/images/screenshots/getting-started/settings-organization.png b/mkdocs/docs/assets/images/screenshots/getting-started/settings-organization.png
index 0fdc8e2b..e21f0fca 100644
Binary files a/mkdocs/docs/assets/images/screenshots/getting-started/settings-organization.png and b/mkdocs/docs/assets/images/screenshots/getting-started/settings-organization.png differ
diff --git a/mkdocs/docs/assets/images/screenshots/getting-started/shifts.png b/mkdocs/docs/assets/images/screenshots/getting-started/shifts.png
index b8125422..2cae879d 100644
Binary files a/mkdocs/docs/assets/images/screenshots/getting-started/shifts.png and b/mkdocs/docs/assets/images/screenshots/getting-started/shifts.png differ
diff --git a/mkdocs/docs/assets/images/screenshots/getting-started/users.png b/mkdocs/docs/assets/images/screenshots/getting-started/users.png
index a53617d8..f044e263 100644
Binary files a/mkdocs/docs/assets/images/screenshots/getting-started/users.png and b/mkdocs/docs/assets/images/screenshots/getting-started/users.png differ
diff --git a/mkdocs/docs/blog/.authors.yml b/mkdocs/docs/blog/.authors.yml
new file mode 100644
index 00000000..48261db7
--- /dev/null
+++ b/mkdocs/docs/blog/.authors.yml
@@ -0,0 +1,5 @@
+authors:
+ admin:
+ name: Bunker Operations
+ description: Changemaker Lite core team
+ avatar: https://gitea.bnkops.com/avatars/1
diff --git a/mkdocs/docs/blog/posts/introducing-changemaker-lite-v2.md b/mkdocs/docs/blog/posts/introducing-changemaker-lite-v2.md
new file mode 100644
index 00000000..f9462cba
--- /dev/null
+++ b/mkdocs/docs/blog/posts/introducing-changemaker-lite-v2.md
@@ -0,0 +1,71 @@
+---
+date: 2026-03-22
+authors:
+ - admin
+categories:
+ - Announcements
+ - Platform
+tags:
+ - v2
+ - release
+ - self-hosted
+ - FOSS
+---
+
+# Introducing Changemaker Lite v2
+
+Changemaker Lite v2 is a ground-up rebuild of the platform — same mission, entirely new architecture. After 14 phases of development, the platform is ready for production use.
+
+
+
+## What Changed
+
+V1 was two independent Express apps stitched together with NocoDB as a data layer. It worked, but scaling features meant fighting the architecture at every turn.
+
+V2 is a unified TypeScript stack:
+
+- **Dual API architecture** — Express.js for the main platform, Fastify for the media library, sharing a single PostgreSQL 16 database via Prisma ORM
+- **React admin GUI** — Vite + Ant Design + Zustand, serving admin, public, and volunteer interfaces from one build
+- **30+ Docker services** — from core infrastructure to monitoring, communication, and developer tools
+- **JWT authentication** with refresh token rotation, role-based access control (11 roles), and a comprehensive security audit
+
+## What's New
+
+The feature set has grown substantially:
+
+- **Advocacy campaigns** with postal code → representative lookup, email sending, response walls, and moderation
+- **Map & canvassing** with multi-provider geocoding, polygon territories, GPS-tracked volunteer sessions, and walking route generation
+- **Media manager** with video upload, FFprobe metadata extraction, scheduled publishing, analytics, and a public gallery
+- **Landing page builder** powered by GrapesJS with drag-and-drop editing
+- **Payments** via encrypted Stripe integration — products, donations, and subscription plans
+- **SMS campaigns** via a Termux Android bridge
+- **Team communication** with self-hosted Rocket.Chat and Jitsi Meet
+- **People CRM** aggregating contacts across all modules with duplicate detection and merge
+- **Volunteer social features** — friend system, achievements, leaderboards, and a personal calendar
+- **One-command install** — `curl | bash` pulls a release tarball and runs the config wizard
+
+## Why Self-Hosted
+
+Every subscription to corporate campaign software funds infrastructure you don't control. Your voter lists, canvassing outcomes, and communication patterns become assets on someone else's balance sheet.
+
+Changemaker Lite costs roughly the price of a VPS — often under $50/month for the full stack. But the real value isn't cost savings. It's **control.** No vendor can cut off your access. No acquisition can change your terms.
+
+Read more in our [Philosophy](../../docs/phil.md) page.
+
+## Get Started
+
+```bash
+curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash
+```
+
+Or follow the [Getting Started guide](../../docs/getting-started/index.md) for a walkthrough.
+
+## What's Next
+
+Phase 15 (Testing & Polish) is underway. We're also working on:
+
+- Social Calendar Phase B (shared views, availability finder)
+- Expanded test coverage
+- Performance optimization for large location datasets
+
+Follow this blog for updates, or subscribe to the [newsletter](https://listmonk.bnkops.com/subscription/form).
diff --git a/mkdocs/docs/docs/admin/advocacy/campaigns.md b/mkdocs/docs/docs/admin/advocacy/campaigns.md
index bb3dfb4f..b4198f0a 100644
--- a/mkdocs/docs/docs/admin/advocacy/campaigns.md
+++ b/mkdocs/docs/docs/admin/advocacy/campaigns.md
@@ -2,6 +2,11 @@
title: Advocacy Campaigns
description: Help supporters contact elected representatives through email campaigns with postal code lookup and response tracking.
icon: material/email-fast
+tags:
+ - guide
+ - admin
+ - influence
+ - campaigns
---
# Advocacy Campaigns
diff --git a/mkdocs/docs/docs/admin/advocacy/email-queue.md b/mkdocs/docs/docs/admin/advocacy/email-queue.md
index 90ba2483..6449c3c3 100644
--- a/mkdocs/docs/docs/admin/advocacy/email-queue.md
+++ b/mkdocs/docs/docs/admin/advocacy/email-queue.md
@@ -2,6 +2,11 @@
title: Email Queue
description: Monitor and manage the BullMQ advocacy email delivery queue.
icon: material/email-sync
+tags:
+ - guide
+ - admin
+ - influence
+ - email
---
# Email Queue
diff --git a/mkdocs/docs/docs/admin/advocacy/index.md b/mkdocs/docs/docs/admin/advocacy/index.md
index c6095355..5151ff28 100644
--- a/mkdocs/docs/docs/admin/advocacy/index.md
+++ b/mkdocs/docs/docs/admin/advocacy/index.md
@@ -2,6 +2,10 @@
title: Advocacy
description: Manage email campaigns, moderate responses, and monitor email delivery.
icon: material/email-fast
+tags:
+ - guide
+ - admin
+ - influence
---
# Advocacy
diff --git a/mkdocs/docs/docs/admin/advocacy/representatives.md b/mkdocs/docs/docs/admin/advocacy/representatives.md
index 654de386..cf4fe136 100644
--- a/mkdocs/docs/docs/admin/advocacy/representatives.md
+++ b/mkdocs/docs/docs/admin/advocacy/representatives.md
@@ -2,6 +2,10 @@
title: Representatives
description: Represent API integration for postal code to representative lookup with caching.
icon: material/account-tie
+tags:
+ - guide
+ - admin
+ - influence
---
# Representatives
diff --git a/mkdocs/docs/docs/admin/advocacy/responses.md b/mkdocs/docs/docs/admin/advocacy/responses.md
index 3f3d6773..51d88613 100644
--- a/mkdocs/docs/docs/admin/advocacy/responses.md
+++ b/mkdocs/docs/docs/admin/advocacy/responses.md
@@ -2,6 +2,11 @@
title: Response Moderation
description: Moderate the public response wall where supporters share how representatives replied.
icon: material/message-reply-text
+tags:
+ - guide
+ - admin
+ - influence
+ - moderation
---
# Response Moderation
diff --git a/mkdocs/docs/docs/admin/broadcast/email-templates.md b/mkdocs/docs/docs/admin/broadcast/email-templates.md
index 47b29d4d..49af5ff7 100644
--- a/mkdocs/docs/docs/admin/broadcast/email-templates.md
+++ b/mkdocs/docs/docs/admin/broadcast/email-templates.md
@@ -2,6 +2,11 @@
title: Email Templates
description: Create reusable email templates with variable substitution for campaign communications.
icon: material/email-edit
+tags:
+ - guide
+ - admin
+ - broadcast
+ - email
---
# Email Templates
diff --git a/mkdocs/docs/docs/admin/broadcast/index.md b/mkdocs/docs/docs/admin/broadcast/index.md
index befe45de..b623c4f5 100644
--- a/mkdocs/docs/docs/admin/broadcast/index.md
+++ b/mkdocs/docs/docs/admin/broadcast/index.md
@@ -2,6 +2,10 @@
title: Broadcast
description: Newsletter sync, email templates, and SMS campaigns for reaching supporters.
icon: material/bullhorn
+tags:
+ - guide
+ - admin
+ - broadcast
---
# Broadcast
diff --git a/mkdocs/docs/docs/admin/broadcast/newsletter.md b/mkdocs/docs/docs/admin/broadcast/newsletter.md
index f755539d..384643d7 100644
--- a/mkdocs/docs/docs/admin/broadcast/newsletter.md
+++ b/mkdocs/docs/docs/admin/broadcast/newsletter.md
@@ -2,6 +2,11 @@
title: Newsletter (Listmonk)
description: Integrated opt-in mailing lists and newsletter campaigns powered by Listmonk.
icon: material/newspaper-variant
+tags:
+ - guide
+ - admin
+ - broadcast
+ - email
---
# Newsletter (Listmonk)
diff --git a/mkdocs/docs/docs/admin/broadcast/sms.md b/mkdocs/docs/docs/admin/broadcast/sms.md
index bfa2481e..ed09010b 100644
--- a/mkdocs/docs/docs/admin/broadcast/sms.md
+++ b/mkdocs/docs/docs/admin/broadcast/sms.md
@@ -2,6 +2,12 @@
title: SMS Campaigns
description: Complete guide to setting up the Termux Android SMS bridge for text message outreach, contact management, and response tracking.
icon: material/message-text
+status: new
+tags:
+ - guide
+ - admin
+ - broadcast
+ - sms
---
# SMS Campaigns
diff --git a/mkdocs/docs/docs/admin/dashboard.md b/mkdocs/docs/docs/admin/dashboard.md
index 3d98b404..f283e83d 100644
--- a/mkdocs/docs/docs/admin/dashboard.md
+++ b/mkdocs/docs/docs/admin/dashboard.md
@@ -2,6 +2,9 @@
title: Dashboard
description: Admin dashboard with live stats, activity feed, upcoming shifts, and service health indicators.
icon: material/view-dashboard
+tags:
+ - guide
+ - admin
---
# Dashboard
diff --git a/mkdocs/docs/docs/admin/index.md b/mkdocs/docs/docs/admin/index.md
index 28bd346d..e95ac6da 100644
--- a/mkdocs/docs/docs/admin/index.md
+++ b/mkdocs/docs/docs/admin/index.md
@@ -2,6 +2,9 @@
title: Admin Guide
description: Day-to-day administration of users, campaigns, content, maps, media, and platform services.
icon: material/shield-account
+tags:
+ - guide
+ - admin
---
# Admin Guide
@@ -82,8 +85,14 @@ The admin panel at `/app` is your command center for managing the entire platfor
| Role | Access Level |
|------|-------------|
-| `SUPER_ADMIN` | Full platform access |
-| `INFLUENCE_ADMIN` | Campaigns, responses, email queue |
-| `MAP_ADMIN` | Locations, areas, shifts, canvassing |
+| `SUPER_ADMIN` | Full platform access — implicitly bypasses all role checks |
+| `INFLUENCE_ADMIN` | Campaigns, responses, representatives, email queue |
+| `MAP_ADMIN` | Locations, areas, shifts, canvassing, data quality |
+| `BROADCAST_ADMIN` | Newsletter sync, email templates |
+| `CONTENT_ADMIN` | Landing pages, homepage, navigation, documentation |
+| `MEDIA_ADMIN` | Video library, analytics, gallery, moderation, ads |
+| `PAYMENTS_ADMIN` | Products, donations, plans, Stripe configuration |
+| `EVENTS_ADMIN` | Gancio event sync and calendar management |
+| `SOCIAL_ADMIN` | Social connections, achievements, calendar layers |
| `USER` | Volunteer portal only |
-| `TEMP` | Limited volunteer access (auto-created) |
+| `TEMP` | Limited volunteer access (auto-created on shift signup) |
diff --git a/mkdocs/docs/docs/admin/map/areas.md b/mkdocs/docs/docs/admin/map/areas.md
index c2fc2b7b..92c3065c 100644
--- a/mkdocs/docs/docs/admin/map/areas.md
+++ b/mkdocs/docs/docs/admin/map/areas.md
@@ -2,6 +2,11 @@
title: Areas (Cuts)
description: Draw polygon canvassing territories on the map and organize locations into manageable regions.
icon: material/vector-polygon
+tags:
+ - guide
+ - admin
+ - map
+ - canvassing
---
# Areas (Cuts)
diff --git a/mkdocs/docs/docs/admin/map/canvassing.md b/mkdocs/docs/docs/admin/map/canvassing.md
index 934541a8..0af83543 100644
--- a/mkdocs/docs/docs/admin/map/canvassing.md
+++ b/mkdocs/docs/docs/admin/map/canvassing.md
@@ -2,6 +2,11 @@
title: Canvassing
description: Canvass dashboard, walk sheets, session management, and contact export for door-to-door outreach.
icon: material/walk
+tags:
+ - guide
+ - admin
+ - map
+ - canvassing
---
# Canvassing
diff --git a/mkdocs/docs/docs/admin/map/data-quality.md b/mkdocs/docs/docs/admin/map/data-quality.md
index ffb322b9..d669eb86 100644
--- a/mkdocs/docs/docs/admin/map/data-quality.md
+++ b/mkdocs/docs/docs/admin/map/data-quality.md
@@ -2,6 +2,11 @@
title: Data Quality
description: Geocoding quality metrics, provider distribution, and confidence analysis.
icon: material/chart-box
+tags:
+ - guide
+ - admin
+ - map
+ - analytics
---
# Data Quality
diff --git a/mkdocs/docs/docs/admin/map/index.md b/mkdocs/docs/docs/admin/map/index.md
index 01002490..47d09fa4 100644
--- a/mkdocs/docs/docs/admin/map/index.md
+++ b/mkdocs/docs/docs/admin/map/index.md
@@ -2,6 +2,10 @@
title: Map & Canvassing
description: Location management, canvassing territories, volunteer shifts, and door-to-door outreach coordination.
icon: material/map-marker-multiple
+tags:
+ - guide
+ - admin
+ - map
---
# Map & Canvassing
diff --git a/mkdocs/docs/docs/admin/map/locations.md b/mkdocs/docs/docs/admin/map/locations.md
index b5723f6a..6721091f 100644
--- a/mkdocs/docs/docs/admin/map/locations.md
+++ b/mkdocs/docs/docs/admin/map/locations.md
@@ -2,6 +2,11 @@
title: Locations
description: Import, geocode, and manage addresses for canvassing and public map display.
icon: material/map-marker-plus
+tags:
+ - guide
+ - admin
+ - map
+ - locations
---
# Locations
diff --git a/mkdocs/docs/docs/admin/map/settings.md b/mkdocs/docs/docs/admin/map/settings.md
index ce1f7672..ecea9fff 100644
--- a/mkdocs/docs/docs/admin/map/settings.md
+++ b/mkdocs/docs/docs/admin/map/settings.md
@@ -2,6 +2,11 @@
title: Map Settings
description: Configure map center coordinates, default zoom level, and QR code links for walk sheets.
icon: material/cog
+tags:
+ - guide
+ - admin
+ - map
+ - configuration
---
# Map Settings
diff --git a/mkdocs/docs/docs/admin/map/shifts.md b/mkdocs/docs/docs/admin/map/shifts.md
index 46b620c9..70f94a47 100644
--- a/mkdocs/docs/docs/admin/map/shifts.md
+++ b/mkdocs/docs/docs/admin/map/shifts.md
@@ -2,6 +2,11 @@
title: Shifts
description: Schedule volunteer time slots with recurring patterns, calendar views, and area assignments.
icon: material/calendar-clock
+tags:
+ - guide
+ - admin
+ - map
+ - shifts
---
# Shifts
diff --git a/mkdocs/docs/docs/admin/media/ads.md b/mkdocs/docs/docs/admin/media/ads.md
index dc388fd5..419f91d0 100644
--- a/mkdocs/docs/docs/admin/media/ads.md
+++ b/mkdocs/docs/docs/admin/media/ads.md
@@ -2,6 +2,11 @@
title: Gallery Ads
description: Promotional cards with audience targeting, scheduling, and click-through analytics.
icon: material/advertisements
+status: new
+tags:
+ - guide
+ - admin
+ - media
---
# Gallery Ads
diff --git a/mkdocs/docs/docs/admin/media/analytics.md b/mkdocs/docs/docs/admin/media/analytics.md
index 4fbe0684..b6b98007 100644
--- a/mkdocs/docs/docs/admin/media/analytics.md
+++ b/mkdocs/docs/docs/admin/media/analytics.md
@@ -2,6 +2,11 @@
title: Analytics
description: Video engagement metrics including views, watch time, completion rates, and traffic sources.
icon: material/chart-line
+tags:
+ - guide
+ - admin
+ - media
+ - analytics
---
# Analytics
diff --git a/mkdocs/docs/docs/admin/media/curated.md b/mkdocs/docs/docs/admin/media/curated.md
index f28fc520..f8ec590d 100644
--- a/mkdocs/docs/docs/admin/media/curated.md
+++ b/mkdocs/docs/docs/admin/media/curated.md
@@ -2,6 +2,11 @@
title: Curated Gallery
description: Manage playlists, the shorts feed, and featured content for the public video gallery.
icon: material/playlist-play
+tags:
+ - guide
+ - admin
+ - media
+ - gallery
---
# Curated Gallery
diff --git a/mkdocs/docs/docs/admin/media/index.md b/mkdocs/docs/docs/admin/media/index.md
index 7f91be0d..a8dc48ef 100644
--- a/mkdocs/docs/docs/admin/media/index.md
+++ b/mkdocs/docs/docs/admin/media/index.md
@@ -2,6 +2,10 @@
title: Media
description: Video and photo library, analytics, playlists, comment moderation, and gallery ad management.
icon: material/play-box-multiple
+tags:
+ - guide
+ - admin
+ - media
---
# Media
diff --git a/mkdocs/docs/docs/admin/media/library.md b/mkdocs/docs/docs/admin/media/library.md
index ba9bc5cc..ff7b4800 100644
--- a/mkdocs/docs/docs/admin/media/library.md
+++ b/mkdocs/docs/docs/admin/media/library.md
@@ -2,6 +2,11 @@
title: Library
description: Upload and manage videos and photos with metadata extraction, scheduled publishing, and preview links.
icon: material/folder-play
+tags:
+ - guide
+ - admin
+ - media
+ - videos
---
# Library
diff --git a/mkdocs/docs/docs/admin/media/moderation.md b/mkdocs/docs/docs/admin/media/moderation.md
index 17710867..9ed74821 100644
--- a/mkdocs/docs/docs/admin/media/moderation.md
+++ b/mkdocs/docs/docs/admin/media/moderation.md
@@ -2,6 +2,11 @@
title: Moderation
description: Review and manage comments across media content with word filters and moderation tools.
icon: material/shield-check
+tags:
+ - guide
+ - admin
+ - media
+ - moderation
---
# Moderation
diff --git a/mkdocs/docs/docs/admin/payments/donations.md b/mkdocs/docs/docs/admin/payments/donations.md
index cf59073f..762b649b 100644
--- a/mkdocs/docs/docs/admin/payments/donations.md
+++ b/mkdocs/docs/docs/admin/payments/donations.md
@@ -2,6 +2,11 @@
title: Donations
description: Create branded donation pages with fundraising goals, suggested amounts, and tracking.
icon: material/hand-heart
+status: new
+tags:
+ - guide
+ - admin
+ - payments
---
# Donations
diff --git a/mkdocs/docs/docs/admin/payments/index.md b/mkdocs/docs/docs/admin/payments/index.md
index a31e32bc..cbec2f49 100644
--- a/mkdocs/docs/docs/admin/payments/index.md
+++ b/mkdocs/docs/docs/admin/payments/index.md
@@ -2,6 +2,11 @@
title: Payments
description: Stripe-powered products, donations, subscription plans, and payment configuration.
icon: material/credit-card
+status: new
+tags:
+ - guide
+ - admin
+ - payments
---
# Payments
diff --git a/mkdocs/docs/docs/admin/payments/plans.md b/mkdocs/docs/docs/admin/payments/plans.md
index bde98744..f6c2dac5 100644
--- a/mkdocs/docs/docs/admin/payments/plans.md
+++ b/mkdocs/docs/docs/admin/payments/plans.md
@@ -2,6 +2,11 @@
title: Plans
description: Recurring subscription plans with monthly and yearly billing via Stripe.
icon: material/card-account-details-star
+status: new
+tags:
+ - guide
+ - admin
+ - payments
---
# Plans
diff --git a/mkdocs/docs/docs/admin/payments/products.md b/mkdocs/docs/docs/admin/payments/products.md
index 648fdaa0..f480acb3 100644
--- a/mkdocs/docs/docs/admin/payments/products.md
+++ b/mkdocs/docs/docs/admin/payments/products.md
@@ -2,6 +2,11 @@
title: Products
description: Manage merchandise and one-time purchase items with inventory and Stripe checkout.
icon: material/shopping
+status: new
+tags:
+ - guide
+ - admin
+ - payments
---
# Products
diff --git a/mkdocs/docs/docs/admin/payments/settings.md b/mkdocs/docs/docs/admin/payments/settings.md
index c9b64ccc..db6a39c2 100644
--- a/mkdocs/docs/docs/admin/payments/settings.md
+++ b/mkdocs/docs/docs/admin/payments/settings.md
@@ -2,6 +2,12 @@
title: Payment Settings
description: Configure Stripe API keys with encrypted storage for secure payment processing.
icon: material/credit-card-settings
+status: new
+tags:
+ - guide
+ - admin
+ - payments
+ - configuration
---
# Payment Settings
diff --git a/mkdocs/docs/docs/admin/people-access.md b/mkdocs/docs/docs/admin/people-access.md
index 08da4d3c..32851b19 100644
--- a/mkdocs/docs/docs/admin/people-access.md
+++ b/mkdocs/docs/docs/admin/people-access.md
@@ -2,6 +2,11 @@
title: People & Access
description: Manage users, roles, and the unified People CRM.
icon: material/account-group
+status: new
+tags:
+ - guide
+ - admin
+ - CRM
---
# People & Access
diff --git a/mkdocs/docs/docs/admin/services/crowdsec.md b/mkdocs/docs/docs/admin/services/crowdsec.md
index ed4d8445..dd2e89ac 100644
--- a/mkdocs/docs/docs/admin/services/crowdsec.md
+++ b/mkdocs/docs/docs/admin/services/crowdsec.md
@@ -2,6 +2,12 @@
title: CrowdSec & Security
description: CrowdSec Manager web UI, Tinyauth forward-auth, CrowdSec tuning, and Cloudflare Turnstile captcha on the Pangolin server.
icon: material/shield-lock
+status: new
+tags:
+ - guide
+ - admin
+ - services
+ - security
---
# CrowdSec Manager & Security Configuration
diff --git a/mkdocs/docs/docs/admin/services/index.md b/mkdocs/docs/docs/admin/services/index.md
index d61c3b16..f66fc050 100644
--- a/mkdocs/docs/docs/admin/services/index.md
+++ b/mkdocs/docs/docs/admin/services/index.md
@@ -2,6 +2,10 @@
title: Services
description: Tunnel management, monitoring, and third-party service integrations.
icon: material/server-network
+tags:
+ - guide
+ - admin
+ - services
---
# Services
diff --git a/mkdocs/docs/docs/admin/services/integrations.md b/mkdocs/docs/docs/admin/services/integrations.md
index c8c610ca..1210b48b 100644
--- a/mkdocs/docs/docs/admin/services/integrations.md
+++ b/mkdocs/docs/docs/admin/services/integrations.md
@@ -2,6 +2,11 @@
title: Integrations
description: Chat, video conferencing, password manager, whiteboard, Git hosting, automation, and QR services.
icon: material/puzzle
+tags:
+ - guide
+ - admin
+ - services
+ - integrations
---
# Integrations
diff --git a/mkdocs/docs/docs/admin/services/monitoring.md b/mkdocs/docs/docs/admin/services/monitoring.md
index 31f13ae2..3bc6d862 100644
--- a/mkdocs/docs/docs/admin/services/monitoring.md
+++ b/mkdocs/docs/docs/admin/services/monitoring.md
@@ -2,6 +2,11 @@
title: Monitoring
description: Prometheus metrics, Grafana dashboards, and Alertmanager for platform observability.
icon: material/chart-timeline-variant
+tags:
+ - guide
+ - admin
+ - services
+ - monitoring
---
# Monitoring
diff --git a/mkdocs/docs/docs/admin/services/tunnel.md b/mkdocs/docs/docs/admin/services/tunnel.md
index 71209eb5..006d0687 100644
--- a/mkdocs/docs/docs/admin/services/tunnel.md
+++ b/mkdocs/docs/docs/admin/services/tunnel.md
@@ -2,6 +2,11 @@
title: Tunnel (Pangolin)
description: Manage the Pangolin tunnel for exposing services to the internet without port forwarding.
icon: material/tunnel
+tags:
+ - guide
+ - admin
+ - services
+ - networking
---
# Tunnel (Pangolin)
diff --git a/mkdocs/docs/docs/admin/services/user-provisioning.md b/mkdocs/docs/docs/admin/services/user-provisioning.md
index 9ca900a5..680ec8bf 100644
--- a/mkdocs/docs/docs/admin/services/user-provisioning.md
+++ b/mkdocs/docs/docs/admin/services/user-provisioning.md
@@ -2,6 +2,11 @@
title: User Provisioning
description: Automatic account creation and sync across integrated services.
icon: material/account-sync
+status: new
+tags:
+ - guide
+ - admin
+ - services
---
# User Provisioning
diff --git a/mkdocs/docs/docs/admin/settings.md b/mkdocs/docs/docs/admin/settings.md
index 1dad552c..1fdf8163 100644
--- a/mkdocs/docs/docs/admin/settings.md
+++ b/mkdocs/docs/docs/admin/settings.md
@@ -2,6 +2,10 @@
title: Platform Settings
description: Multi-tab admin settings for organization branding, theme colors, email configuration, feature toggles, and notification controls.
icon: material/cog
+tags:
+ - guide
+ - admin
+ - configuration
---
# Platform Settings
diff --git a/mkdocs/docs/docs/admin/web/documentation.md b/mkdocs/docs/docs/admin/web/documentation.md
index 194325a8..cbb77467 100644
--- a/mkdocs/docs/docs/admin/web/documentation.md
+++ b/mkdocs/docs/docs/admin/web/documentation.md
@@ -2,6 +2,10 @@
title: Documentation
description: MkDocs site management, page analytics, comment moderation, and documentation settings.
icon: material/book-open-variant
+tags:
+ - guide
+ - admin
+ - content
---
# Documentation
diff --git a/mkdocs/docs/docs/admin/web/homepage.md b/mkdocs/docs/docs/admin/web/homepage.md
index ea0186bb..ec4cab4e 100644
--- a/mkdocs/docs/docs/admin/web/homepage.md
+++ b/mkdocs/docs/docs/admin/web/homepage.md
@@ -2,6 +2,10 @@
title: Public Homepage
description: Dynamic landing page that aggregates campaigns, shifts, media, events, and platform stats for public visitors.
icon: material/home-variant
+tags:
+ - guide
+ - admin
+ - content
---
# Public Homepage
diff --git a/mkdocs/docs/docs/admin/web/index.md b/mkdocs/docs/docs/admin/web/index.md
index 9b88d2ef..c73fec28 100644
--- a/mkdocs/docs/docs/admin/web/index.md
+++ b/mkdocs/docs/docs/admin/web/index.md
@@ -2,6 +2,10 @@
title: Web Content
description: Landing pages, homepage configuration, navigation, and documentation management.
icon: material/web
+tags:
+ - guide
+ - admin
+ - content
---
# Web Content
diff --git a/mkdocs/docs/docs/admin/web/landing-pages.md b/mkdocs/docs/docs/admin/web/landing-pages.md
index 9a042b00..15c4f2fc 100644
--- a/mkdocs/docs/docs/admin/web/landing-pages.md
+++ b/mkdocs/docs/docs/admin/web/landing-pages.md
@@ -2,6 +2,11 @@
title: Landing Pages
description: Build campaign microsites with a drag-and-drop GrapesJS visual editor.
icon: material/application-edit
+tags:
+ - guide
+ - admin
+ - content
+ - landing-pages
---
# Landing Pages
diff --git a/mkdocs/docs/docs/admin/web/navigation.md b/mkdocs/docs/docs/admin/web/navigation.md
index 2e12132c..f88a7b21 100644
--- a/mkdocs/docs/docs/admin/web/navigation.md
+++ b/mkdocs/docs/docs/admin/web/navigation.md
@@ -2,6 +2,10 @@
title: Navigation Settings
description: Customize the public-facing navigation menu from the admin panel.
icon: material/menu
+tags:
+ - guide
+ - admin
+ - content
---
# Navigation Settings
diff --git a/mkdocs/docs/docs/api/index.md b/mkdocs/docs/docs/api/index.md
index c8860d7d..b91bfe31 100644
--- a/mkdocs/docs/docs/api/index.md
+++ b/mkdocs/docs/docs/api/index.md
@@ -2,6 +2,10 @@
title: API Reference
description: Complete REST API reference for both the Express API (port 4000) and Fastify Media API (port 4100).
icon: material/api
+tags:
+ - reference
+ - developer
+ - API
---
# API Reference
diff --git a/mkdocs/docs/docs/architecture/index.md b/mkdocs/docs/docs/architecture/index.md
index b707421e..f7c9de17 100644
--- a/mkdocs/docs/docs/architecture/index.md
+++ b/mkdocs/docs/docs/architecture/index.md
@@ -2,38 +2,213 @@
title: Architecture
description: System architecture, dual API design, database schema, and authentication flow.
icon: material/sitemap
+tags:
+ - reference
+ - developer
+ - architecture
---
# Architecture
-Changemaker Lite uses a dual-API architecture with a shared PostgreSQL database.
+Changemaker Lite uses a dual-API architecture with a shared PostgreSQL database, a React single-page application, and Nginx for subdomain routing across 30+ services.
-!!! warning "Under Construction"
- Detailed architecture documentation is being written. Check back soon.
+---
-## System Overview
+## System Diagram
+```mermaid
+graph LR
+ Browser["Browser"] --> Nginx["Nginx (reverse proxy)"]
+ Nginx --> Admin["React Admin GUI port 3000"]
+ Nginx --> API["Express API port 4000"]
+ Nginx --> MediaAPI["Fastify Media API port 4100"]
+ Nginx --> MkDocs["MkDocs port 4003/4004"]
+ Nginx --> Services["Other Services (Gitea, NocoDB, etc.)"]
+
+ API --> PostgreSQL[("PostgreSQL 16 30+ tables")]
+ MediaAPI --> PostgreSQL
+ API --> Redis[("Redis cache + queues")]
+ API --> BullMQ["BullMQ (email, video jobs)"]
+ BullMQ --> Redis
+
+ subgraph Tunnel ["Public Access"]
+ Newt["Newt Client"] --> Pangolin["Pangolin Server"]
+ end
+ Newt --> Nginx
```
-Browser ──► Nginx (reverse proxy) ──┬──► Express API (port 4000) ──► PostgreSQL
- ├──► Fastify Media API (port 4100) ──┘
- ├──► React Admin GUI (port 3000)
- └──► MkDocs / Other Services
-```
+
+---
## Key Components
| Component | Technology | Role |
|-----------|-----------|------|
-| Main API | Express.js + Prisma | Auth, campaigns, map, shifts, pages |
-| Media API | Fastify + Prisma | Video library, analytics, uploads |
-| Admin GUI | React + Ant Design | Single-page admin application |
-| Database | PostgreSQL 16 | Shared by both APIs (30+ tables) |
-| Cache | Redis | Rate limiting, job queues, geocoding |
-| Proxy | Nginx | Subdomain routing, security headers |
+| **Main API** | Express.js + TypeScript + Prisma | Auth, campaigns, map, shifts, pages, canvassing, email |
+| **Media API** | Fastify + TypeScript + Prisma | Video library, analytics, uploads, scheduling |
+| **Admin GUI** | React 19 + Vite + Ant Design + Zustand | Admin dashboard, public pages, volunteer portal, media gallery |
+| **Database** | PostgreSQL 16 | Shared by both APIs (30+ models via Prisma) |
+| **Cache** | Redis 7 | Rate limiting, BullMQ job queues, geocoding cache |
+| **Proxy** | Nginx | Subdomain routing, security headers, WebSocket upgrade |
+| **Tunnel** | Pangolin + Newt | Expose services without port forwarding |
+| **Monitoring** | Prometheus + Grafana + Alertmanager | Metrics collection, dashboards, alerting |
+
+---
+
+## Dual API Design
+
+The platform runs two independent API servers sharing one PostgreSQL database:
+
+=== "Express API (port 4000)"
+
+ The main API handles all core platform logic:
+
+ - **Authentication** — JWT access/refresh tokens, RBAC middleware
+ - **Modules** — Influence (campaigns, responses), Map (locations, cuts, shifts, canvassing), Pages, Email Templates, Settings, Users, Payments, Social, Calendar
+ - **Services** — Email queue (BullMQ), geocoding queue, Listmonk sync, Pangolin client, user provisioning
+ - **ORM** — Prisma with 30+ models and migration history
+
+=== "Fastify Media API (port 4100)"
+
+ A separate server optimized for media handling:
+
+ - **Video CRUD** — Upload with FFprobe metadata extraction
+ - **Scheduled Publishing** — BullMQ queue with timezone support
+ - **Analytics** — View tracking, watch time, completion rates (GDPR-compliant)
+ - **Public Gallery** — Playlists, reactions, comments, SSE chat
+ - **ORM** — Prisma (migrated from Drizzle, Feb 2026)
+
+Both servers connect to the same database and share the same Prisma schema. This separation allows the media API to handle large file uploads and streaming independently from the main API's request/response cycle.
+
+---
## Authentication Flow
-- JWT access tokens (15 min) + refresh tokens (7 days)
-- Refresh token rotation with atomic database transaction
-- Role-based access control (5 roles)
-- Rate limiting on auth endpoints (10/min per IP)
+```mermaid
+sequenceDiagram
+ participant Client
+ participant API
+ participant DB
+ participant Redis
+
+ Client->>API: POST /api/auth/login {email, password}
+ API->>Redis: Check rate limit (10/min per IP)
+ Redis-->>API: OK
+ API->>DB: Verify bcrypt password
+ DB-->>API: User record
+ API->>DB: Create refresh token
+ API-->>Client: {accessToken (15min), refreshToken (7d)}
+
+ Note over Client: Authenticated requests
+ Client->>API: GET /api/campaigns Authorization: Bearer
+ API->>API: Verify JWT + check role (RBAC)
+ API-->>Client: 200 OK
+
+ Note over Client: Token expired
+ Client->>API: POST /api/auth/refresh {refreshToken}
+ API->>DB: Atomic rotation (delete old, create new)
+ API-->>Client: {new accessToken, new refreshToken}
+```
+
+### Security Features
+
+- **Password policy** — 12+ characters, uppercase, lowercase, digit (schema-enforced)
+- **Refresh token rotation** — Atomic Prisma transaction prevents race conditions
+- **User enumeration prevention** — Returns 401 (not 404) for missing users
+- **Rate limiting** — 10 requests/minute on auth endpoints via Redis
+- **11 roles** — `SUPER_ADMIN` (implicit bypass), 8 module-specific admin roles, `USER`, `TEMP`
+- **Encryption** — AES-256-GCM for sensitive DB fields (`ENCRYPTION_KEY` env var)
+
+---
+
+## Request Lifecycle
+
+```mermaid
+graph TD
+ A["Incoming Request"] --> B["Nginx"]
+ B -->|"Host: api.domain"| C["Express API"]
+ B -->|"Host: media.domain"| D["Fastify Media API"]
+ B -->|"Host: app.domain"| E["React Admin GUI"]
+ C --> F["Rate Limiter (Redis)"]
+ F --> G["Auth Middleware (JWT)"]
+ G --> H["Role Check (RBAC)"]
+ H --> I["Validation (Zod)"]
+ I --> J["Route Handler"]
+ J --> K["Service Layer"]
+ K --> L["Prisma ORM"]
+ L --> M[("PostgreSQL")]
+ J --> N["Response + Metrics"]
+```
+
+---
+
+## Database Schema
+
+The database contains **30+ Prisma models** organized by module:
+
+| Module | Key Models |
+|--------|-----------|
+| **Auth** | `User`, `RefreshToken` |
+| **Influence** | `Campaign`, `CampaignEmail`, `CampaignResponse`, `Representative`, `PostalCode` |
+| **Map** | `Location`, `Address`, `Cut`, `Shift`, `ShiftSignup` |
+| **Canvass** | `CanvassSession`, `CanvassVisit`, `TrackingSession`, `TrackingPoint` |
+| **Pages** | `Page`, `PageBlock`, `EmailTemplate` |
+| **Media** | `Video`, `VideoReaction`, `VideoComment`, `VideoView`, `Playlist`, `PlaylistVideo` |
+| **Payments** | `StripeProduct`, `StripePrice`, `StripeDonationPage`, `StripeOrder` |
+| **Social** | `Friendship`, `SocialNotification`, `CalendarLayer`, `CalendarItem` |
+| **SMS** | `SmsContactList`, `SmsCampaign`, `SmsMessage`, `SmsConversation` |
+| **People** | `Contact`, `ContactAddress`, `ContactEmail`, `ContactPhone`, `ContactConnection` |
+| **Settings** | `SiteSettings`, `MapSettings` |
+
+---
+
+## Docker Compose Architecture
+
+Services are organized into categories with dependency management:
+
+```mermaid
+graph TD
+ subgraph Core ["Core (always started)"]
+ PG["PostgreSQL"] --> API["Express API"]
+ Redis --> API
+ PG --> Media["Fastify Media API"]
+ API --> Admin["React Admin"]
+ Admin --> Nginx
+ API --> Nginx
+ Media --> Nginx
+ end
+
+ subgraph Communication ["Communication (optional)"]
+ RC["Rocket.Chat"] --> MongoDB
+ Jitsi["Jitsi Meet (4 containers)"]
+ Gancio["Gancio Events"]
+ end
+
+ subgraph Monitoring ["Monitoring (profile)"]
+ Prometheus --> Grafana
+ Prometheus --> Alertmanager
+ cAdvisor --> Prometheus
+ NodeExporter --> Prometheus
+ end
+
+ subgraph Tunnel ["Tunnel"]
+ Newt --> Nginx
+ end
+```
+
+Docker healthchecks ensure proper startup order: PostgreSQL and Redis must be healthy before the API starts. The API runs migrations and seeding automatically via its entrypoint script.
+
+---
+
+## Subdomain Routing
+
+Nginx routes requests based on the `Host` header. All services run on the `changemaker-lite` Docker bridge network.
+
+| Pattern | Target |
+|---------|--------|
+| `app.DOMAIN` | Admin GUI (admin + public + volunteer + gallery) |
+| `api.DOMAIN` | Express API |
+| `media.DOMAIN` | Fastify Media API |
+| `DOMAIN` (root) | MkDocs static site |
+| `*.DOMAIN` | 15+ additional service subdomains |
+
+See [Services](../services/index.md) for the complete subdomain table.
diff --git a/mkdocs/docs/docs/deployment/index.md b/mkdocs/docs/docs/deployment/index.md
index 91387b83..926d33d6 100644
--- a/mkdocs/docs/docs/deployment/index.md
+++ b/mkdocs/docs/docs/deployment/index.md
@@ -2,6 +2,11 @@
title: Deployment
description: Deploy Changemaker Lite to production with Docker, SSL, backups, and monitoring.
icon: material/docker
+tags:
+ - guide
+ - operator
+ - deployment
+ - docker
---
# Deployment
diff --git a/mkdocs/docs/docs/getting-started/control-panel.md b/mkdocs/docs/docs/getting-started/control-panel.md
index 78712e6f..11ef1d3e 100644
--- a/mkdocs/docs/docs/getting-started/control-panel.md
+++ b/mkdocs/docs/docs/getting-started/control-panel.md
@@ -2,6 +2,11 @@
title: Control Panel (CCP)
description: Multi-tenant management for provisioning and operating multiple Changemaker Lite instances.
icon: material/console
+status: new
+tags:
+ - guide
+ - operator
+ - multi-tenant
---
# Changemaker Control Panel (CCP)
diff --git a/mkdocs/docs/docs/getting-started/environment-variables.md b/mkdocs/docs/docs/getting-started/environment-variables.md
index a5d1f364..336f0892 100644
--- a/mkdocs/docs/docs/getting-started/environment-variables.md
+++ b/mkdocs/docs/docs/getting-started/environment-variables.md
@@ -2,6 +2,11 @@
title: Environment Variables
description: Complete reference for every .env variable in Changemaker Lite.
icon: material/file-cog
+tags:
+ - reference
+ - getting-started
+ - operator
+ - configuration
---
# Environment Variables
diff --git a/mkdocs/docs/docs/getting-started/features.md b/mkdocs/docs/docs/getting-started/features.md
index 39db7544..58e93e07 100644
--- a/mkdocs/docs/docs/getting-started/features.md
+++ b/mkdocs/docs/docs/getting-started/features.md
@@ -2,6 +2,11 @@
title: Features at a Glance
description: A visual overview of every Changemaker Lite module.
icon: material/star-shooting
+tags:
+ - reference
+ - getting-started
+search:
+ boost: 2
---
# Features at a Glance
diff --git a/mkdocs/docs/docs/getting-started/first-steps.md b/mkdocs/docs/docs/getting-started/first-steps.md
index 6a91158e..8e73d092 100644
--- a/mkdocs/docs/docs/getting-started/first-steps.md
+++ b/mkdocs/docs/docs/getting-started/first-steps.md
@@ -2,6 +2,12 @@
title: First Steps
description: Log in, explore the dashboard, and set up your first campaign and volunteer shift.
icon: material/shoe-print
+tags:
+ - tutorial
+ - getting-started
+ - admin
+search:
+ boost: 2
---
# First Steps
diff --git a/mkdocs/docs/docs/getting-started/index.md b/mkdocs/docs/docs/getting-started/index.md
index 3cb7279f..a72e6d01 100644
--- a/mkdocs/docs/docs/getting-started/index.md
+++ b/mkdocs/docs/docs/getting-started/index.md
@@ -2,6 +2,12 @@
title: Getting Started
description: Install and configure Changemaker Lite from scratch.
icon: material/rocket-launch
+tags:
+ - guide
+ - getting-started
+ - operator
+search:
+ boost: 2
---
# Getting Started
diff --git a/mkdocs/docs/docs/getting-started/installation.md b/mkdocs/docs/docs/getting-started/installation.md
index 5b3459d6..a410f489 100644
--- a/mkdocs/docs/docs/getting-started/installation.md
+++ b/mkdocs/docs/docs/getting-started/installation.md
@@ -2,6 +2,13 @@
title: Installation
description: System requirements, configuration wizard walkthrough, and initial service startup.
icon: material/download
+tags:
+ - guide
+ - getting-started
+ - operator
+ - docker
+search:
+ boost: 2
---
# Installation
diff --git a/mkdocs/docs/docs/getting-started/services.md b/mkdocs/docs/docs/getting-started/services.md
index ac8f7ece..8e48de6a 100644
--- a/mkdocs/docs/docs/getting-started/services.md
+++ b/mkdocs/docs/docs/getting-started/services.md
@@ -2,6 +2,11 @@
title: Services Overview
description: Complete catalog of all Docker services, ports, and startup commands.
icon: material/docker
+tags:
+ - reference
+ - getting-started
+ - operator
+ - docker
---
# Services Overview
diff --git a/mkdocs/docs/docs/getting-started/upgrades.md b/mkdocs/docs/docs/getting-started/upgrades.md
index aba670fd..574a17f8 100644
--- a/mkdocs/docs/docs/getting-started/upgrades.md
+++ b/mkdocs/docs/docs/getting-started/upgrades.md
@@ -2,6 +2,10 @@
title: Updates & Upgrades
description: Keep Changemaker Lite up to date via the admin GUI or command line.
icon: material/update
+tags:
+ - guide
+ - operator
+ - upgrades
---
# Updates & Upgrades
diff --git a/mkdocs/docs/docs/index.md b/mkdocs/docs/docs/index.md
index 608cced7..9c211106 100644
--- a/mkdocs/docs/docs/index.md
+++ b/mkdocs/docs/docs/index.md
@@ -2,6 +2,11 @@
title: Documentation
description: Changemaker Lite documentation hub — guides for users, admins, and operators.
icon: material/book-open-variant
+tags:
+ - guide
+ - getting-started
+search:
+ boost: 2
---
# Documentation
@@ -82,7 +87,7 @@ Welcome to the Changemaker Lite documentation. Whether you're a campaign volunte
Prometheus metrics, Grafana dashboards, Alertmanager rules, and health checks.
- [:octicons-arrow-right-24: Monitoring](../blog/index.md){ .md-button .md-button--secondary } *Coming soon*
+ [:octicons-arrow-right-24: Monitoring](admin/services/monitoring.md)
@@ -120,7 +125,7 @@ Welcome to the Changemaker Lite documentation. Whether you're a campaign volunte
Development setup, code style, git workflow, and pull request guidelines.
- [:octicons-arrow-right-24: Contributing](../blog/index.md){ .md-button .md-button--secondary } *Coming soon*
+ [:octicons-arrow-right-24: Contributing](https://gitea.bnkops.com/admin/changemaker.lite){ target="_blank" }
diff --git a/mkdocs/docs/docs/phil.md b/mkdocs/docs/docs/phil.md
index b418f044..4144d038 100644
--- a/mkdocs/docs/docs/phil.md
+++ b/mkdocs/docs/docs/phil.md
@@ -1,6 +1,10 @@
---
title: Philosophy
description: Why we build Changemaker Lite — and why your movement should own its infrastructure.
+tags:
+ - concept
+ - philosophy
+ - FOSS
---
# Philosophy
diff --git a/mkdocs/docs/docs/services/index.md b/mkdocs/docs/docs/services/index.md
index 46cf7c33..a2e050cb 100644
--- a/mkdocs/docs/docs/services/index.md
+++ b/mkdocs/docs/docs/services/index.md
@@ -2,6 +2,11 @@
title: Services
description: All services that make up the Changemaker Lite platform — configuration, ports, and links to upstream docs.
icon: material/server-network
+tags:
+ - reference
+ - operator
+ - services
+ - docker
---
# Services
diff --git a/mkdocs/docs/docs/troubleshooting/index.md b/mkdocs/docs/docs/troubleshooting/index.md
index 39c92084..e2ae89b8 100644
--- a/mkdocs/docs/docs/troubleshooting/index.md
+++ b/mkdocs/docs/docs/troubleshooting/index.md
@@ -2,14 +2,18 @@
title: Troubleshooting
description: Solutions for common errors, CORS issues, database problems, and tunnel debugging.
icon: material/bug
+tags:
+ - troubleshooting
+ - operator
+search:
+ boost: 2
---
# Troubleshooting
Common issues and their solutions when running Changemaker Lite.
-!!! warning "Under Construction"
- This troubleshooting guide is being expanded. Check back soon for more solutions.
+---
## CORS Errors in Production
@@ -23,26 +27,202 @@ CORS_ORIGINS=https://app.yourdomain.org,http://localhost:3000
Then restart the API: `docker compose restart api`
-## Pangolin Tunnel 403/302 Errors
+---
-**Symptom:** All API endpoints return 302 redirects to Pangolin auth page.
+## Pangolin Tunnel — 403/302 Errors
-**Fix:** In the Pangolin dashboard, set each resource to "Not Protected" (public access).
+**Symptom:** All API endpoints return 302 redirects to Pangolin auth page, or 403 Forbidden.
+
+**Fix:** In the Pangolin dashboard, set each resource to **Not Protected** (public access). Critical resources to fix first:
+
+1. `api.yourdomain.org` — Main API
+2. `app.yourdomain.org` — Admin GUI + public pages
+3. `media.yourdomain.org` — Media API
+
+**Verify:**
+
+```bash
+# Should return JSON, NOT a 302 redirect
+curl -I https://api.yourdomain.org/api/health
+```
+
+---
## Database Connection Failures
+**Symptom:** API logs show database connection errors.
+
+**Checklist:**
+
1. Check PostgreSQL: `docker compose ps v2-postgres`
-2. Verify `DATABASE_URL` in `.env`
+2. Verify `DATABASE_URL` in `.env` matches container name and port
3. View logs: `docker compose logs v2-postgres --tail 50`
+4. Test connection: `docker compose exec api npx prisma db execute --stdin <<< "SELECT 1"`
+
+---
## Redis Connection Failures
+**Symptom:** API logs show Redis connection errors, rate limiting doesn't work.
+
+**Checklist:**
+
1. Check Redis: `docker compose ps redis-changemaker`
-2. Verify `REDIS_PASSWORD` and `REDIS_URL` format in `.env`
-3. Test: `docker compose exec redis-changemaker redis-cli -a $REDIS_PASSWORD ping`
+2. Verify `REDIS_PASSWORD` and `REDIS_URL` format (`redis://:password@host:port`)
+3. View logs: `docker compose logs redis-changemaker --tail 50`
+4. Test: `docker compose exec redis-changemaker redis-cli -a $REDIS_PASSWORD ping`
+
+---
## API Not Starting
+**Symptom:** API container keeps restarting or won't start.
+
+**Checklist:**
+
1. Check logs: `docker compose logs api --tail 100`
-2. Verify all required env vars are set (see `.env.example`)
-3. Run migrations: `docker compose exec api npx prisma migrate deploy`
+2. Verify all required env vars are set (compare with `.env.example`)
+3. Check database is ready: `docker compose ps v2-postgres` (should show "healthy")
+4. Run migrations manually: `docker compose exec api npx prisma migrate deploy`
+5. Check for port conflicts: `ss -tlnp | grep 4000`
+
+---
+
+## Containers in Restart Loops
+
+**Symptom:** `docker compose ps` shows containers with "restarting" status.
+
+**Diagnosis:**
+
+```bash
+# Find restarting containers
+docker compose ps | grep -i restarting
+
+# Check recent logs for the problem container
+docker compose logs --tail 50
+
+# Check container exit code
+docker inspect --format='{{.State.ExitCode}}'
+```
+
+**Common causes:**
+
+- Missing environment variables (check `.env`)
+- Database not ready (healthcheck dependencies)
+- Port already in use by another process
+- Insufficient memory (check with `free -h`)
+
+---
+
+## Newt Tunnel Won't Connect
+
+**Checklist (in order):**
+
+1. **Credentials:** Verify `PANGOLIN_NEWT_ID` and `PANGOLIN_NEWT_SECRET` in `.env`
+2. **Endpoint:** Confirm `PANGOLIN_ENDPOINT` matches your Pangolin server URL
+3. **Logs:** `docker compose logs newt --tail 50`
+4. **Nginx running:** Newt depends on nginx — `docker compose ps nginx`
+5. **Network:** Ensure outbound HTTPS is not blocked by your firewall
+
+---
+
+## Migration Errors
+
+**Symptom:** `prisma migrate deploy` fails.
+
+**Common fixes:**
+
+```bash
+# Check migration status
+docker compose exec api npx prisma migrate status
+
+# If migrations are out of sync, reset (DESTRUCTIVE — dev only)
+docker compose exec api npx prisma migrate reset
+
+# If shadow database errors, create one
+docker compose exec -T v2-postgres createdb -U changemaker prisma_shadow_diff
+```
+
+!!! danger "Never use `prisma db push` in production"
+ Always use `prisma migrate dev` (development) or `prisma migrate deploy` (production) to keep migration history in sync.
+
+---
+
+## Media API Upload Failures
+
+**Symptom:** Video uploads fail with permission errors or 500 status.
+
+**Checklist:**
+
+1. Verify inbox volume is writable: check `media/local/inbox` has `:rw` mount
+2. Check disk space: `df -h`
+3. Verify FFmpeg is installed in container: `docker compose exec media-api ffprobe -version`
+4. Check upload size limit: default is 10 GB in Fastify multipart config
+
+---
+
+## Email Not Sending
+
+**Symptom:** Advocacy emails or notifications aren't delivered.
+
+**Checklist:**
+
+1. Check `EMAIL_TEST_MODE` — if `true`, all emails go to MailHog (`http://localhost:8025`)
+2. Verify SMTP credentials in `.env` (`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`)
+3. Check BullMQ queue: visit **Admin > Email Queue** or check logs
+4. Test SMTP from Settings: **Admin > Settings > Email > Test Connection**
+
+---
+
+## Services Unreachable via Tunnel
+
+**Checklist:**
+
+1. Verify nginx is running: `docker compose ps nginx`
+2. Test locally first: `curl http://localhost:4000/api/health`
+3. Check nginx logs: `docker compose logs nginx --tail 50`
+4. Verify DNS: `dig app.yourdomain.org` should point to your Pangolin server
+5. Check Pangolin resources are all set to "Not Protected"
+
+---
+
+## Slow Map Performance
+
+**Symptom:** Map page is slow or returns 500 errors with many locations.
+
+**Causes and fixes:**
+
+- **Too many locations loaded at once** — the API limits by address count with debounced bounds queries
+- **Missing indexes** — verify database has the 5 performance indexes on Location/Address tables
+- **Browser memory** — marker clustering activates above zoom level 18; below that, addresses are grouped
+
+---
+
+## Docker Disk Space
+
+**Symptom:** Builds fail, containers can't start, or images won't pull.
+
+```bash
+# Check disk usage
+df -h
+
+# Clean unused Docker resources
+docker system prune -f
+
+# Clean old images (keep only last 2 days)
+docker image prune -a --filter "until=48h"
+
+# Check what's using space
+docker system df
+```
+
+---
+
+## Getting Help
+
+If your issue isn't listed here:
+
+1. Check the API logs: `docker compose logs api --tail 200`
+2. Search the [Gitea issues](https://gitea.bnkops.com/admin/changemaker.lite/issues)
+3. Review the [Deployment guide](../deployment/index.md) for production-specific issues
+4. File a new issue with your logs and `.env` (redact passwords)
diff --git a/mkdocs/docs/docs/user-guide/campaigns.md b/mkdocs/docs/docs/user-guide/campaigns.md
index fca2a091..87ca7a4a 100644
--- a/mkdocs/docs/docs/user-guide/campaigns.md
+++ b/mkdocs/docs/docs/user-guide/campaigns.md
@@ -2,6 +2,11 @@
title: Campaigns
description: Find advocacy campaigns, look up your representatives by postal code, and send emails.
icon: material/email-fast
+tags:
+ - guide
+ - user
+ - influence
+ - campaigns
---
# Campaigns
diff --git a/mkdocs/docs/docs/user-guide/donations.md b/mkdocs/docs/docs/user-guide/donations.md
index 9a34bf34..2e33a107 100644
--- a/mkdocs/docs/docs/user-guide/donations.md
+++ b/mkdocs/docs/docs/user-guide/donations.md
@@ -2,6 +2,11 @@
title: Donations
description: Support the cause with one-time donations on branded pages with goals and suggested amounts.
icon: material/hand-heart
+status: new
+tags:
+ - guide
+ - user
+ - payments
---
# Donations
diff --git a/mkdocs/docs/docs/user-guide/events.md b/mkdocs/docs/docs/user-guide/events.md
index 75c5bf65..66e96ffb 100644
--- a/mkdocs/docs/docs/user-guide/events.md
+++ b/mkdocs/docs/docs/user-guide/events.md
@@ -2,6 +2,10 @@
title: Events (Gancio)
description: Self-hosted event management with automatic shift-to-event sync powered by Gancio.
icon: material/calendar-star
+tags:
+ - guide
+ - user
+ - events
---
# Events (Gancio)
diff --git a/mkdocs/docs/docs/user-guide/gallery.md b/mkdocs/docs/docs/user-guide/gallery.md
index bff87bba..262707f8 100644
--- a/mkdocs/docs/docs/user-guide/gallery.md
+++ b/mkdocs/docs/docs/user-guide/gallery.md
@@ -2,6 +2,11 @@
title: Gallery
description: Watch campaign videos, browse photos, explore playlists, and view shorts.
icon: material/play-box-multiple
+tags:
+ - guide
+ - user
+ - media
+ - gallery
---
# Gallery
diff --git a/mkdocs/docs/docs/user-guide/index.md b/mkdocs/docs/docs/user-guide/index.md
index 30ea7d79..54caab53 100644
--- a/mkdocs/docs/docs/user-guide/index.md
+++ b/mkdocs/docs/docs/user-guide/index.md
@@ -2,6 +2,9 @@
title: User Guide
description: How to use Changemaker Lite as a public visitor or registered supporter.
icon: material/account
+tags:
+ - guide
+ - user
---
# User Guide
diff --git a/mkdocs/docs/docs/user-guide/map.md b/mkdocs/docs/docs/user-guide/map.md
index b7863891..69e107f0 100644
--- a/mkdocs/docs/docs/user-guide/map.md
+++ b/mkdocs/docs/docs/user-guide/map.md
@@ -2,6 +2,10 @@
title: Map
description: Explore the interactive community map showing locations across your area.
icon: material/map
+tags:
+ - guide
+ - user
+ - map
---
# Map
diff --git a/mkdocs/docs/docs/user-guide/profile.md b/mkdocs/docs/docs/user-guide/profile.md
index 3a5c51ec..fb38654d 100644
--- a/mkdocs/docs/docs/user-guide/profile.md
+++ b/mkdocs/docs/docs/user-guide/profile.md
@@ -2,6 +2,11 @@
title: Self-Service Contact Profile
description: Token-based CRM contact profiles where supporters can view their engagement history, edit their details, manage communication preferences, and opt out.
icon: material/card-account-details
+status: new
+tags:
+ - guide
+ - user
+ - CRM
---
# Self-Service Contact Profile
diff --git a/mkdocs/docs/docs/user-guide/shifts.md b/mkdocs/docs/docs/user-guide/shifts.md
index 4659f62e..fe730b9c 100644
--- a/mkdocs/docs/docs/user-guide/shifts.md
+++ b/mkdocs/docs/docs/user-guide/shifts.md
@@ -2,6 +2,10 @@
title: Shifts
description: Sign up for volunteer shifts, join canvassing teams, and get started quickly with QR codes.
icon: material/calendar-clock
+tags:
+ - guide
+ - user
+ - shifts
---
# Shifts
diff --git a/mkdocs/docs/docs/user-guide/shop.md b/mkdocs/docs/docs/user-guide/shop.md
index 4657066a..9a4341bc 100644
--- a/mkdocs/docs/docs/user-guide/shop.md
+++ b/mkdocs/docs/docs/user-guide/shop.md
@@ -2,6 +2,11 @@
title: Shop & Pricing
description: Browse campaign merchandise and membership subscription plans.
icon: material/shopping
+status: new
+tags:
+ - guide
+ - user
+ - payments
---
# Shop & Pricing
diff --git a/mkdocs/docs/docs/volunteer/achievements.md b/mkdocs/docs/docs/volunteer/achievements.md
index 5852204a..19de2270 100644
--- a/mkdocs/docs/docs/volunteer/achievements.md
+++ b/mkdocs/docs/docs/volunteer/achievements.md
@@ -2,6 +2,11 @@
title: Achievements & Leaderboard
description: Badge-based gamification and volunteer leaderboards to recognize and encourage platform participation.
icon: material/trophy
+status: new
+tags:
+ - guide
+ - volunteer
+ - social
---
# Achievements & Leaderboard
diff --git a/mkdocs/docs/docs/volunteer/canvassing.md b/mkdocs/docs/docs/volunteer/canvassing.md
index 8cc2cb04..cc991831 100644
--- a/mkdocs/docs/docs/volunteer/canvassing.md
+++ b/mkdocs/docs/docs/volunteer/canvassing.md
@@ -2,6 +2,11 @@
title: Canvassing
description: GPS-guided door-to-door canvassing with the volunteer map, visit recording, and walking routes.
icon: material/map-marker-path
+tags:
+ - guide
+ - volunteer
+ - map
+ - canvassing
---
# Canvassing
diff --git a/mkdocs/docs/docs/volunteer/index.md b/mkdocs/docs/docs/volunteer/index.md
index bdbae524..c6fec357 100644
--- a/mkdocs/docs/docs/volunteer/index.md
+++ b/mkdocs/docs/docs/volunteer/index.md
@@ -2,6 +2,9 @@
title: Volunteer Guide
description: Getting started as a volunteer — shifts, canvassing, social connections, and achievements.
icon: material/walk
+tags:
+ - guide
+ - volunteer
---
# Volunteer Guide
diff --git a/mkdocs/docs/docs/volunteer/shifts.md b/mkdocs/docs/docs/volunteer/shifts.md
index a6275850..eed9fbec 100644
--- a/mkdocs/docs/docs/volunteer/shifts.md
+++ b/mkdocs/docs/docs/volunteer/shifts.md
@@ -2,6 +2,10 @@
title: Your Shifts
description: View your assigned volunteer shifts, activity history, and canvassing stats.
icon: material/calendar-check
+tags:
+ - guide
+ - volunteer
+ - shifts
---
# Your Shifts
diff --git a/mkdocs/docs/docs/volunteer/social.md b/mkdocs/docs/docs/volunteer/social.md
index 7a36a461..cc976a2f 100644
--- a/mkdocs/docs/docs/volunteer/social.md
+++ b/mkdocs/docs/docs/volunteer/social.md
@@ -2,6 +2,11 @@
title: Social Connections
description: Connect with fellow volunteers through friend requests, activity feeds, groups, and real-time notifications.
icon: material/account-heart
+status: new
+tags:
+ - guide
+ - volunteer
+ - social
---
# Social Connections
diff --git a/mkdocs/docs/includes/abbreviations.md b/mkdocs/docs/includes/abbreviations.md
new file mode 100644
index 00000000..25cbc0ad
--- /dev/null
+++ b/mkdocs/docs/includes/abbreviations.md
@@ -0,0 +1,50 @@
+*[API]: Application Programming Interface
+*[JWT]: JSON Web Token
+*[RBAC]: Role-Based Access Control
+*[CORS]: Cross-Origin Resource Sharing
+*[SMTP]: Simple Mail Transfer Protocol
+*[CSV]: Comma-Separated Values
+*[ORM]: Object-Relational Mapping
+*[SSL]: Secure Sockets Layer
+*[TLS]: Transport Layer Security
+*[DNS]: Domain Name System
+*[CRUD]: Create, Read, Update, Delete
+*[SSO]: Single Sign-On
+*[SPA]: Single Page Application
+*[CLI]: Command Line Interface
+*[GUI]: Graphical User Interface
+*[QR]: Quick Response
+*[GPS]: Global Positioning System
+*[GDPR]: General Data Protection Regulation
+*[CDN]: Content Delivery Network
+*[VPS]: Virtual Private Server
+*[CGNAT]: Carrier-Grade Network Address Translation
+*[NAR]: National Address Register
+*[CRM]: Customer Relationship Management
+*[OG]: Open Graph
+*[DDoS]: Distributed Denial of Service
+*[SSE]: Server-Sent Events
+*[UUID]: Universally Unique Identifier
+*[FOSS]: Free and Open Source Software
+*[HSTS]: HTTP Strict Transport Security
+*[CSP]: Content Security Policy
+*[BullMQ]: Bull Message Queue
+*[FFprobe]: FFmpeg Probe — media metadata extraction tool
+*[FFmpeg]: Fast Forward MPEG — multimedia processing framework
+*[XMPP]: Extensible Messaging and Presence Protocol
+*[ACME]: Automatic Certificate Management Environment
+*[SSH]: Secure Shell
+*[YAML]: YAML Ain't Markup Language
+*[JSON]: JavaScript Object Notation
+*[HTML]: HyperText Markup Language
+*[CSS]: Cascading Style Sheets
+*[UI]: User Interface
+*[UX]: User Experience
+*[CI/CD]: Continuous Integration / Continuous Deployment
+*[UID]: User Identifier
+*[GID]: Group Identifier
+*[RSVP]: Respondez S'il Vous Plait
+*[CTR]: Click-Through Rate
+*[KPI]: Key Performance Indicator
+*[AES]: Advanced Encryption Standard
+*[PIN]: Personal Identification Number
diff --git a/mkdocs/docs/lander.md b/mkdocs/docs/lander.md
deleted file mode 100644
index 2350380c..00000000
--- a/mkdocs/docs/lander.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-template: lander.html
-hide:
- - navigation
- - toc
-title: "lander"
----
diff --git a/mkdocs/docs/main.md b/mkdocs/docs/main.md
deleted file mode 100644
index d8ab1699..00000000
--- a/mkdocs/docs/main.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-template: main.html
-hide:
- - navigation
- - toc
-title: "main"
----
diff --git a/mkdocs/docs/overrides/test-page.html b/mkdocs/docs/overrides/test-page.html
deleted file mode 100644
index 1230c3d7..00000000
--- a/mkdocs/docs/overrides/test-page.html
+++ /dev/null
@@ -1,7 +0,0 @@
-{% extends "main.html" %}
-{% block content %}
-
-