Jasrags/architecture-reference

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:

/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:

1. Extract session from cookie via getSession()
2. Validate user exists via getUserById()
3. Return 401 if unauthenticated
4. Perform user-scoped operation
5. 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 });
}