SystemStatus-PRD

#systemRPG #appDev #webapp #PRD #ttrpg #VTT #dice

SystemStatus — Product Requirements Document (PRD)

Goals

  • Unified live hub for characters, skills, Paths, dice, and encounters
  • Smooth DM workflows: award PP, unlock Paths, automate notifications
  • Player-friendly sheet with transparent derived stats and resource tracking
  • Extensible data model for homebrew and optional plugins/webhooks

Non-Goals

  • Full VTT map/LOS engine (beyond simple positioning tools) in MVP
  • Complex CRDT-based multi-user text editors in MVP (basic notes/logs only)
  • Public marketplace for third-party plugins at initial release

Primary Users & Roles

  • SO/DM: controls campaigns, unlocks Paths, awards PP, runs encounters
  • Player: edits/uses their character, performs checks/rolls, spends PP
  • Homebrew Designer: defines/imports Skills/Traits/Paths (admin-gated)

Success Metrics (examples)

  • TTRPG-session readiness: create character → roll Flux → spend PP in < 10 minutes (P90)
  • DM efficiency: award PP and send notification in < 20 seconds (P90)
  • Reliability: 99.9% uptime for real-time updates; event delivery < 500 ms (P95)
  • Data safety: 0 critical incidents of redacted info leakage

Scope Overview (MVP → Phase 2 → Phase 3)

  • Phase 1 (MVP): Core sheet, Flux roller with tiers/effects, Skills with RNG level checks, PP wallet, Path management (basic), export/import (JSON), notifications (manual + basic rules), basic encounter tracker.
  • Phase 2: Combat tracker full flow (1s rounds, conditions, regen), Knowledge Bank viewer for markdown with DM visibility, encounter export to markdown.
  • Phase 3: AI path suggestions and level-up wizard, homebrew rule-pack import/validation UI, outbound webhooks, optional plugin/widget surfaces.

Functional Requirements (with Acceptance Criteria)

Visibility & Access (Ref F-80–F-82)

  • F-80: SO can toggle visibility per-field/section with workspace defaults.
    • Accept: DM toggles a field path (e.g., stats.spiritual.*) → Player view hides; DM view shows with redaction indicators.
  • F-81: Player view auto-hides redacted fields; DM view shows redaction state.
    • Accept: Switching from DM → Player preview redacts all configured paths consistently across UI and exports.
  • F-82: Redaction-aware exports and notifications.
    • Accept: Exported markdown and notifications omit hidden values and labels; audit shows what was redacted.

Notifications & Automation (Ref F-90–F-93)

  • F-90: SO Notification Builder with templates, variables, audience, preview, history.
    • Accept: Create template with {{character.name}}; preview renders with sample data; send to player.
  • F-91: Rules engine triggers on events with filters and throttles.
    • Accept: Event skill.levelUp auto-sends a “Level Up” to the player no more than once per 10s per character.
  • F-92: Manual “Compose & Send” quick-inserts (Level Up, PP Award, Path Unlock, Condition Applied).
    • Accept: SO can select a quick-insert, edit variables, and deliver to chosen audience.
  • F-93: Notification logs (global and per character) with filters.
    • Accept: DM filters by category/event to view history for last session.

Character & Progression (Ref F-100–F-104)

  • F-100: 18-stat framework with spiritual stats optionally enabled and hidden by default.
    • Accept: Workspace toggle reveals spiritual section for selected characters; defaults are respected.
  • F-101: Derived stat engine per Core Formulas with per-second regen tracking in combat.
    • Accept: Sheet displays base/bonus/total; combat mode shows per-second regen values.
  • F-102: Flux Check roller (3d6) with special effects and tier calculator.
    • Accept: Users can apply Resonant/Discordant; tier advantage adjusts success thresholds and bonus dice; history logged.
  • F-103: Skills with rarity/XP; each level grants +1 PP; PP wallet and spend history.
    • Accept: Running an RNG level check updates skill level, wallet increments PP, and events are logged.
  • F-104: Paths with unlock conditions, branching, and extensions; suggestions informed by stats/history.
    • Accept: When prerequisites met, SO can unlock a Path; UI blocks spend until conditions satisfied; suggestions list eligible items.

Combat & Encounter (Ref F-110–F-112)

  • F-110: Combat sequence (declare → adjudicate → roll simultaneous → narrate by initiative); d20 initiative; re-roll triggers.
    • Accept: Round operation enforces order; initiative re-roll occurs on configured triggers (e.g., combatant changes).
  • F-111: CAS/action-chains enforcement; conditions manager; damage calculator with DR/resists.
    • Accept: CAS = floor(Initiative ÷ 5) enforced; next action gated by ≥1 success; condition durations tracked; DR applied per formula.
  • F-112: Encounter log export to markdown with rolls, outcomes, conditions, and damage steps.
    • Accept: Post-encounter export contains timestamped entries and derived calculations.

Collaboration & Review (Ref F-120–F-121)

  • F-120: Player working copy → DM diff review → approve/reject → master record update.
    • Accept: Player submits edit; DM sees human-readable diffs; approve applies change and emits events/notifications.
  • F-121: Audit/Event log for all mutations; link events to notifications.
    • Accept: Each mutation has an immutable event with actor, payload, timestamp, and related notification id.

