SessionZero Design Document

1. Introduction

1.1 Purpose

SessionZero is a free and open-source TTRPG companion app designed to streamline tabletop role-playing game management. It emphasizes flexibility, modularity, and federation through a system-agnostic datapack format, supporting both offline and self-hostable online play. The goal is to empower players and GMs with full control over their data, rulesets, and session management.

1.2 Scope

The project will begin as a cross-platform desktop application (Windows and Linux), offering tools for creating and managing TTRPG data such as characters, datasets, templates, and sessions. The backend supports user accounts, a database for shared content (SessionZeroDB), and prepares for future federation capabilities. Phase 2 introduces federation, while Phase 3 focuses on mobile support and plugin extensibility.

1.3 Objectives

• Provide a modular, open-source companion app for any TTRPG system.
• Implement a JSON-based datapack format for extensible content storage.
• Support both local use and self-hostable online instances.
• Create a foundation for future federation and mobile support.

---

2. System Overview

SessionZero consists of three main layers:

1. Frontend (Client): Cross-platform desktop application (.NET Avalonia).
2. Backend (Server): ASP.NET backend managing user accounts, SessionZeroDB, and P2P connections.
3. Datapack System: A structured archive format for storing and sharing game data.

---

3. Functional Requirements

3.1 Core Features (Phase 1)

• User Authentication: Email and password-based account creation and login.

• Datapack Management:

  • Create, edit, and package datapacks.
  • Import/export datapacks.
  • Link media assets (e.g., images) within datapacks.

• Data Creation/Editing:

  • Datasets, characters, character templates, and session templates.

• Session Management:

  • GM control over player sheets and session datapacks.
  • Player view limited to their own characters.
  • Integrated chat/log system for simple in-session communication.

• SessionZeroDB:

  • Database for hosting and retrieving community content.
  • Attribution and license information for each uploaded pack.

3.2 Federation (Phase 2)

• Federated servers can communicate for global content discovery.
• Configurable access controls for visibility (private, public, or indexed).
• P2P session management.

3.3 Mobile/Plugin System (Phase 3)

• Native mobile clients for Android/iOS.
• Plugin architecture for extending UI and data management capabilities.

---

4. Non-Functional Requirements

• Cross-Platform Support: Windows and Linux for MVP.
• Performance: Efficient JSON parsing and fast local caching.
• Scalability: Designed for multiple users per server instance.
• Security: Hashed passwords, secure token authentication.
• Data Portability: All user data exportable in open formats.

---

5. Datapack Specification

5.1 Structure

pack-name/
├── szpack.json        # Metadata
├── media/
│   └── images/        # Image assets
└── objects/
    ├── datasets/
    ├── characters/
    ├── character-templates/
    └── session-templates/

5.2 Metadata File (szpack.json)

Example:

{
  "name": "Example Pack",
  "version": "1.0",
  "author": "UserName",
  "license": "CC-BY-SA 4.0",
  "description": "A fantasy setting for SessionZero.",
  "created": "2025-10-15",
  "sessionzeroVersion": "1.0"
}

5.3 Object Format Example

{
  "type": "character",
  "name": "Thalindra",
  "attributes": {
    "strength": 14,
    "intelligence": 12,
    "dexterity": 10
  },
  "image": "../media/images/thalindra.png"
}

---

6. Architecture

6.1 High-level Overview

SessionZero is split into three cooperating layers:

• Client (Avalonia / .NET 9) - the primary desktop application used by players and GMs. It is responsible for local data storage, datapack management, UI rendering, and establishing/maintaining real-time session connections. The client is offline-first and can run entirely without a backend.

• Backend (ASP.NET Core Web API) - an optional, self-hostable server that provides account management, persistent session storage, the SessionZeroDB (index of community datapacks), and signaling for P2P connections (WebRTC). Servers may be run privately or publicly and can optionally federate with other servers.

• Federation Layer / SessionZeroDB - a network of self-hosted servers that optionally synchronize metadata (datapack manifests, public session listings, user profiles) between instances. Federation is opt-in per server and respects server-configured visibility and access controls.

6.2 Client Architecture (Avalonia)

Key responsibilities:

• Local datastore and caching (SQLite for structured local data, filesystem for datapacks and media).
• Datapack Manager: discovery, validation, import/export (.szp), and in-memory registry of loaded objects.
• UI layer (MVVM pattern) using Avalonia controls and styles.
• Networking components:
  • SignalR client for communicating with an ASP.NET backend.
  • WebRTC peer connection subsystem for direct P2P session data transfer (signaling via backend when needed).
• Tools integration: a CLI helper (szpack) for building/extracting packs and optional pack signing/verification.

Runtime layout:

