# Data Model

This document defines the intended high-level data model for the simulation.

It is a design-side schema document. It does not describe the current codebase exactly. It describes the durable entity vocabulary the codebase should move toward.

## Design Goals

The data model should support:

- the layered spatial model
- commander-driven behavior
- market-driven economy
- module-based capability
- population and workforce
- claimable construction sites
- local-space combat
- scalable replication and future sharding

## Core Principles

- important game concepts should exist as explicit entities or records
- IDs should be stable and durable
- spatial state should be explicit, not inferred from one generic position alone
- access, market, and behavior restrictions should be data-driven
- construction, production, and logistics should all use shared entity vocabulary

## Identity

Every major persistent entity should have:

- a stable ID
- an owning faction where relevant
- a type or kind
- a current lifecycle or state

Recommended global ID families:

- `factionId`
- `commanderId`
- `systemId`
- `nodeId`
- `bubbleId`
- `stationId`
- `shipId`
- `moduleId`
- `claimId`
- `orderId`
- `recipeId`
- `policyId`
- `marketOrderId`
- `constructionSiteId`

## Core Entity Set

The intended core entities are:

1. `Faction`
2. `Commander`
3. `System`
4. `Node`
5. `LocalBubble`
6. `Station`
7. `Ship`
8. `ModuleInstance`
9. `Claim`
10. `ConstructionSite`
11. `MarketOrder`
12. `Recipe`
13. `PolicySet`

## Faction

A faction is the top-level strategic actor.

Suggested fields:

- `factionId`
- `label`
- `color`
- `doctrine`
- `populationTotal`
- `credits` if retained
- `relation state to other factions`
- `commanderIds`
- `policy defaults`

## Commander

Commanders are first-class AI actors.

Suggested fields:

- `commanderId`
- `kind`
- `ownerFactionId`
- `parentCommanderId?`
- `controlledEntityId?`
- `doctrine`
- `policy overrides`
- `goal set`
- `subordinateCommanderIds`
- `alive`

Recommended commander kinds:

- `faction`
- `station`
- `ship`
- `fleet`
- `sector`
- `task-group`

## System

A system is a strategic world entity in galaxy space.

Suggested fields:

- `systemId`
- `label`
- `galaxyPosition`
- `star definition`
- `nodeIds`
- `faction influence later`

## Node

A node is a meaningful location in system space that owns a local bubble.

Suggested fields:

- `nodeId`
- `systemId`
- `kind`
- `systemPosition`
- `bubbleId`
- `parentNodeId?`
- `orbital metadata?`
- `occupyingStructureId?`

Recommended node kinds:

- `star`
- `planet`
- `moon`
- `lagrange-point`
- `station`
- `gate`
- `resource-site`
- `structure`

## LocalBubble

A local bubble is the tactical simulation context attached to one node.

Suggested fields:

- `bubbleId`
- `nodeId`
- `systemId`
- `radius`
- `occupantShipIds`
- `occupantStationIds`
- `occupantClaimIds`
- `occupantConstructionSiteIds`
- `serverAuthorityId later`

## Station

A station is a structure attached to a Lagrange-point node.

Suggested fields:

- `stationId`
- `ownerFactionId`
- `commanderId?`
- `nodeId`
- `systemId`
- `bubbleId`
- `moduleIds`
- `inventory`
- `population`
- `workforceCapacity`
- `workforceEfficiency`
- `power state`
- `policySetId?`
- `marketOrderIds`
- `construction state if incomplete`
- `docking state`

## Ship

A ship is a mobile actor that changes movement regime over time.

Suggested fields:

- `shipId`
- `ownerFactionId`
- `commanderId?`
- `shipClass`
- `role`
- `moduleIds`
- `inventory`
- `health`
- `power state`
- `currentSpatialState`
- `policySetId?`
- `current goal/order/task references`

## ModuleInstance

A module instance is a fitted capability component on a ship or station.

Suggested fields:

- `moduleId`
- `definitionId`
- `hostKind`
- `hostId`
- `category`
- `operational state`
- `construction state`
- `workforceRequirement`
- `power requirement`

Recommended host kinds:

- `ship`
- `station`

## Claim

A claim is a vulnerable object placed at a Lagrange point before construction.

Suggested fields:

- `claimId`
- `ownerFactionId`
- `commanderId?`
- `systemId`
- `nodeId`
- `bubbleId`
- `placedAt`
- `activatesAt`
- `state`
- `health`

Recommended claim states:

- `placed`
- `activating`
- `active`
- `destroyed`

