Skip to content

Data Models

Canonical reference for SectorWars 2102 persistent entities. Every entity here is validated against the SQLAlchemy models under services/gameserver/src/models/ (in the Sectorwars2102 repo). When the docs and the model disagree, the model wins and this folder is updated.

Files

Doc Covers
galaxy.md Galaxy, Region, Cluster, Zone, Sector, WarpTunnel and the sector_warps association
special-formations.md SpecialFormation catalog: graph-topology landmarks (Bubble, Tunnel, Dead-End, Blister, etc.) stamped during generation
entities.md Index for the per-entity schema docs below
ships.md Ship, ShipRegistry, ShipSpecification (incl. Carrier hangar JSONB and Tractor Beam tow state)
planets.md Planet, player_planets association
stations.md Station, player_stations, TradeDock, ConstructionSlip, ShipConstructionProject
genesis-devices.md GenesisDevice, PlanetFormation
cargo-wrecks.md CargoWreck (target schema)
player.md User, Player, Team, TeamMember, Reputation, Message, first-login session models
economy.md Resource, Market, MarketTransaction (resource-enum and commodity-string variants), MarketPrice, PriceHistory, EconomicMetrics, PriceAlert
combat.md CombatLog, CombatStats, Drone, DroneDeployment, DroneCombat, Fleet, FleetMember, FleetBattle, FleetBattleCasualty
gameplay.md Faction, SectorFactionInfluence, regional governance (RegionalElection, RegionalVote, RegionalPolicy, RegionalTreaty, InterRegionalTravel, RegionalMembership)
admin.md User admin flag, AdminCredentials, AuditLog, moderation references
npcs.md NPCCharacter (named persistent NPCs with single-place presence), NPCRoster (per-region per-faction targets), NPCDeathLog (KIA audit trail). Schema for the named-NPC layer that powers Federation Marshals, Nexus Sentinels, and other persistent NPCs.
npc-lodging.md NPCBarracks (lawful-faction lodging — barracks rows with capacity, occupancy, faction allegiance) and OutlawBase (hostile-faction lodging — pirate dens, Cabal war rooms, gated by player discovery requirements). The first-class entities behind the schedule's home_barracks references.
migrations.md Alembic migration chain, current head, summary of each revision
jsonb-schema.md Inner key shapes for every JSONB column across the schema
../SYSTEMS/medal-service.md Medal (catalog) and PlayerMedal (association table with awarded_at, awarded_via, source_combat_log_id, source_event_key, awarded_by_user_id, context_payload, is_hidden_per_player) — schema lives in the systems spec alongside the dispatcher and realtime events; cross-listed here so the data-model index is complete. Per ADR-0028.

Conventions

  • Primary keys are UUIDs unless noted (Sector.sector_id is a human-readable integer alongside the UUID id).
  • Timestamps are DateTime(timezone=True) with server_default=func.now() — not repeated per entity below unless behaviorally relevant.
  • JSONB columns are widely used as flexible substructures; we list their default keys when they encode game rules (e.g., Sector.defenses, Station.commodities).
  • Soft delete: User.deleted, Message.deleted_by_sender/recipient. Hard delete cascades elsewhere.

High-level relationships

erDiagram
    USER ||--o| PLAYER : owns
    USER ||--o| ADMIN_CREDENTIALS : has
    USER ||--o{ REGION : owns
    PLAYER }o--o{ TEAM : member_of
    PLAYER ||--o{ SHIP : owns
    PLAYER }o--o{ PLANET : owns
    PLAYER }o--o{ STATION : owns
    PLAYER ||--o{ REPUTATION : has
    PLAYER ||--o{ DRONE : owns
    PLAYER ||--o{ MARKET_TRANSACTION : performs
    PLAYER ||--o{ FIRST_LOGIN_SESSION : completes
    PLAYER ||--o{ REGIONAL_MEMBERSHIP : holds
    REPUTATION }o--|| FACTION : with
    SHIP }o--|| SECTOR : located_in
    PLANET }o--|| SECTOR : in
    STATION }o--|| SECTOR : in
    SECTOR }o--|| CLUSTER : grouped_by
    SECTOR }o--o| ZONE : security_class
    SECTOR }o--o| REGION : in
    CLUSTER }o--|| REGION : in
    ZONE }o--|| REGION : in
    SECTOR }o--o{ SECTOR : warps_to
    WARP_TUNNEL }o--|| SECTOR : origin
    WARP_TUNNEL }o--|| SECTOR : destination
    STATION ||--o| MARKET : hosts
    MARKET ||--o{ MARKET_TRANSACTION : records
    COMBAT_LOG }o--|| PLAYER : attacker
    COMBAT_LOG }o--|| PLAYER : defender
    COMBAT_LOG }o--|| SECTOR : in
    FLEET }o--|| TEAM : owned_by
    FLEET ||--o{ FLEET_MEMBER : has
    FLEET_MEMBER }o--|| SHIP : ship
    GENESIS_DEVICE }o--|| PLAYER : owner
    GENESIS_DEVICE ||--o| PLANET : created

ASCII fallback for the same shape:

                       +------+
                       | USER |---owns---> REGION (player-owned)
                       +--+---+
                          | 1:1
                          v
                      +--------+        +------+
                      | PLAYER |--joins-| TEAM |-----owns----> FLEET
                      +---+----+        +------+               |
                       /  |  \                                 v
                  ships   |   reputations -> FACTION       FLEET_MEMBER
                    |     |                                    |
                    v     v                                    v
                  SHIP  STATION/PLANET (many-to-many)        SHIP
                    |     |
                    +--in-+--> SECTOR --in--> CLUSTER --in--> REGION
                              |     \           |             |
                              |      +-zone-> ZONE -----------+
                              |
                              +- warps_to -> SECTOR (sector_warps)
                              +- origin/dest -> WARP_TUNNEL

Where to look in source

  • Models: services/gameserver/src/models/<file>.py
  • Migrations: services/gameserver/alembic/versions/
  • Raw SQL bootstrap (multi-region, AI companion): services/gameserver/sql/