SessionZeroWasm/technical-specifications.md

Session Zero - Design Document

Executive Summary

Session Zero is a comprehensive tabletop RPG management application designed with an "offline-first" philosophy. The application enables Game Masters and players to create custom game systems, manage characters, and run sessions with integrated resources. Core functionality operates entirely offline, with optional online features available through tiered accounts for enhanced collaboration and content sharing.

Core Architecture

Design Philosophy

The application follows a modular, data-driven approach where users define their own game systems rather than being locked into predefined rulesets. Everything is built around flexibility and user customization, with offline functionality as the primary focus.

Key Principles

• Offline First: Full functionality without internet connection
• User-Defined Systems: No hardcoded game rules or restrictions
• Modular Content: Reusable datasets and templates
• Progressive Enhancement: Online features enhance but don't replace offline capabilities

Feature Specifications

1. Library System (Content Management)

The Library serves as the central content repository, organized into modular datasets that can be mixed and matched across different games and sessions.

Dataset Structure

• Purpose: Logical groupings of related content (e.g., "Core Fantasy Items", "Homebrew Monsters")
• Type System: Arbitrary string identifiers for categorization ("items", "spells", "monsters", "npcs", etc.)
• Content Entries: Individual data records with name and structured key-value pairs
• Flexibility: Users can create custom dataset types beyond the built-in defaults

Field Types

• Text: Single-line string input
• Text-Field: Multi-line text areas
• Number: Integer or floating-point values
• Boolean: True/false checkboxes
• Group: Nested collections of related fields
• Calculated: Dynamically computed values based on mathematical formulas referencing other fields
• System: Special fields handled by the application framework for configuration purposes
• Dataset-Reference: Reference to a specific dataset identified by its unique identifier
• Dataset-Type: Generic reference to any dataset of a specified type (e.g., items, spells)
• Dataset-Reference-Multiple: Multiple selection reference to a specific dataset
• Dataset-Type-Multiple: Multiple selection reference to any dataset of a specified type

Data Management

• Local Storage: All datasets stored locally in LocalStorage for fast access
• Cloud Sync: Optional synchronization for paid accounts
• Import/Export: Native support for dataset backup and sharing via .szf files
• Version Control: Each dataset has unique GUID and semantic versioning
• Online Library: Community content hub (download free, upload requires paid account)

2. Template Builder (Character Sheet Designer)

Templates define the structure and layout of character sheets for specific game systems, providing the blueprint for character creation.

Template Components

• Core Fields: Basic character attributes (stats, names, etc.) with configurable types
• Field Properties: Required/optional flags, default values, validation rules
• Grouped Data: Hierarchical sections (e.g., "Skills" containing multiple skill entries)
• Dataset Integration: Link datasets to templates for contextual dropdowns and data binding

Field Types

• Text: Single-line string input
• Text-Field: Multi-line text areas
• Number: Integer or floating-point values
• Boolean: True/false checkboxes
• Group: Nested collections of related fields

Template Features

• Section Management: Organize character sheet into logical sections
• Data Binding: Connect sections to dataset types for searchable dropdowns
• Validation: Enforce required fields and data type constraints
• Reusability: One template can generate unlimited characters

Dataset Integration

• Required Datasets: Templates specify dependencies via Name|GUID|Version format
• Reference Types:
  • Dataset-Reference: Direct reference to specific dataset entries by key
  • Dataset-Type: Generic reference to any dataset of a specified type
  • Multiple Selection: Support for selecting multiple items from datasets
• Section Binding: Entire sections can be bound to dataset types
• Selection Modes: Single selection, multiple selection with optional count limits
• System Properties: Special template properties handled by the application framework

Data Management

• Local Storage: All templates stored locally in LocalStorage for fast access
• Cloud Sync: Optional synchronization for paid accounts
• Import/Export: Native support for template backup and sharing via .szf files
• Version Control: Each template has unique GUID and semantic versioning
• Online Library: Community templates hub (download free, upload requires paid account)

Dataset Dependencies