Admin & Data (Ref F-130–F-131)

  • F-130: Rule packs import (skills/paths/traits); schema validation; merge preview.
    • Accept: Upload JSON/YAML pack; validation errors are surfaced; merge shows item-level additions/updates/conflicts.
  • F-131: Export/import campaign data including visibility maps and notification rules.
    • Accept: Export produces a single JSON; import restores equivalent state in a new workspace.

Knowledge Bank (Optional)

  • Viewer for markdown world notes; DM visibility controls; Obsidian-style navigation.
    • Accept: Note links via wikilinks open within the app; redacted sections do not render for players.

AI-Assisted Features (Phase 3)

  • Path suggestions and Level-Up wizard with rationale; DM chat over campaign context.
    • Accept: Given a character context, the system returns N ranked Path suggestions with prerequisite checks and reasoning; DM can copy/edit outputs.

Non-Functional Requirements (NFR)

  • Performance: WebSocket event fan-out < 500 ms P95 per room; initial character sheet load < 1.5s P90 on broadband.
  • Availability: 99.9% monthly uptime for real-time features.
  • Security: JWT/OAuth auth; RBAC for SO/DM vs Player; all traffic over HTTPS/WSS; input validation and output sanitization.
  • Privacy: Redaction enforced across UI/exports/notifications; no hidden fields leaked to players.
  • Observability: Structured logs for all events and errors; metrics for event queue lag and dice roll throughput; SLO dashboards.

Data Model (Reference Shape)

See SystemStatus - Concept & Features#Data Model Notes (PRD-Oriented). Core entities:

  • Workspace/Campaign, User, Character (stats, derived, skills, PP wallet, paths, visibility), Lookup catalogs (skills/paths/species/origins), Event, NotificationTemplate, NotificationRule, Notification, PendingChange.

Character schema snapshot includes base/bonus decomposition for stats and derived, skills with rarity/xp/xpToNext/powerLevel, and authoritative PP wallet. Derived values must be recomputable deterministically from authoritative inputs.

Real-Time & Events

  • Transport: WebSockets (rooms per workspace/campaign); internal pub/sub for scaled nodes.
  • Event types (emit to audit log): character.created, stats.updated, skill.used, skill.levelUp, pp.awarded, pp.spent, path.unlocked, path.progressed, combat.roundStart, combat.conditionApplied, injury.triggered, initiative.reRoll, visibility.changed, note.added.
  • Ordering: Server sequences events per room; throttles per event type/character as configured.

API Surfaces (High-Level)

  • REST (or GraphQL) for CRUD on: workspaces, users, characters, skills catalog, paths catalog, notification templates/rules, events (read-only), pending changes (review/approve).
  • WebSocket channels: room:workspace-{id} for live updates; per-character subchannels optional.
  • Export/Import endpoints for campaign data; rule-pack import with validation.
  • Webhooks (Phase 3): Outbound notifications on selected events; async delivery.

UX Flows (Key)

  • Character Creation: Name/species/origin/paradigm → 12 stats entry → live derived preview → save (emits character.created).
  • Play Loop: Use skill → XP accrual → RNG level check → Level Up → +1 PP → PP spend on Path → emit notifications.
  • DM Notification Builder: Choose template or quick-insert → fill variables → choose audience → preview with redactions → send → logs.
  • Combat Round: Setup → declare → adjudicate → simultaneous dice → narrate by initiative; re-roll triggers; CAS/action chains enforced; export log.
  • Review Workflow: Player submits working copy → DM sees diffs → approve/reject with comment → events created and linked.

Security & Compliance

  • AuthN: OAuth2/JWT; optional SSO providers (e.g., Discord/Google).
  • AuthZ: Role-based permissions; field-level visibility maps; server-side checks for all mutations.
  • Data protection: Password hashing (Argon2/bcrypt); secrets vaulting; dependency updates; backups.
  • Input/Output: Validation and sanitization; markdown rendering sanitized; redaction-safe notifications/exports.

Telemetry & QA

  • Metrics: event throughput/lag, dice rolls per minute, rule-engine trigger counts, notification delivery success.
  • Logs: Immutable audit events; error tracking; user action logs (coarse-grained).
  • Testing: Unit tests for formulas and rule engine; integration tests for diff/approval and notifications; load tests for WebSocket fan-out.

Milestones & Deliverables

  • Phase 1 (MVP)
    • Character sheet with derived engine; Skills and RNG level checks; PP wallet; basic Paths; Flux Roller with tiers/effects; manual + basic rules notifications; JSON export/import.
    • Deliverables: Working SPA + backend, real-time updates, audit log, minimal DM tooling.
  • Phase 2
    • Full combat tracker, conditions/regen, Knowledge Bank viewer with DM visibility, encounter export.
  • Phase 3
    • AI suggestions and level-up wizard; rule-pack import UI with validation; webhooks; plugin/widget surfaces.

Risks & Mitigations

  • Rule complexity drift → maintain single source formulas in shared module; add verification tests.
  • Redaction leaks → centralize redaction in server templates/exports; redaction unit tests.
  • Real-time scale → room-scoped eventing; Redis pub/sub; backpressure metrics and alerts.
  • AI reliability (Phase 3) → human-in-the-loop UI; caching; safety filters; clear AI labeling.

Open Questions

  • Scope of spiritual stats visibility per-character vs global default nuances
  • Minimum viable subset of conditions for Phase 1 vs Phase 2
  • Specific homebrew validation constraints (strict vs permissive)

References