Architecture Reference

Detailed documentation for Shadow Master's core subsystems. For high-level architecture overview, see CLAUDE.md.

Combat System

Full combat tracking with initiative, actions, and damage resolution.

Key Concepts:

•Combat Session: Tracks all combatants, turn order, and combat state
•Action Resolution: Executes and validates combat actions
•Initiative Tracking: Automatic turn management with initiative passes
•Damage Tracking: Condition monitor integration

Critical Files:

•/lib/combat/CombatSessionContext.tsx - Combat state management
•
/lib/rules/action-resolution/ - Action execution framework
- •action-executor.ts - Core execution logic
- •action-validator.ts - Action validation
- •dice-engine.ts - Dice rolling engine
- •pool-builder.ts - Dice pool construction
- •edge-actions.ts - Edge spending actions
- •combat/ - Combat-specific handlers (damage, weapons)
•/app/api/combat/ - Combat session API endpoints
•/components/combat/ - Combat UI (tracker, dice pools, quick reference)

Matrix Operations System

Full matrix hacking with overwatch, marks, and program management.

Key Concepts:

•Cyberdecks: Hardware validation and configuration
•Programs: Slot management and allocation
•Overwatch Score: OS tracking and convergence handling
•Marks: Mark placement and tracking system
•Matrix Actions: Action validation with mark requirements

Critical Files:

•
/lib/rules/matrix/ - Matrix operations
- •cyberdeck-validator.ts - Hardware validation
- •program-validator.ts - Program allocation
- •overwatch-calculator.ts - OS calculation
- •overwatch-tracker.ts - Session tracking
- •mark-tracker.ts - Mark management
- •action-validator.ts - Matrix action validation
- •dice-pool-calculator.ts - Matrix dice pools

Rigging Control System

Vehicle and drone control for riggers.

Key Concepts:

•VCR (Vehicle Control Rig): Validation and bonuses
•RCC (Rigger Command Console): Drone slaving and command execution
•Drone Networks: Network management and noise handling
•Jump-In Mode: VR mode management for direct control
•Biofeedback: Damage and dumpshock handling

Critical Files:

•
/lib/rules/rigging/ - Rigging mechanics
- •vcr-validator.ts - VCR validation
- •rcc-validator.ts - RCC validation and slaving
- •drone-network.ts - Network management
- •drone-condition.ts - Drone damage tracking
- •jumped-in-manager.ts - Jump-in mode
- •biofeedback-handler.ts - Biofeedback damage
- •noise-calculator.ts - Signal noise calculations
- •action-validator.ts - Rigging action validation
- •dice-pool-calculator.ts - Vehicle/drone dice pools

Inventory and Equipment System

Equipment state management for gear, weapons, and devices.

Key Concepts:

•Readiness States: ready, holstered, stored, etc.
•Wireless Toggles: Enable/disable for augmentations and devices
•Device Condition: functional, bricked, repaired
•Gear Validation: Availability and rating validation

Critical Files:

•/lib/rules/inventory/state-manager.ts - Equipment state management
•/lib/rules/gear/validation.ts - Gear availability validation
•/lib/rules/gear/weapon-customization.ts - Weapon modifications

Gameplay Utilities

Runtime calculations for combat and tests.

Key Concepts:

•Effective Ratings: Wireless bonuses and matrix damage effects
•Dice Pool Bonuses: Equipment rating bonuses
•Test Thresholds: Detect, analyze, bypass calculations
•Armor Stacking: SR5 Core p.169-170 rules with accessories and encumbrance
•Wound Modifiers: High/Low Pain Tolerance support

Critical Files:

•/lib/rules/gameplay.ts - Core gameplay calculations
•/lib/rules/constraint-validation.ts - Creation constraint validation

Grunt/NPC System

Pre-built NPC templates for GMs with professional rating tiers.

Key Concepts:

•Professional Rating (PR): PR0 (street rabble) to PR6 (dragon guard)
•Grunt Templates: Pre-configured NPCs with stats, gear, and skills
•Grunt Teams: Groups of NPCs for encounter management

Critical Files:

•/lib/rules/grunts.ts - Grunt mechanics and validation
•/lib/storage/grunt-templates.ts - Template persistence
•/data/editions/{editionCode}/grunt-templates/ - PR0-PR6 template files
•/app/campaigns/[id]/grunt-teams/ - Team management UI
•/app/api/campaigns/[id]/grunt-teams/ - Grunt team API

Contact Network System

Contact relationships and favor economy for social gameplay.

Key Concepts:

•Contact Network: Relationships with NPCs and their loyalty/connection ratings
•Favor Economy: Tracking favors owed and earned
•Social Capital: Reputation and influence mechanics

Critical Files:

•/lib/rules/contact-network.ts - Contact relationship logic
•/lib/rules/favors.ts - Favor economy system
•/lib/rules/social-actions.ts - Social interaction mechanics
•/lib/storage/contacts.ts - Contact persistence
•/lib/storage/favor-ledger.ts - Favor tracking
•/app/api/characters/[characterId]/contacts/ - Contact API

System Synchronization