• Reference Format: Name|GUID|Version triple identifies exact dataset requirements
• Dependency Resolution: Templates fetch dependencies from local storage by GUID and version
• Fallback Behavior: Missing dependencies prompt download from community library
• Graceful Degradation: Templates function with empty datasets if dependencies unavailable
• Type Discovery: Dataset types determined from metadata, not hardcoded in templates

3. Character Manager (Character Sheet Interface)

Character sheets are runtime instances of templates, populated with player data and linked to relevant datasets.

Character Sheet Structure

• Core Data: Template-defined attributes and basic information
• Inventory System: Dedicated item management linked to "items" datasets
• Private Journal: Freeform notes section for personal character development
• Custom Sections: Template-defined sections (spells, abilities, etc.)
• Dynamic Content: Real-time access to linked dataset entries

Character Operations

• Creation: Select template and populate initial data
• Management: Edit, duplicate, or delete existing characters
• Data Validation: Ensure character data conforms to template requirements
• Asset Support: Character portraits and custom images

Data Management

• Local Storage: All character sheets stored locally in LocalStorage for fast access
• Cloud Sync: Optional synchronization for paid accounts
• Import/Export: Native support for character backup and sharing via .szf files

4. Session Management (Game Runtime Environment)

Sessions provide the active gaming environment where GMs and players interact with characters, datasets, and shared resources.

Session Components

• Session Identity: Unique name/ID for organization
• Active Datasets: Loaded content libraries available during play
• Session Notes: GM workspace for encounter planning and event tracking
• Character Roster: Active participants and their character sheets
• Session History: Audit log of actions and changes during play

Operational Modes

Offline Mode (Default)

• Single-user environment (GM and Player roles combined)
• Manual character management and updates
• Local-only data access
• Full functionality without internet connection

Online Mode (Future Implementation)

• GM Role: Requires paid account to host sessions
  • Control information visibility
  • Push real-time updates to players
  • Manage session flow and permissions
• Player Role: Requires free account to join hosted sessions
  • Access personal character sheet
  • Receive live updates from GM
  • Participate in session chat

Future Online Features

• Real-time Collaboration: Live character sheet updates
• Chat Integration: Text communication with command support
• Dice Rolling: Built-in dice system with notation support
• Information Control: GM-managed visibility of content

Technical Implementation

Technology Stack

• Frontend: C# .NET Blazor Standalone WebAssembly (PWA-enabled)
• Local Storage: Browser LocalStorage for session data
• Authentication: ASP.NET Web API (future online features)
• Online Database: POSTGRESQL (for future online features)
• File Format: Custom .szf (Session Zero Format) for data interchange and storage

Data Architecture

Storage Strategy

• Local Primary: LocalStorage for all local data
• Runtime Loading: Templates and datasets loaded dynamically from LocalStorage
• Version Compatibility: GUID-based references ensure data integrity across versions
• Asset Management: Local caching with size limits (2MB per image, 500MB total cache)

Validation System

• Type Safety: Strict enforcement of declared field types
• Data Integrity: No null values permitted, unique names within scope
• Type Coercion: Automatic conversion between compatible types
• Hierarchical Validation: Groups must contain at least one child entry

Calculated Fields

• Formula Parsing: Support for mathematical expressions with field references
• Runtime Evaluation: Formulas re-evaluated whenever dependency values change
• Function Support: Built-in math functions (SUM, MIN, MAX, etc.)
• Cross-Field References: Reference other fields by name in calculations
• Nested References: Access properties of referenced dataset entries (e.g., Equipment.Weight)

File Format Specification (.szf)

Session Zero Format provides human-readable, structured data representation for all content types.

Dataset Example

!type: dataset
!schema: 1.0.0

[Metadata]
Name (text) = Core Fantasy Items
Type (text) = items
Version (text) = 1.0.0
Description (text-field) = Basic fantasy items for any campaign

[Entry: Longsword]
Name (text) = Longsword
Description (text-field) = A standard sword with a long blade
Category (text) = Weapon

[Entry.Longsword.Stats]
Damage (text) = 1d8
Weight (number) = 3
IsMartial (bool) = true

Template Example

!type: character_template
!schema: 1.0.0

