RetroBoards

RetroBoards is self-hostable forum / community software — a Community Inbox: durable forum topics (Discourse-style permanence) presented through the familiar Slack/email-style three-pane shell, with email-style triage. Stack: vanilla PHP 8 + MySQL, server-rendered with progressive-enhancement JavaScript, designed to run on a single VPS.

Status: Phase 4 (advanced community & content) — engineering closeout complete with explicit deferrals. Phase 4 adds topic workflow, public tag lifecycle + board/tag follows, windowed/board leaderboards backed by reputation_events, private board/bookmark folders plus saved feed filters, and custom emoji as default-on features, all reversible via the features override. It also includes deploy-dark group-DM membership/reporting hardening, advanced Markdown tables/task lists/rules, follower removal, and community-memory summaries/related/wiki rollback. The current automated suite is green at 866 tests / 4519 assertions. Large rich-expression/Gate-B surfaces (previews, expanded non-image files, slash commands/GIFs, automated context, custom profile fields, split/merge services, custom badge rules, and reference cards) are explicitly deferred in docs/adr/0003-phase-4-closeout-deferrals.md. See PHASE_4_STATUS.md, docs/evidence/phase4-gate-a.md, and docs/design-system/imladris/ACTIVATED_FEATURES.md for the evidence and design-system mapping.

Running Phase 1

Requirements: PHP 8.2+ (with pdo_mysql, mbstring, dom, openssl), Composer, and MySQL 8 / MariaDB 10.6+.

composer install                      # install league/commonmark + phpunit
cp .env.example .env                  # then set DB_* and run: php bin/console key:generate
php bin/console migrate               # apply the 10 Phase-1 migrations
php -S 127.0.0.1:8000 -t public public/index.php

Open http://127.0.0.1:8000 — a fresh install redirects to /setup, where you create the first admin, name the community, and get starter boards. Useful commands:

php bin/console migrate:status        # show applied migrations
php bin/console migrate:fresh         # drop all tables and re-migrate (destructive)
php bin/console migrate:rollback      # roll back (greenfield only)
composer test                         # run the full PHPUnit suite

Tests run against a separate database (retroboards_test by default; override with DB_TEST_DATABASE).

This is an orientation pointer, not a source of ground truth

The authoritative documents are:

Document	Owns
DECISIONS.md	Locked decisions; the resolved stack; the replaceable-interface seams (email, search, media storage, feed — §2); the priority-tier-vs-delivery-phase rule. Authoritative on any conflict.
DESIGN.md	The product & technical design — the product source of truth; the roadmap and completion-evidence policy (§13).
SCHEMA.md	The consolidated database schema (final table shapes) and the per-phase build cut (§6).
USER.md · ADMIN.md · COMMUNITY.md · COMPOSER.md	The member, operator, community-layer, and composer surfaces.
PHASE_1_PLAN.md … PHASE_7_PLAN.md (+ PHASE_1_MIGRATIONS.md)	The seven-phase delivery sequence, entry/exit gates, and migration manifests.

Precedence: when this README and any document above disagree, the document above wins — and DECISIONS.md wins over all. In particular, the replaceable-interface seams live in DECISIONS §2, and the roadmap and completion-evidence policy in DESIGN §13 — not here.

The seven delivery phases (at a glance)

1. Phase 1 — MVP backend (auth, posting, read path, first-run setup, inline moderation).
2. Phase 2 — community essentials (reactions/stars/unread, notifications + email, search, DMs, reports/moderators, OAuth, the community layer, announcements).
3. Phase 3 — polish, trust & scale (the unified rich composer, uploads, anti-spam, TOTP, appeals, branding, plugins/webhooks/API, a11y/SEO/perf).
4. Phase 4 — advanced community & content (topic status/triage, group DMs, tags/feeds, reputation ledger + leaderboards, community memory).
5. Phase 5 — ecosystem, identity & governance (signed packages, custom roles/capabilities, passkeys, generic OIDC, invitations).
6. Phase 6 — realtime & scale (capacity-triggered: SSE, external search, Redis, object storage/CDN, read replicas, materialized feeds).
7. Phase 7 — platform expansion (i18n, PWA/offline, Web Push, import/export, multi-community/tenancy, optional public federation).

"v1" means the Phase 1–2 initial release (DECISIONS §7).