Getting Started

This guide walks you through setting up and running Titan locally.

Prerequisites

• .NET 10 SDK
• Docker Desktop (or Docker Engine)
• Node.js 18+ (for the admin dashboard)

Running with .NET Aspire

The recommended way to run Titan is using .NET Aspire, which orchestrates all services and infrastructure.

1. Clone and Open

git clone https://github.com/47565647456/titan.git
cd titan

Open src/Titan.sln in Visual Studio or Rider.

2. Configure Secrets

Create or update src/Titan.AppHost/appsettings.Development.json:

{
  "Jwt": {
    "Key": "your-secret-key-at-least-32-characters-long"
  }
}

3. Start the AppHost

Set Titan.AppHost as the startup project and press F5.

Aspire will:

1. Start Redis containers for clustering and rate limiting
2. Start PostgreSQL for data persistence
3. Launch all Orleans silo hosts (Identity, Inventory, Trading)
4. Start the API gateway
5. Start the admin dashboard

4. Access the Services

Service	URL	Description
Aspire Dashboard	https://localhost:17225	Logs, traces, metrics
Titan API	https://localhost:7001	SignalR hubs and HTTP endpoints
Admin Dashboard	http://localhost:5173	React admin interface
Scalar API Docs	https://localhost:7001/scalar/v1	OpenAPI documentation

First API Calls

Authentication

Login via HTTP to get JWT tokens:

# Development: Use Mock provider
curl -X POST https://localhost:7001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"token": "mock:test-user-123", "provider": "Mock"}'

Response:

{
  "accessToken": "eyJhbG...",
  "refreshToken": "abc123...",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accessTokenExpiresInSeconds": 900
}

SignalR Connection

Connect to hubs with the access token:

const connection = new signalR.HubConnectionBuilder()
    .withUrl("https://localhost:7001/accountHub", {
        accessTokenFactory: () => accessToken
    })
    .build();

await connection.start();

// Get account info
const account = await connection.invoke("GetAccount");
console.log(account);

Create a Character

// Create a character in the "standard" season
const character = await connection.invoke(
    "CreateCharacter", 
    "standard",           // seasonId
    "MyHero",            // name
    0                    // restrictions (None)
);

Configuration

JWT Settings

Configure in appsettings.json:

{
  "Jwt": {
    "Key": "your-secret-key-minimum-32-characters",
    "Issuer": "Titan",
    "Audience": "TitanClient",
    "AccessTokenExpirationMinutes": 15,
    "RefreshTokenExpirationDays": 7
  }
}

Rate Limiting

{
  "RateLimiting": {
    "Enabled": true,
    "DefaultPolicy": "Global",
    "Policies": {
      "Global": {
        "Rules": [
          { "RequestsPerWindow": 1000, "WindowSeconds": 60 }
        ]
      },
      "Auth": {
        "Rules": [
          { "RequestsPerWindow": 10, "WindowSeconds": 60 },
          { "RequestsPerWindow": 100, "WindowSeconds": 3600 }
        ],
        "TimeoutSeconds": 300
      }
    }
  }
}

CORS

{
  "Cors": {
    "AllowedOrigins": [
      "http://localhost:5173",
      "https://yourgame.com"
    ]
  }
}

Next Steps

• Authentication - Learn about EOS and JWT
• SignalR Hubs - Explore the real-time API
• Client SDK - Use the .NET SDK in your game