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
entities.md Ship, ShipSpecification, Planet, Station, GenesisDevice, PlanetFormation
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, FactionMission, regional governance (RegionalElection, RegionalVote, RegionalPolicy, RegionalTreaty, InterRegionalTravel, RegionalMembership)
admin.md User admin flag, AdminCredentials, AuditLog, moderation 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

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/