[Metadata]
Name (text) = Fantasy Character Sheet
Version (text) = 2.0.0
GUID (text) = f9e8d7c6-b5a4-3210-9876-543210fedcba
Description (text-field) = Advanced character sheet for fantasy RPGs
Author (text) = Template Master
GameSystem (text) = Fantasy RPG Universal

[Required Datasets]
ClassesDataset (text) = Core Classes|c3d4e5f6-g7h8-9012-cdef-123456789012|1.5.0
RacesDataset (text) = Playable Races|d4e5f6g7-h8i9-0123-def0-234567890123|1.3.0

[Section: Core Identity]
Name (text) = 
Race (dataset-reference) = RacesDataset
Class (dataset-reference) = ClassesDataset
Level (number) = 1

[Section: Ability Scores]
Strength (number) = 10
Dexterity (number) = 10
Constitution (number) = 10

[Section.Ability Scores.Modifiers]
StrengthMod (calculated) = (Strength - 10) / 2
DexterityMod (calculated) = (Dexterity - 10) / 2

[Section: Inventory]
DatasetType (system) = items
SelectionMode (system) = multiple
MaxItems (number) = 50
CarryingCapacity (calculated) = Strength * 15

[Section: Equipment]
PrimaryWeapon (dataset-type) = items
SecondaryWeapon (dataset-type) = items

[Section: Spellcasting]
DatasetType (system) = spells
SpellSaveDC (calculated) = 8 + ProficiencyBonus + IntelligenceMod

[Section.Spellcasting.Known Spells]
Cantrips (dataset-type-multiple) = spells
Level1Spells (dataset-type-multiple) = spells

Business Model

Account Tiers

Guest (No Account) - $0

• Full offline functionality
• Download community content
• Export/import for data
• PWA installation

Free Account - $0

• All Guest features
• Join online sessions hosted by paid users
• Basic profile management

Paid Account - $5/month

• All Free features
• Host unlimited online sessions
• Upload content to community library
• Cross-device data synchronization
• Priority support

Monetization Strategy

• Freemium Model: Core functionality free, collaboration features paid
• Content Ecosystem: Revenue sharing with popular content creators
• Enterprise Features: Advanced GM tools and campaign management (future)

Development Roadmap

Phase 1: Core Foundation

• [] Library system implementation
• [] Template Builder functionality
• [] Character Manager interface
• [] Basic session framework

Phase 2: Enhanced Sessions

• Dataset loading into sessions
• Advanced session management
• Character-session integration
• Offline GM/Player workflow

Phase 3: Data Management

• Import/export functionality
• Asset management system
• Advanced validation
• Performance optimization

Phase 4: Polish & Usability

• UI/UX refinement
• Mobile responsiveness
• Accessibility compliance
• User testing integration

Phase 5: Online Features (Future)

• Account system implementation
• Community content library
• Real-time collaboration
• Advanced GM tools

Platform Strategy

Primary Targets

• Desktop: PWA for cross-platform desktop usage
• Mobile: PWA for mobile devices

Distribution

• PWA: Progressive Web App for cross-platform compatibility
• Web Access: Browser-based access for quick usage

Technical Considerations

Performance Requirements

• Startup Time: < Needs testing
• Database Operations: < Needs testing
• Memory Usage: < Needs testing
• Offline Capability: Full functionality without network

Security & Privacy

• Local Data: All personal data stored locally by default
• Content Sharing: Explicit user consent for uploads
• Account Security: Standard authentication practices for online features
• Optional Sync: Paid accounts can optionally opt-in to cloud synchronization of datasets and characters

Scalability

• Local Limits: 1000+ characters, 100+ datasets per user
• Online Sessions: 10+ concurrent players per session
• Content Library: Community-driven growth model

UI Design System

Color Palette

• Background: #1a202e (Dark theme primary)
• Primary: #3a4f6f (Interactive elements)
• Primary Light: #4a5f7f (Hover states)
• Secondary: #2d3f5c (Secondary elements)
• Accent: #5b89b3 (Highlights and CTAs)
• Text: #ffffff (Primary text)
• Headings: #c5d5e6 (Section headers)

Design Principles

• Dark Theme: Reduce eye strain during long gaming sessions
• Clear Hierarchy: Visual organization of complex information
• Responsive: Consistent experience across device sizes