Shadow Master is a comprehensive character management system for the Shadowrun tabletop RPG, designed to support all editions (1E-6E plus Anarchy). The application provides multi-edition character creation with edition-specific rules, a flexible ruleset system supporting sourcebooks and errata, and a robust character lifecycle management.
Currently, the project is in its MVP phase, focusing on Shadowrun 5th Edition Priority-based character creation.
- Modular Ruleset System: Data-driven ruleset loading and merging algorithm supporting multiple books and editions.
- Character Creation Framework: Sheet-based single-page creation (SR5 Priority) with auto-save drafts.
- Dynamic Character Sheet: Responsive UI with theme-aware sections, automated derived stats, and dice-roller integration.
- Character Advancement: Full karma-based progression with GM approval workflows.
- Campaign Management: Integrated campaign support including calendar management, locations, and member tracking.
- Secure Authentication: Session-based auth with role-based access control (User, GM, Admin).
- NPC / Grunt System: Rapid NPC generation and team management.
- Combat Tracker: Real-time initiative and turn tracking for encounters.
- Inventory & Gear Management: Detailed tracking of items, ammo, and modifications.
- System Synchronization: Protocol for managing data drift between characters and updated rulebooks.
Shadow Master follows a modern, performance-oriented stack designed for atomic data integrity:
- Frontend: Next.js (App Router) with React 19 and Tailwind CSS 4.
- UI Components: React Aria Components for first-class accessibility and headless logic.
- Persistence: Atomic file-based storage using JSON for all user, character, and ruleset data.
- Rules Engine: A custom merging algorithm that processes edition metadata and sourcebook payloads into a unified runtime context.
For a detailed breakdown of subsystem statuses, current blockers, and development priorities, please refer to: 👉 PROJECT_STATE.md
First, install dependencies:
pnpm installStart the development server:
pnpm devOpen http://localhost:3000 with your browser to see the result.
# Build and start with one command
pnpm docker:dev
# Or step by step
pnpm docker:build # Build image
pnpm docker:up # Start containers
pnpm docker:logs # View logs
pnpm docker:down # Stop containersThis starts:
- Shadow Master at http://localhost:3000
- Mailpit (email testing) at http://localhost:8025
| Environment | How to Run | Badge Color |
|---|---|---|
| local | pnpm dev |
Purple |
| docker | pnpm docker:dev |
Blue |
| staging | Portainer/GHCR | Amber |
| production | Web hosting | Hidden |
The environment badge shows version, git SHA, and build time (hidden in production).
For production deployment, see our Portainer Setup Guide or the CI/CD Pipeline documentation.
/app- Application routes, pages, and API handlers./components- Shared React UI components and layouts./lib- Core business logic, storage layers, and ruleset engines./data- Static and persistent JSON storage for rulesets and user entities./docs- Comprehensive technical specifications and architectural guides.
See LICENSE for license information.