SystemStatus-PRD

SystemStatus — Product Requirements Document (PRD)

• Purpose: Define scope, requirements, and acceptance criteria for the SystemStatus web app that supports SystemRPG character lifecycle, dice/encounter flow, DM–player collaboration, and optional AI features.
• Context: This PRD consolidates and operationalizes content from SystemStatus - Concept & Features and SystemStatus - Research. It aligns with rules and references in: Flux Check System, Power Scales, Action Economy, Combat Sequence, Damage Application Order, Damage Dice Scale, Conditions, Stats, Core Formulas, Skills System, Path Points, 8-Projects/ttrpg_gameDev/systemRPG/3-Mechanix/Paths/Paths, Trainee Path, Character_Creation_Guide, Player_Glossary, Welcome_to_the_System.

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

• SystemStatus - Concept & Features
• SystemStatus - Research
• Rules/Mechanics references listed in the Purpose section