For developers, this means interacting with a dual-server architecture that separates static configuration (Dashboard) from real-time execution (Realm). This guide serves as the primary reference for the platform's architecture, the official NuGet/NPM package ecosystem, and the core data structures that underpin the API.

Platform Architecture: The "Two Worlds"

To ensure scalability, ResQueServe divides responsibilities between two distinct environments. Developers must understand which environment owns the data they are trying to manipulate.

The Dashboard Environment (Static Data)

Role: The "Source of Truth" for infrastructure.
Responsibility: Manages the definition of resources that exist before a session starts.
Primary Entities: Points of Interest (POI), Units (Vehicles/Responders), Keywords (Dispatch Logic), Radio Groups, and User Permissions.
API Base URL: https://<dashboard-server>/api-docs (e.g., www.sim-dispatcher.com for public SaaS).
Developer Usage: Use this API to sync data from external systems, import map data, or manage fleet configurations.

The Realm Environment (Real-Time Operations)

Role: The "Engine".
Responsibility: Hosts active sessions where resources are instantiated and state changes occur (e.g., a Unit moving from "Status 1" to "Status 3").
Primary Entities: Sessions, Active Missions, Real-time Unit Positions, Patient States.
API Base URL: https://<realm-server>/api-docs (e.g., platform.sim-dispatcher.com).
Developer Usage: Use this API to read live telemetry, inject operations, or trigger external alerts based on simulation events.

Official Package Ecosystem

We strictly adhere to a modular package design to prevent "dependency hell" and ensure that lightweight integrations (like plugins) don't need to reference the entire core logic.

.NET (C#) Packages

These packages target .NET 9 and are available via the public Nuget feed.

Package Name	Namespace	Type	Description
`XENBIT.ResQueServe.Abstractions`	`XENBIT.ResQueServe.Abstractions`	Contracts	The foundation. Contains only Interfaces (`IPoi`, `IUnit`), Enums (`PoiCategory`, `UnitEquipment`), and Base Exceptions. Use Case: Use this if you are writing a plugin or an extension. It has zero heavy dependencies and ensures type safety across versions.
`XENBIT.ResQueServe.Core`	`XENBIT.ResQueServe.Core`	Logic	The implementation.Contains the concrete `record`types (e.g., `public record Unit`), JSON Converters, and business logic validation. Use Case: Use this if you need to instantiate concrete objects or perform local validation before sending data to the API.
`XENBIT.ResQueServe.SDK.Client`	`XENBIT.ResQueServe.SDK.Client`	Client	The consumer. Wraps the API into typed C# methods. Includes `ApiClientBase`, `DependencyInjection`extensions, and fully tested HTTP clients. Use Case: The standard entry point for building standalone applications or API integrations.

Web & TypeScript Ecosystem

Package Name	Link	Description
`resqueserve-core`	npmjs.com	A 1:1 TypeScript reflection of the C# `Core` and `Abstractions` libraries. Provides interfaces for all API responses, ensuring your frontend code is strongly typed against the backend models.

The "Shelf Origin" Data Pattern

One of the most powerful features of the ResQueServe data model is the Shelf Origin system. Almost every major entity (Unit, POI, Keyword) inherits from ShelfOriginBase. This pattern allows you to link ResQueServe entities to external data sources (e.g., OpenStreetMap, an internal SQL database, or a CSV file) without losing context.

JSON Polymorphism

The ShelfOrigin property is polymorphic. Depending on your needs, it can serialize different data types for the versioning field. The API uses @type discrimination (via System.Text.Json attributes) to handle this.

Structure of `ShelfOriginBase`:

Namespace (string): The source identifier (e.g., "OpenStreetMap", "Internal_HR_DB").
Id (string): The unique key in that external system.
Version (T): A generic version stamp (supported: long, int, string, Guid, DateTimeOffset).

Example JSON Payload:

JSON

{
  "name": "Central Fire Station",
  "origin": {
    "namespace": "OpenStreetMap",
    "id": "node/349201",
    "version": "2023-10-01T12:00:00Z" 
  }
}

Note: This allows you to perform "Delta Updates" by comparing the Version field of the API entity with your local database.

Domain Entities Deep Dive

Points of Interest (POI)

The POI is the geographical anchor of most entities.

Categorization: Defined by the PoiCategory enum. This is not just a label; it defines behavior.
- Example: PoiCategory.Nightclub (ID 10) carries metadata [OpeningHours(..., 21, 0, 4, 0)], meaning simulations will likely generate incidents there only at night.
Hospitals: If Category == PoiCategory.Hospital (30), the HospitalDepartments list becomes active. This is a list of PoiHospitalDepartment enums (e.g., TraumaSurgery, StrokeUnit), dictating which patients can be transported there.
Coordinates: We use a custom Coordinates struct. It includes validation logic (IsValid()) to reject 0,0 (Null Island) or out-of-bounds lat/longs.

Units (Resources)

A Unit represents a movable resource. It is a composite entity requiring several links to function:

Home Station: Every unit must be linked to a Poi (via the Poi property).
Radio Configuration: Linked via IRadioGroup.
Callsigns:
- Callsign: The unique technical identifier.
- CallsignVerbal: The phonetic name used in Text-to-Speech generation.
- CallsignGps: The identifier used for tracking via the Real-Time API.

Keywords (Dispatch Logic)

Keywords define the "Rules of Engagement" for an emergency.

Requirements Matrix: Properties like DispatchAmountDoctor (int), DispatchAmountAmbulanceUrgent (int), and DispatchAmountHelicopter (int) define what the system will suggest.
Equipment Logic: The RequiredEquipment collection ensures that specific tools (e.g., UnitEquipment.HeavyRescueSet) are present on scene.

Technical Reference & Documentation Links

Resource	URL	Description
Class Reference	docs.resqueserve.com	Generated documentation for all classes, methods, and properties in the `Abstractions` and `Core` namespaces.
NPM Package	npmjs.com/package/resqueserve-core	TypeScript definitions for frontend integration.
API	`https://<server>/api-docs`	Swagger/OpenAPI UI for testing endpoints manually.