gridpilot.gg/docs/architecture/shared/ENUMS.md

Enums (Shared Contract)

This document defines how enums are modeled, placed, and used across the system.

Enums are frequently a source of architectural leakage. This contract removes ambiguity.

1) Core principle (non-negotiable)

Enums represent knowledge.

Knowledge must live where it is true.

2) Enum categories (strict)

There are four and only four valid enum categories:

1. Domain enums
2. Application workflow enums
3. Transport enums (HTTP contracts)
4. UI enums (website-only)

3) Domain enums

Definition:

• business meaning
• affects rules or invariants

Placement:

• core/**

Rule:

• domain enums MUST NOT cross a delivery boundary

4) Application workflow enums

Definition:

• internal workflow coordination
• not business truth

Placement:

• core/**

Rule:

• workflow enums MUST remain internal

5) Transport enums

Definition:

• constrain HTTP contracts

Placement:

• apps/api/** and apps/website/** (as transport representations)

Rules:

• transport enums are copies, not reexports of domain enums
• transport enums MUST NOT be used inside Core

6) UI enums

Definition:

• website presentation or interaction state

Placement:

• apps/website/**

Rule:

• UI enums MUST NOT leak into API or Core

7) Final rule

If an enum crosses a boundary, it is in the wrong place.