Introduction

The ECC Department of Professional Standards (DPS) platform is the case-management and personnel-training system for the Lakeview City Roleplay roleplay community. It tracks reports ("dockets") made against community members, drives investigations, records disciplinary actions, and runs a live simulated-investigation training program for new agents.

This documentation is the technical manual for that platform. It is written for developers, maintainers, and administrators who need to understand, operate, troubleshoot, or extend the system. It describes the production architecture as it actually exists in the repositories — not an idealized version of it.

What DPS is responsible for

The platform performs four core jobs:

1. Case management. Reports are created by the Discord bot, investigated by assigned agents through the dashboard, and resolved through a defined status lifecycle. Every meaningful state change is recorded in a timeline and an append-only event stream.
2. Discipline records. Agents with sufficient clearance can issue, edit, and revoke punishment records against users. Punishment records are retained — they are never hard-deleted — and Discord-side delivery (DMs, role changes) is delegated to the bot through a dedicated delivery queue.
3. Personnel records. The agents table is the authoritative directory of DPS agents: rank, clearance, status, training-eligibility, and onboarding identifiers. Rank and clearance changes are Director-gated and audited.
4. Training. The Training Center is a parallel, simulated environment where trainers run data-driven scenarios with onboarding trainees. It shares the authentication, API, and database of the production system but keeps simulated state fully separate from production cases.

Major system components

Component	Repo / location	Role
Dashboard	ecc-dps-dashboard/	React 19 + TypeScript + Vite single-page application. Contains both the normal DPS dashboard and the Training Center, selected by hostname at boot.
Flask API	dps-code-api/	The only client of the database in production. Owns authentication, authorization, validation, and domain orchestration.
Supabase (PostgreSQL)	external	Source of truth for all persistent state. Named RPC functions own authoritative, atomic mutations; row-level security and least-privilege grants back the API.
Supabase Realtime	external	Best-effort synchronization channel for live training sessions. Never authoritative.
Discord bot (BotGhost)	external	The "bot": creates reports, performs Discord-side queue work (DMs, role changes, logs), and relays reporter replies. Authenticates with the shared API key.
Discord OAuth proxy	discord-oauth-proxy/	Optional Cloudflare Worker that performs the Discord OAuth token exchange so outbound requests do not originate from a shared datacenter IP.
ER:LC relay	dps-code-api/tools/erlc_relay + erlc_relay.py	Residential egress relay for the Roblox ER:LC server API used by the bot.

Intended users

• DPS agents — view and work dockets, add notes and evidence, contact reporters, claim cases, and (with clearance) view analytics, punishments, and queues.
• Supervisors (Senior Agent+) — additional access to supervisor-flagged reports, the supervisor queue, and the full audit log.
• Leadership (Head Investigator / Lead Agent) — case reassignment, punishment management, and System Administration panel access.
• Directors — Director-only administrative capabilities: agent rank/clearance changes, report correction, schema visibility, and admin access-list management.
• Trainers — run Training Center sessions for onboarding trainees.
• The Discord bot — an API-key-authenticated integration that creates reports and performs Discord-side work picked up from the action queues.

High-level architecture

                    ┌───────────────┐
                    │   Dashboard   │
                    └───────┬───────┘
                            │  credentialed fetch (HttpOnly session cookie)
                    ┌───────▼───────┐
                    │   Flask API   │  (dps-code-api, Render)
                    └───────┬───────┘
                            │  service-role Supabase client
                    ┌───────▼───────┐
                    │    Services   │  (domain logic, validation, gating)
                    └───────┬───────┘
                            │  named RPC calls / table access
                    ┌───────▼───────┐
                    │ RPC / DB Auth │  (transactional functions, RLS, grants)
                    └───────┬───────┘
                    ┌───────▼───────┐
                    │  PostgreSQL   │  (Supabase)
                    └───────┬───────┘
                 ┌──────────┴──────────┐
                 │                     │
           Application Data       Audit / Events

Three security boundaries matter, in order:

1. The API validates identity (session or API key), authorization (clearance, rank, assignment), and input before anything else.
2. The database re-checks the critical parts: transactional RPCs guard status transitions under row locks, validate field whitelists, and raise machine-readable errors; grants and RLS restrict which roles can do what.
3. The frontend is a client. UI visibility is advisory; the API and database are authoritative. The browser never receives the service-role key or session secrets.

The frontend must never bypass the API's authorization model, and database/RPC authority is part of the security boundary: application code should not recreate authoritative multi-step database operations when an atomic database operation already exists.

How to use this documentation

• Getting Started — how the system is put together and where everything lives.
• DPS Platform — the functional areas: reports, investigations, punishments, appeals, evidence, agents, training.
• Backend — the Flask application, its services, and the full API reference.
• Database — schema, migrations, RPC layer, and RLS.
• Events & Audit — how activity is recorded and why the audit records are trustworthy.
• Security — authentication, authorization, input validation, and the threat model.
• Frontend — the dashboard application and how to extend it.
• Development Guide — setup, testing, and architectural rules.
• Deployment and Operations — shipping and running the system.
• Reference — canonical tables: endpoints, schema, RPCs, event types, permissions, statuses, identifiers, environment variables.