## ConstructionSite

A construction site is the market-facing and build-facing record for an incomplete structure or expansion.

Suggested fields:

- `constructionSiteId`
- `ownerFactionId`
- `nodeId`
- `bubbleId`
- `targetKind`
- `targetDefinitionId`
- `requiredItems`
- `deliveredItems`
- `progress`
- `assignedConstructorIds`
- `marketOrderIds`
- `state`

Recommended target kinds:

- `station`
- `station-module`
- `ship later`

## MarketOrder

A market order expresses station-side demand or supply.

Suggested fields:

- `marketOrderId`
- `stationId` or `constructionSiteId`
- `ownerFactionId`
- `kind`
- `itemId`
- `amount`
- `remainingAmount`
- `valuation`
- `reserveThreshold?`
- `policy restrictions`
- `state`

Recommended market order kinds:

- `buy`
- `sell`

Recommended market order states:

- `open`
- `partially-filled`
- `filled`
- `cancelled`
- `expired later`

## Recipe

A recipe defines a conversion from inputs to outputs.

Suggested fields:

- `recipeId`
- `label`
- `inputItems`
- `outputItems`
- `cycleTime`
- `validModuleCategories`
- `powerRequirement?`
- `workforceModifier?`

## PolicySet

A policy set defines access and restriction rules.

Suggested fields:

- `policySetId`
- `ownerKind`
- `ownerId`
- `tradeAccessPolicy`
- `dockingAccessPolicy`
- `constructionAccessPolicy`
- `operationalRangePolicy`
- `hostility rules later`

Recommended owner kinds:

- `faction`
- `station`
- `commander`
- `ship`

## Spatial State

Ships should not be modeled with only one generic position and target.

Recommended ship spatial state fields:

- `spaceLayer`
- `currentSystemId`
- `currentNodeId?`
- `currentBubbleId?`
- `localPosition?`
- `systemPosition?`
- `movementRegime`
- `destinationNodeId?`
- `transitState?`

Recommended space layers:

- `universe-space`
- `galaxy-space`
- `system-space`
- `local-space`

Recommended movement regimes:

- `local-flight`
- `warp`
- `stargate-transit`
- `ftl-transit`

## Population State

Population should remain explicit rather than hidden in generic inventory only.

Suggested station-side workforce fields:

- `population`
- `populationCapacity`
- `workforceRequired`
- `workforceEffectiveRatio`
- `workerConsumptionRates`

Commanders should not be ordinary cargo items even if they are population-derived.

## Power State

Ships and stations both need explicit operational power state.

Suggested fields:

- `fuelInventory`
- `energyStored`
- `powerOperational`
- `powerDeficitReason?`

This matters because no fuel leads to no power, and no power halts major operations.

## Inventories

Inventories should remain generic item maps, but hosts should also have explicit context.

Recommended inventory host kinds:

- `ship`
- `station`
- `construction-site`

This prevents construction storage from being a special-case invisible system.

## Ownership vs Access

The model should separate:

- ownership
- commander control
- policy-based access
- current occupancy

These are not the same thing.

Examples:

- a faction owns a station
- a station commander operates it
- another faction may be allowed to trade there
- multiple factions may be present in the same system

## Minimum Enums

The following enum families should exist somewhere in the model:

- `SpaceLayer`
- `MovementRegime`
- `NodeKind`
- `CommanderKind`
- `ModuleCategory`
- `MarketOrderKind`
- `MarketOrderState`
- `ClaimState`
- `ConstructionTargetKind`
- `TradeAccessPolicy`
- `DockingAccessPolicy`
- `OrderState`
- `TaskState`
- `TaskKind`

## Replication Implication

This entity model is also intended to support replication.

That means entity shape should make it easy to stream:

- strategic summaries from higher layers
- detailed updates from lower layers
- explicit lifecycle changes
- explicit claim, market, and construction updates

See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the typed event layer built on top of this model.

## Minimum Rules

The following rules should remain true unless deliberately revised:

- important world concepts should have explicit records
- ships need explicit spatial state
- claims and construction sites are real entities
- market orders are real entities
- modules are real instances attached to hosts
- policy is separate from ownership
- population is explicit at the station level

## Relationship To Other Documents

- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
  - defines the layered world structure

- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
  - defines commander roles and hierarchy

- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
  - defines market behavior

- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md)
  - defines capability-bearing module instances

- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
  - defines population and commander generation

- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
  - defines the policy sets attached to entities

- [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md)
  - defines the execution-layer fields that entities should carry