Architecture

Titan is built on Microsoft Orleans, a virtual actor framework that provides a simplified programming model for distributed systems.

System Overview

Project Structure

Project	Type	Description
Titan.AppHost	Aspire Orchestrator	Manages containers and service configuration
Titan.API	Orleans Client	Public gateway with SignalR hubs and HTTP endpoints
Titan.Grains	Class Library	Core business logic as Orleans grain implementations
Titan.Abstractions	Class Library	Shared interfaces, models, and contracts
Titan.IdentityHost	Orleans Silo	Hosts identity-related grains (Account, Character, Session)
Titan.InventoryHost	Orleans Silo	Hosts inventory grains (Bag, Stash, ItemGenerator)
Titan.TradingHost	Orleans Silo	Hosts trading grains with Orleans Streams
Titan.Client	Class Library	Strongly-typed .NET SDK
titan-dashboard	React/Vite	Admin dashboard for monitoring and management

Orleans Grain Model

Orleans uses virtual actors called Grains. Key characteristics:

1. Single-threaded: Each grain processes one request at a time
2. Location-transparent: Grains can be on any silo, Orleans routes calls
3. Persistent: State is automatically saved to storage
4. Lazy activation: Grains are created on first access, deactivated when idle

Grain Keys

Grains are identified by keys. Titan uses:

Communication Flow

SignalR Hub Request Flow

Authentication Flow

Persistence

Titan uses MemoryPack for high-performance binary serialization:

• ~40% smaller payloads compared to JSON
• Fast serialization via source generators
• Used for both wire protocol and storage

Storage Configuration

Grains persist state to PostgreSQL via Orleans' ADO.NET provider:

[PersistentState("account", "OrleansStorage")]
IPersistentState<AccountGrainState> _state;

Rate Limiting

Redis-backed rate limiting protects the API:

Policies are configured per-endpoint pattern in appsettings.json and can be modified at runtime via the admin API.

Aspire Orchestration

The Titan.AppHost uses .NET Aspire to orchestrate all services:

Key benefits:

• Single startup project for the entire solution
• Automatic container provisioning (Redis, PostgreSQL)
• Service discovery between projects
• Integrated dashboard for logs and traces