Pixels

A self-hostable, invite-only chat and community platform. Pre-2020-Discord-shaped functionality, original pixel-grid branding, PHP 8.2 + PostgreSQL 15 under the hood. All 7 phases implemented as real, working code — no mocked auth, no fake APIs, no JS-only gates.

What's implemented

Phase 1 — Foundation: PSR-4 architecture, PostgreSQL schema/migrations, server-enforced invite-only registration, username#1234 handles with a cryptographically random discriminator, email verification, Argon2id password hashing, database-backed sessions, CSRF protection, password reset, and the idempotent 14-day automatic invite job.

Phase 2 — Communities: servers, categories, text/voice channels, a bitmask role/permission system (PermissionService) with per-channel overwrites, membership management, kicks, and server invites.

Phase 3 — Messaging: real-time messages (send/edit/delete/reply/react/pin), cursor-based pagination, full-text search, mentions (@user#1234, @everyone, @here), secure attachment uploads (server-side MIME sniffing, randomized filenames, non-executable storage), typing indicators, presence, read states, and a WebSocket gateway (bin/gateway.php, built on Ratchet) that fans out events published over PostgreSQL LISTEN/NOTIFY — decoupling the HTTP tier from the gateway tier without extra infrastructure.

Phase 4 — Social: friend requests, blocking, 1:1 and group DMs, profiles with mutual-server visibility, and notifications.

Phase 5 — Moderation: the report system with the required 10-messages-before + reported message + 10-messages-after context view (MessageService::contextAround), profile and server report views, bans/timeouts/disables, a full audit log, and an admin panel (dashboard, user search/detail, report review with one-click actions, invite management).

Phase 6 — Developer platform: applications with regenerable client secrets, bot accounts (real users rows so bots can be @mentioned and join servers like anyone else), bot-token/OAuth2/personal-API-key authentication (all resolved through one Auth helper), the OAuth2 authorization-code flow (/oauth2/authorize, /oauth2/token, /oauth2/userinfo), channel webhooks, per-token sliding-window rate limiting, and in-app API docs at /developers/docs.

Phase 7 — Production: security headers, an Nginx config with a locked-down /uploads/ alias, an isolated PHP-FPM pool, systemd units for the gateway process and the invite-grant/session-GC timers, and a full deployment walkthrough — see deploy/DEPLOYMENT.md.

Requirements

• PHP 8.2+ with pdo_pgsql, pgsql, mbstring, openssl
• PostgreSQL 15+
• Composer 2.x
• Nginx + PHP-FPM for production

Setup

composer install
cp .env.example .env
php pixels generate-secret   # paste the output into APP_KEY in .env
# edit .env: DB_*, MAIL_*, APP_URL

createdb pixels
php pixels migrate
php pixels create-admin      # first admin bypasses the invite requirement

Serve public/ as the document root (e.g. php -S 127.0.0.1:8080 -t public for local dev). Start the real-time gateway separately:

php bin/gateway.php

For production deployment (Nginx, PHP-FPM, systemd, HTTPS, backups), see deploy/DEPLOYMENT.md.

CLI

php pixels migrate            # run pending migrations
php pixels create-admin       # interactively create the first administrator
php pixels generate-secret    # generate an APP_KEY
php pixels invites:grant      # idempotent 14-day auto-grant job (cron/systemd daily)
php pixels session:gc         # prune expired sessions + stale rate-limit hits (cron/systemd hourly)
php pixels clear-cache        # clear storage/cache

API & bots

See /developers in the running app (developer portal — create applications, bots, and OAuth2 clients) and /developers/docs for the full REST + gateway reference with curl/JS/Python/PHP examples.

Project layout

app/Controllers/       Web (session-based) controllers: auth, admin, developer portal, OAuth2
app/Controllers/Api/   REST API controllers (bot/OAuth2/session/API-key auth)
app/Core/              Router, Request/Response, DB, Session, Config, Auth
app/Middleware/        Csrf, Auth, Admin, ApiAuth
app/Services/          All business logic — one service per domain
app/WebSocket/         The gateway server + its token auth
bin/gateway.php        Real-time gateway entrypoint
database/migrations/   7 migrations, one per phase, applied in order
deploy/                Nginx, PHP-FPM, systemd units, deployment guide
resources/views/       PHP views (auth, app shell, admin, developer portal)
routes/                web.php (sessions/HTML) and api.php (REST v1)