Skip to content

Technical Architecture

Architectural Goal

EchoSpire should be built like a professional game platform with a clean separation between game rules, presentation, content authoring, and analytics.

The strongest current technical decision is that the game logic lives in a shared core rather than inside one client.

Platform Direction

  • Target platform: PC desktop, with Steam as the initial shipping target.
  • MVP preview client: WPF in C# on Windows.
  • Later presentation migration target after product validation: Unity in C#.
  • Backend: ASP.NET Web API in C#.
  • Primary structured data store: PostgreSQL.
  • Telemetry and balance analytics store: ClickHouse.
  • Cache and messaging layer: Redis.
  • Admin layer: Blazor Server or lightweight React SPA served against the API.

Core Principles

Core Owns Rules

Gameplay rules, combat sequencing, state transitions, determinism, and effect execution belong in the shared core library.

Clients Own Presentation

The current WPF MVP client should own presentation, input, screen flow, local UX state, packaging, and Steam-facing shell behavior for the first paid preview.

If the product is proven and the presentation layer later migrates to Unity, Unity should become the successor presentation client for animation, audio, richer effects, controller-first polish, and higher-end visual delivery.

Neither client should silently fork or reimplement combat rules.

Data Is Tunable, Behavior Is Coded

Cards, enemies, classes, factions, map parameters, economy values, and content definitions should live in data. The execution behavior of effects and core turn sequencing should live in code.

Everything Important Must Be Deterministic

Seeds must reproduce map generation, encounter generation, reward generation, and all run-level structural randomness.

Admin And Simulation Are First-Class Systems

Authoring workflows and automated balance workflows are part of the product architecture, not optional side tooling.

AI Must Respect System Boundaries

EchoSpire should use deterministic gameplay AI for rules execution, constrained generative AI for limited content assistance, and agentic AI for operational analysis outside the live gameplay loop.

See AI Systems And Agents, Simulation And Rival Hero AI, and Live-Site AI Agent for the official subsystem split.

Deterministic Generation

The deterministic contract covers:

  • realm layouts
  • node type placement
  • enemy encounter selection
  • enemy intent sequences
  • reward rolls
  • event selection
  • transit interruptions
  • mutation outcomes
  • shop inventories

The recommended implementation is a seeded RNG service with child streams forked by stable contextual keys such as realm, combat, reward, event, and mutation scope.

Data-Driven Effect System

The intended model is:

  • effect behavior is implemented in registered C# effect classes
  • content records refer to effect identifiers plus parameters
  • card resolution looks up effects by id and executes them against a structured context

This preserves flexibility without hard-coding every card.

See Effect Pipeline And Modular Deployment for the official architecture direction covering code-based effect units, trigger sub-pipelines, module manifests, and UX event emission.

API-First Model

The WPF MVP client, admin UI, and simulation engine should all act as API consumers.

Major endpoint groups should cover:

  • authentication
  • game data snapshots
  • admin CRUD and publishing
  • runs and save state
  • heroes and meta-progression
  • simulation control and analytics

Additional Data Contracts Needed

To support the current official design direction, the data model should be extended to cover:

  • hero progression rows and per-level class choices
  • hero XP and persistent level state
  • rival hero encounter definitions and loadouts
  • authored quest acts, beats, and recurring character references
  • AI policy definitions for simulator players, enemies, bosses, and rival heroes
  • difficulty scaling tables by realm tier and threat tier
  • realm definitions with provenance, sector tags, and passive global rules
  • quest sector data that explains how one area of a realm leads to the next
  • rift definitions with type-specific variable payloads
  • effect manifests, trigger manifests, and module compatibility metadata
  • operational analysis records, agent recommendation artifacts, and evidence-link data for support workflows

Offline Direction

The current official direction is:

  • single-player runs should remain playable from a local cached snapshot when services are unavailable
  • save data should not depend on server availability to function
  • admin and simulation workflows can remain primarily service-backed

Project Boundaries

The intended project structure is:

  • EchoSpire.Core: pure gameplay models, state, combat, effects, RNG, and simulation logic
  • EchoSpire.API: API surface, auth, repositories, infrastructure, and orchestration
  • EchoSpire.Admin: live data authoring and analytics UI
  • EchoSpire.Simulation: headless execution and balance analysis
  • EchoSpire.Wpf: Windows-first MVP presentation client for the first paid preview
  • EchoSpire.Unity: later migration target once the product is validated and presentation investment is justified

Current Guidance For The MVP Client

While WPF is the MVP client, preserve these boundaries:

  • keep the client focused on presentation, orchestration, API integration, local settings, and Steam packaging concerns
  • keep gameplay-rule truth in EchoSpire.Core
  • do not let view logic become the long-term owner of combat sequencing or map rules
  • prefer explicit view-model or presenter state over event-driven code-behind sprawl
  • keep a narrow translation seam between gameplay events and UI-facing state so a later Unity migration can replace the presentation layer without rewriting rules

Current Guidance For Unity

When Unity development scales up, preserve these boundaries:

  • thin adapter layer over core gameplay systems
  • view-model or presenter style UI state for combat and map screens
  • ScriptableObjects for presentation metadata only, not for gameplay rule truth
  • explicit translation from core game events into UI events
  • clear save and local cache boundaries

Rival Hero And Future PvP Support

The architecture should explicitly preserve support for hero-versus-hero combat.

That means shared rule systems must correctly support:

  • player-like decks and passives on both sides
  • class and faction mechanics in mirror-compatible combat
  • save, replay, and deterministic resolution for hero duels

Campaign rival hero encounters should use that shared rule base even if future PvP balance becomes a separate layer.

Testing Strategy

The required test shape is:

  • unit tests for effects, combat sequencing, and rule primitives
  • determinism tests for seeded generation and scripted run replay
  • integration tests for API CRUD, auth, and snapshot workflows
  • balance tests driven by simulation telemetry and outlier detection
  • compatibility tests for effect modules and trigger chains

Architectural Risk Summary

The main architectural risk is not choosing WPF for the MVP. The main risk is letting the MVP client harden into an accidental permanent rule owner, or allowing the client, live content workflows, and persistence edge cases to lag too far behind the strong core systems foundation.