System API 0.1 — De Facto Specification

1. What the System API is — and the "two APIs, one word" caveat ⚠︎

A System (D&D 5e 2014/2024, System 8, custom) is described by three layers (per system.md), but in code those layers are two very different APIs that happen to share the word "System":

1. Data plane (Layers 1–2): the trait/fixture REST API. Fully built, DB-backed, dual-ownership (system-default vs. campaign-override), seeded from TypeScript fixtures. This is the bulk of the surface and is consumed broadly (campaigns, tokens, maps, lighting, actions).
2. Logic plane (Layer 3): the SystemModule interface. A lazy-loaded TypeScript character-logic module. It has no REST surface and is consumed only by the Character Sheet UI — so it is really the foundation of the Character Sheet API, not a general system concern (see §8).

2. Version

Unversioned — no SYSTEM_API_VERSION constant exists. Three version-ish fields, only one enforced:

So: fixture data is versioned (integer, enforced); the code module carries an unenforced string; the API contract itself has no version gate.

3. Logic plane — SystemModule (packages/shared/src/systems/types.ts)

Character Sheet / Monster / Content API members (MODULE_API_VERSION 1.5.0, all optional, additive). SystemModule gained the projection/generation/content surfaces; see the dedicated specs for detail:

The Character type it operates on is imported from types/character.ts:36 — it is system-agnostic; SystemModule is the interpretation layer.

Registry / loading (systems/index.ts): systemRegistry (:24) statically registers only dnd5e-2014 and dnd5e-2024; loadSystemModule(id) (:109) is cache-first and falls back to moduleRegistry.getSystemModule(id).loadModule() (:129) for module-provided systems (this is how System 8 loads — it is an external module, not in this repo ⚠︎). getLoadedSystemModule (:148), isSystemAvailable (:155), getAvailableSystems (:39), systemInfoList/getSystemInfoList (:57/:79, the UI list; splices module systems in before custom).

4. Data plane — Systems core REST (routes/systems.ts, mounted /api/systems)

5. Data plane — Trait CRUD (system-level & campaign-level)

System-level trait CRUD — generic createTraitRouter factory (routes/systemTraits.ts:41), mounted /api/systems/:systemId/<trait> (all behind requireAuthWithImpersonation). Each exposes GET /, GET /:id, POST /, PUT /:id, PATCH /:id, DELETE /:id. Ten traits: prop-types, property-definitions, conditions, bars, light-source-types, vision-types, functions, actions, damage-types, currencies. ⚠︎ Entirely undocumented in system.md.

Campaign-level (inherited) trait endpoints — one router per trait, mounted under /api/campaigns/:campaignId/<trait> (conditions is the exception: /api/conditions?campaignId=). Files: propTypes.ts, propertyDefinitions.ts, bars.ts, conditions.ts, lightSourceTypes.ts, visionTypes.ts, campaignFunctions.ts, campaignActions.ts, damageTypes.ts, currencies.ts.

• Dual-ownership merge (verified propTypes.ts:49-79): with a systemId, query OR(campaignId=X, systemId=…), annotate each row isSystemDefault = (systemId != null && campaignId == null) and isEditable = (campaignId === X).
• 403-on-system-row (verified propTypes.ts:168-170): writes reject when existing.systemId && !existing.campaignId.

change-system (campaigns.ts:447): body { newSystemId, mergeNewDefaults, deleteOldDefaults, overwriteExisting }; optionally deletes old-default copies, copies new defaults to campaign level, then updates campaign.systemId. ⚠︎ Copies only 7 of 10 trait types (omits campaign_actions, damage_types, currencies) — likely a bug (§7).

6. Data plane — Trait tables & seeding

Tables (all in dbSchema.ts, sqlite + pg mirror), each with dual-ownership system_id/campaign_id columns: systems, prop_types, property_definitions, conditions, bars, light_source_types, vision_types, campaign_functions, campaign_actions, damage_types, currencies, plus fixture_versions (seed tracking).

Seeding (seedSystems.ts): seedAllSystems(force?) (:373, also the startup call at index.ts:843) pulls getAllSystemFixtures() (built-in + module-provided), compares each fixture.version to the fixture_versions table, and seeds/re-seeds accordingly. Prop-types/property-definitions/bars get namespaced ids (${systemId}_${id}) so multiple systems can define e.g. hp without PK collision (buildNamespacedTraitRows, :57).

7. Drift vs. system.md

1. ⚠︎ System 8 is no longer bundled. system.md lists system8/system8.ts in the repo; it has been extracted to @purple-cat-games/system8 and loads via moduleRegistry. The systemRegistry snippet (system.md:616) is wrong for current code (2 entries, not 3).
2. ⚠︎ System-level trait CRUD (/api/systems/:systemId/*, 10 routers) is absent from the doc.
3. ⚠︎ 3 extra trait types in code not in the doc's Layer-2 list: actions (campaign_actions), damage_types, currencies (+ fixture_versions, baseCurrency).
4. ⚠︎ Fixture packaging claim outdated: doc says traits seed via SQL migrations 0014–0018; actual mechanism is TS fixtures + seedSystems.ts + version-gated fixture_versions.
5. Doc omits newer fields (aliases, showOnHover, bar colorScale*, SystemClass.savingThrowProficiencies/spellcastingAbility, applyTemplateStats) and the custom no-validation system behavior.

8. Overlap with the Character Sheet API — the key structural finding

SystemModule (Layer 3) is almost entirely a Character-Sheet concern. Its sole consumer is CharacterSheet.tsx (loadSystemModule at :463; abilityScores/suggestions/classes/ applyTemplateStats at :474–:1021). No server code and no other UI consumes its logic members. Classification:

• Foundational (this System API): Layer 1 metadata (ISystem) + Layer 2 trait tables/REST — consumed app-wide.
• Character-sheet-specific (belongs to the Character Sheet API): abilityScores, classes, validateHp, suggestions, classAttributePriorities, applyTemplateStats, and all validation/suggestion types. These drive one screen and should arguably be documented/versioned under a Character-Sheet system-adapter contract, not "System API."

9. Known gaps

1. change-system migrates only 7/10 trait types (§5) — actions/damage-types/ currencies silently dropped on system switch.
2. No API version / negotiation; SystemModule.version is read by nothing.
3. ⚠︎ system-level trait writes are under-guarded: the generic factory only enforces same-system ownership, not "bundled system is read-only" — the server will happily PATCH /api/systems/dnd5e-2014/bars/:id. Bundled protection relies on the client honoring isBundledSystem (which excludes system8).
4. Two parallel trait-copy implementations (systems.ts copy/restore vs. campaigns.ts change-system) with divergent field sets — divergence already realized in gap #1.
5. Legacy DND5E_* constants in types/system.ts duplicate fixture data (hardcode systemId:'dnd5e-2014' even for 2024) — pre-fixture leftovers.