Character-ruleset drift detection and migration.

Key Concepts:

•Drift Analysis: Detect metatype, skill, quality changes between rulesets
•Legality Validation: Quick sync status checks
•Migration Engine: Generate and execute migration plans
•Sync Audit: Trail of synchronization events

Critical Files:

•
/lib/rules/sync/ - Synchronization system
- •drift-analyzer.ts - Change detection
- •legality-validator.ts - Rule compliance checking
- •migration-engine.ts - Migration planning and execution
- •sync-audit.ts - Audit trail
- •hooks.ts - React hooks for client-side sync

Optional Rules System

Campaign-level rule customization.

Key Concepts:

•Campaign Configuration: Enable/disable optional rules per campaign
•GM Control: Default override support
•Rule Extraction: Pull optional rules from loaded rulesets
•Content Access: Validate content against enabled rules

Critical Files:

•/lib/rules/optional-rules.ts - Optional rule management

Data Management Layers

Authentication State (/lib/auth/AuthProvider.tsx):

•React Context managing user session globally
•Provides useAuth() hook for components
•Session stored in httpOnly cookie

Ruleset State (/lib/rules/RulesetContext.tsx):

•React Context caching loaded ruleset
•Provides hooks: useRuleset(), useMetatypes(), useSkills(), etc.
•Fetches from /api/rulesets/[editionCode]

Sidebar State (/lib/contexts/SidebarContext.tsx):

•React Context managing sidebar open/collapsed state globally
•Provides useSidebar() hook with: isOpen, isCollapsed, toggle, close, toggleCollapse
•Desktop collapsed state persisted to localStorage (shadow-master-sidebar-collapsed-global)
•Built-in Escape key handler and resize listener for mobile drawer
•Focus trap and accessibility features managed in AuthenticatedLayout

Local Storage:

•User preferences and UI state (theme, sidebar collapsed state)
•Draft recovery handled server-side via auto-save

File-Based Storage Pattern

Design: JSON files on disk with atomic writes (temp file + rename pattern)

Storage Layer (/lib/storage/):

Core modules:

•base.ts - Core utilities: readJsonFile(), writeJsonFile(), ensureDirectory()
•users.ts - User CRUD operations
•characters.ts - Character CRUD + specialized operations (damage, karma, etc.)
•campaigns.ts - Campaign CRUD operations
•editions.ts - Edition and ruleset loading

Extended modules:

•contacts.ts, favor-ledger.ts - Contact system persistence
•combat.ts, action-history.ts - Combat session storage
•grunt-templates.ts, grunts.ts - NPC system storage
•notifications.ts, activity.ts - User activity tracking
•audit.ts, user-audit.ts - Audit trail logging
•ruleset-snapshots.ts, snapshot-cache.ts - Ruleset versioning
•locations.ts, locations_connections.ts - Campaign location storage
•social-capital.ts - Social capital tracking
•violation-record.ts - Rule violation tracking

Storage Structure:

code

/data
├── /users/{userId}.json
├── /characters/{userId}/{characterId}.json
├── /campaigns/{campaignId}.json
└── /editions/{editionCode}/
    ├── edition.json
    ├── core-rulebook.json
    ├── {sourcebook}.json
    └── /grunt-templates/
        └── pr{0-6}-{name}.json

Important: This is NOT production-scalable. File I/O happens on every request. Future migration to a database is planned.

Security Infrastructure

Rate Limiting (/lib/security/rate-limit.ts):

•DDoS protection for API endpoints
•Configurable limits per endpoint

Audit Logging (/lib/security/audit-logger.ts):

•Full audit trail for user actions
•Security event tracking
•Stored via /lib/storage/audit.ts

Character Authorization (/lib/auth/character-authorization.ts):

•Granular character access control
•Owner, campaign GM, and viewer permissions

Additional Auth Modules (/lib/auth/):

•validation.ts - Auth validation logic
•middleware.ts - Auth middleware
•campaign.ts - Campaign-specific authorization
•email-verification.ts - Email verification token handling

Admin User Management (/app/api/users/[id]/):

•lockout/route.ts - DELETE to clear login lockouts
•resend-verification/route.ts - POST to resend verification emails (rate limited)
•verify-email/route.ts - POST to manually verify user email
•suspend/route.ts - POST/DELETE to suspend/reactivate accounts

Admin UI (/app/users/):

•UserTable.tsx - User list with lockout/verification badges and menu actions
•UserEditModal.tsx - User details with lockout info and verification controls
•UserAuditModal.tsx - User audit trail viewer

API Route Patterns

All API routes follow this pattern:

•Extract session from cookie via getSession()
•Validate user exists via getUserById()
•Return 401 if unauthenticated
•Perform user-scoped operation
•Return JSON response

Example:

typescript

// /app/api/characters/route.ts
export async function GET(request: NextRequest) {
  const session = await getSession();
  if (!session?.userId) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const user = getUserById(session.userId);
  if (!user) {
    return NextResponse.json({ error: "User not found" }, { status: 404 });
  }

  const characters = getUserCharacters(session.userId);
  return NextResponse.json({ characters });
}