• ViewModels: represent datapacks, objects, sessions, and user state.
• Services: DataPackService, StorageService (SQLite/File), NetworkingService (SignalR/WebRTC), AuthService, LoggingService.

6.3 Backend Architecture (ASP.NET Core)

Key responsibilities:

• User account management (email/password auth, JWT tokens).
• Session hosting and persistence (store session metadata and optional session snapshots in PostgreSQL).
• SessionZeroDB: index and serve community datapacks and metadata; host uploaded .szp files on disk or object storage.
• Signaling service for WebRTC: setup offers/answers and ICE candidate exchange to enable P2P connections between clients.
• Federation endpoints for inter-server communication (signed JSON over HTTPS).

Components:

• REST API controllers: Accounts, Sessions, Datapacks, Federation, Admin
• SignalR Hubs: Real-time session coordination and lightweight session synchronization for clients that prefer server-mediated sync.
• Storage: PostgreSQL for server metadata and user accounts; filesystem/object storage for datapack blobs; optional S3-compatible storage for large deployments.
• Auth & Security: Password hashing (Argon2), JWT issuance and refresh, TLS for all endpoints, RBAC for admin operations.

6.4 Networking Model

• Offline Mode: Client runs entirely locally; datapacks and session files live on the local filesystem / SQLite; no networking required.

• LAN / P2P Mode: Clients can host sessions on a LAN. Discovery via mDNS/Zeroconf or optional UDP broadcast. For internet play, the backend's signaling service facilitates NAT traversal and WebRTC handshake. Actual session traffic (character updates, chat) is sent peer-to-peer where possible to minimize server load.

• Server-Hosted Mode: For users who run or subscribe to an ASP.NET instance, sessions may be persisted on the server and clients can reconnect to continue campaigns. The server can optionally mediate real-time traffic for clients that cannot form direct P2P connections.

• Federation: Servers exchange signed metadata (pack manifests, publicly shared pack indexes, optionally session discovery) on a scheduled or event-driven basis. Federation rules and visibility are configured by each server operator.

6.5 Data Flow Examples

Importing a Datapack (Client-only):

1. User selects Import pack.szp.
2. Client extracts the archive into the local datapacks directory.
3. DataPackService validates szpack.json and object schemas and registers objects into the in-memory registry.
4. The UI updates to show new templates and datasets.

Joining a Hosted Session (Server + P2P):

1. Client authenticates to ASP.NET server via email/password, obtains JWT.
2. Client requests to join a session; server verifies permissions and returns session metadata and peer list.
3. Server provides WebRTC signaling data (or the client uses STUN/TURN if needed).
4. Clients establish P2P channels and synchronize session state. Server stores session snapshots as needed.

6.6 Extensibility & Plugins

• Design client services around interfaces to permit replacement or extension (e.g., IDataPackStore, INetworkingTransport).
• Plugin API (Phase 3) will allow third-party modules to register new object types, UI panels, and data transformations while running within a sandboxed environment.

6.7 Deployment & Operations

• Client: Distributed via platform-native packaging (AppImage/Flatpak for Linux, MSI for Windows). Continuous builds via GitHub Actions.
• Server: Dockerized ASP.NET image with environment-driven configuration. Use PostgreSQL as the recommended production datastore and SQLite for small personal deployments.
• SessionZeroDB: Each server can host its own repository; the official public index is recommended to be a well-maintained instance but is optional.

7. UI/UX Design

7.1 Philosophy

• Desktop-first layout with responsive adjustments.
• Blend of creative and functional design to support immersive TTRPG use.

7.2 Core Views

• Dashboard
• Datapack Manager
• Data Editor (characters, templates, datasets)
• Session View (GM & Player modes)
• Chat/Log interface

---

8. Licensing

8.1 Software License

• GNU Affero General Public License (AGPL-3.0) - ensures open-source continuity and attribution, prevents uncredited commercial rebranding.

8.2 User Content License

• Creative Commons BY-SA 4.0 - allows sharing and adaptation with attribution.

---

9. Development Phases

Phase 1: Core Platform (MVP)

• Client (UI, datapack editing, session management)
• Backend (accounts, SessionZeroDB, P2P prep)
• JSON datapack format implementation

Phase 2: Federation

• Cross-server communication
• Access controls and search indexing

Phase 3: Mobile and Plugins

• Cross-platform mobile apps
• Plugin and API extensibility

---

10. Open Questions

1. Should we support local single-user mode without an account?
2. How should dependency handling between datapacks work (e.g., one datapack relying on another)?
3. Should we include an optional offline mode for play sessions without a backend?
4. How should session persistence be handled for ongoing campaigns?

---

11. Next Steps

1. Confirm open questions above.
2. Create schema definitions for datapack object types.
3. Design backend API endpoints.
4. Create wireframes for client UI.
5. Begin core MVP development (client + backend).