name: architecture-reference description: Deep-dive reference for Shadow Master subsystems including Combat, Matrix, Rigging, Inventory, Contacts, Sync, and Security. Use when working on specific game mechanics or need detailed file locations for a subsystem. allowed-tools: Read, Grep, Glob
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 frameworkaction-executor.ts- Core execution logicaction-validator.ts- Action validationdice-engine.ts- Dice rolling enginepool-builder.ts- Dice pool constructionedge-actions.ts- Edge spending actionscombat/- 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 operationscyberdeck-validator.ts- Hardware validationprogram-validator.ts- Program allocationoverwatch-calculator.ts- OS calculationoverwatch-tracker.ts- Session trackingmark-tracker.ts- Mark managementaction-validator.ts- Matrix action validationdice-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 mechanicsvcr-validator.ts- VCR validationrcc-validator.ts- RCC validation and slavingdrone-network.ts- Network managementdrone-condition.ts- Drone damage trackingjumped-in-manager.ts- Jump-in modebiofeedback-handler.ts- Biofeedback damagenoise-calculator.ts- Signal noise calculationsaction-validator.ts- Rigging action validationdice-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 systemdrift-analyzer.ts- Change detectionlegality-validator.ts- Rule compliance checkingmigration-engine.ts- Migration planning and executionsync-audit.ts- Audit trailhooks.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 operationscharacters.ts- Character CRUD + specialized operations (damage, karma, etc.)campaigns.ts- Campaign CRUD operationseditions.ts- Edition and ruleset loading
Extended modules:
contacts.ts,favor-ledger.ts- Contact system persistencecombat.ts,action-history.ts- Combat session storagegrunt-templates.ts,grunts.ts- NPC system storagenotifications.ts,activity.ts- User activity trackingaudit.ts,user-audit.ts- Audit trail loggingruleset-snapshots.ts,snapshot-cache.ts- Ruleset versioninglocations.ts,locations_connections.ts- Campaign location storagesocial-capital.ts- Social capital trackingviolation-record.ts- Rule violation tracking
Storage Structure:
/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 logicmiddleware.ts- Auth middlewarecampaign.ts- Campaign-specific authorizationemail-verification.ts- Email verification token handling
Admin User Management (/app/api/users/[id]/):
lockout/route.ts- DELETE to clear login lockoutsresend-verification/route.ts- POST to resend verification emails (rate limited)verify-email/route.ts- POST to manually verify user emailsuspend/route.ts- POST/DELETE to suspend/reactivate accounts
Admin UI (/app/users/):
UserTable.tsx- User list with lockout/verification badges and menu actionsUserEditModal.tsx- User details with lockout info and verification controlsUserAuditModal.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:
// /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 });
}