Blueprint examples

{
  "intent": "The game runs the night and day rounds itself, on a clock every player can see, so nobody has to sit out and narrate.",
  "why": "Somebody currently has to leave the game to deal roles, wake people up and count votes. That person never plays. Every part of this outcome exists so that job disappears rather than rotates.",
  "success": [
    {
      "statement": "A full game runs from first night to a win with no human narrator",
      "verifiable": true
    },
    {
      "statement": "A phase change reaches every player's screen within 2 seconds",
      "verifiable": true,
      "changeType": "modified"
    },
    {
      "statement": "An action submitted before a phase closes is always counted",
      "verifiable": true
    }
  ],
  "stakes": {
    "nonNegotiable": [
      "A player never receives another player's role",
      "The server owns the clock; a client only displays it"
    ],
    "acceptableTradeoffs": [
      "A player who is offline when a phase closes loses that phase's action",
      "The round history is kept for the game only, not archived"
    ]
  },
  "constraints": [
    {
      "rule": "Must work in a mobile browser, one-handed",
      "hard": true
    },
    {
      "rule": "No accounts; a seat is a one-time token from the join link",
      "hard": true
    }
  ],
  "escalate": [
    {
      "when": "Two players report seeing different phases of the same game",
      "action": "Freeze the round and raise it with the owner — a split clock silently invalidates every vote after it"
    },
    {
      "when": "A role appears in a response sent to a player who does not own it",
      "action": "Stop the game and rotate the deal — the game is unwinnable and nobody can tell"
    }
  ]
}

sequenceDiagram
  autonumber
  actor P as Player
  participant R as Round service
  participant D as Postgres
  participant C as Phase timer
  actor O as Other players
  P->>R: submit night action
  alt while the phase is open
    R->>R: check the role allows this action
    R->>D: store action, stamped with the phase number
    R-->>P: accepted
  else after the deadline
    R-->>P: rejected, that phase is already resolved
  end
  C->>R: night timer expires
  R->>D: close the phase
  R->>R: resolve this night's actions together
  R->>O: broadcast the outcome to everyone
  R->>P: broadcast the outcome to everyone
  P-->>P: sees what happened at dawn

stateDiagram-v2
  [*] --> Lobby
  Lobby --> Dealing: every seat filled
  Dealing --> Night: roles dealt
  Night --> Dawn: night timer expires
  Dawn --> Day: resolve night actions
  Day --> Voting: discussion timer expires
  Voting --> Tally: votes tallied
  Tally --> Day: tied
  Tally --> Resolution: elimination confirmed
  Resolution --> Night: no winner yet
  Resolution --> MafiaWin: mafia win
  Resolution --> TownWin: town wins
  MafiaWin --> [*]
  TownWin --> [*]

Table games {
  id uuid [pk]
  join_code varchar [not null, unique]
  phase varchar [not null]
  phase_number int [not null, default: 0]
  phase_ends_at timestamptz
  note: 'phase_ends_at is the only clock. A client never decides a phase is over.'
}

Table seats {
  id uuid [pk]
  game_id uuid [not null, ref: > games.id]
  display_name varchar [not null]
  seat_token varchar [not null, unique]
  alive boolean [not null, default: true]

  indexes {
    (game_id, display_name) [unique, name: 'one_seat_per_name_per_game']
  }
  note: 'seat_token is what a player proves a seat with. The name is public; the token is not.'
}

Table role_assignments {
  seat_id uuid [pk, ref: > seats.id]
  role varchar [not null]
  note: 'Read only by the server, and only ever served to the seat that owns it.'
}

Table night_actions {
  id uuid [pk]
  game_id uuid [not null, ref: > games.id]
  phase_number int [not null]
  actor_seat_id uuid [not null, ref: > seats.id]
  target_seat_id uuid [ref: > seats.id]

  indexes {
    (game_id, phase_number, actor_seat_id) [unique, name: 'one_action_per_seat_per_phase']
  }
  note: 'Stamped with the phase it was submitted in, so a late arrival is rejected rather than applied to the next night.'
}

Table votes {
  game_id uuid [not null, ref: > games.id]
  phase_number int [not null]
  voter_seat_id uuid [not null, ref: > seats.id]
  target_seat_id uuid [not null, ref: > seats.id]

  indexes {
    (game_id, phase_number, voter_seat_id) [unique, name: 'one_vote_per_seat_per_phase']
  }
}

# ──── Core Tier ────

core: {
  round: {
    Round: {
      shape: class
      \# Aggregate Root
      gameId: uuid
      phase: Phase
      phaseNumber: int {constraint: monotonic}
      phaseEndsAt: timestamptz

      open()
      close()
      resolve()
    }

    # @change: added
    NightAction: {
      shape: class
      actorSeatId: uuid {constraint: unique with phaseNumber}
      targetSeatId: uuid
      phaseNumber: int
    }

    Vote: {
      shape: class
      voterSeatId: uuid {constraint: unique with phaseNumber}
      targetSeatId: uuid
      phaseNumber: int
    }

    Round -> NightAction: holds
    Round -> Vote: holds
  }

  roster: {
    Game: {
      shape: class
      \# Aggregate Root
      id: uuid
      joinCode: string {constraint: unique}
    }

    Seat: {
      shape: class
      id: uuid
      displayName: string
      seatToken: string {constraint: secret}
      alive: boolean
    }

    RoleAssignment: {
      shape: class
      seatId: uuid
      role: Role {constraint: server-only}
    }

    Game -> Seat: holds
    Game -> RoleAssignment: deals
  }
}

# ──── Supporting Tier ────

supporting: {
  presence: {
    Connection: {
      shape: class
      seatId: uuid
      lastSeenAt: timestamptz
    }
  }
}

# ──── Generic Tier ────

generic: {
  delivery: {
    # @change: modified
    PhaseBroadcast: {
      shape: class
      phase: Phase
      sentAt: timestamptz
    }
  }
}

# ──── Cross-Context Relationships ────

core.roster.Seat -> core.round.NightAction: targets
core.round.Round -> core.roster.Game: advances
supporting.presence.Connection -> core.roster.Seat: occupies
core.round.Round -> generic.delivery.PhaseBroadcast: broadcasts

specification {
  element actor
  element system
  element container
  element database
}

model {
  player = actor "Player"
  mafia = system "Mafia game" {
    web = container "Game screen" "Next.js, in a mobile browser"
    round = container "Round service" "Owns the phase clock and resolves actions"
    timer = container "Phase timer" "Closes each phase on time"
    db = database "Postgres" "Games, seats, roles, actions, votes"
  }
  player -> mafia.web "plays on"
  mafia.web -> mafia.round "submits actions and votes"
  mafia.round -> mafia.db "stores, stamped with the phase"
  mafia.timer -> mafia.round "expires the phase"
  mafia.round -> mafia.web "broadcasts phase changes (no roles)"
}

views {
  view rounds { include * }
}

{
  "openapi": "3.0.3",
  "info": {
    "title": "Mafia round API",
    "version": "0.1.0",
    "description": "The smallest surface a round needs. Note what is absent: there is no endpoint that returns anyone else's role."
  },
  "paths": {
    "/games/{id}/state": {
      "get": {
        "summary": "Current state, as this seat sees it",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Phase, time remaining, who is alive, and this seat's own role — no other seat's"
          }
        }
      }
    },
    "/games/{id}/actions": {
      "post": {
        "summary": "Submit a night action",
        "responses": {
          "202": {
            "description": "Accepted, stamped with the current phase number"
          },
          "403": {
            "description": "This seat's role does not permit that action"
          },
          "409": {
            "description": "That phase is already resolved"
          }
        }
      }
    },
    "/games/{id}/votes": {
      "post": {
        "summary": "Cast a vote",
        "responses": {
          "202": {
            "description": "Accepted"
          },
          "409": {
            "description": "This seat has already voted in this phase"
          }
        }
      }
    },
    "/games/{id}/events": {
      "get": {
        "summary": "Phase change stream",
        "responses": {
          "200": {
            "description": "Server-sent phase changes, carrying no role information"
          }
        }
      }
    }
  }
}

{
  "schemaVersion": 1,
  "decisions": [
    {
      "category": "language",
      "choice": "TypeScript",
      "icon": "typescript",
      "rationale": "One set of phase and role types shared by the server and the screen, so one side cannot drift from the other.",
      "alternatives": [
        "Python",
        "Go"
      ]
    },
    {
      "category": "framework",
      "choice": "Next.js",
      "icon": "nextdotjs",
      "rationale": "The join screen and the round screen come off one runtime, and server-sent events need no extra service.",
      "alternatives": [
        "Remix",
        "SvelteKit"
      ],
      "tradeoffs": "Past a few hundred concurrent players this needs a dedicated socket layer."
    },
    {
      "category": "database",
      "choice": "PostgreSQL",
      "icon": "postgresql",
      "rationale": "One action per seat per phase is a unique index, not application code.",
      "alternatives": [
        "MySQL",
        "DynamoDB"
      ],
      "changeType": "modified"
    },
    {
      "category": "hosting",
      "choice": "Vercel",
      "icon": "vercel",
      "rationale": "Small deploy unit, and straightforward delivery for a link people open on a phone.",
      "alternatives": [
        "Fly.io",
        "Render"
      ]
    },
    {
      "category": "auth",
      "choice": "Seat tokens, no accounts",
      "rationale": "A display name is visible to everyone on the call, so it cannot prove a seat. A one-time token issued at join can.",
      "alternatives": [
        "Auth0",
        "Clerk"
      ],
      "changeType": "added"
    },
    {
      "category": "monitoring",
      "choice": "Structured logs + error tracking",
      "rationale": "Inherited from the workspace default rather than chosen again for this outcome."
    }
  ]
}

{
  "dimensions": [
    {
      "name": "Role secrecy",
      "target": 100,
      "current": 100,
      "weight": 1,
      "description": "A seat's own session never receives another seat's role. Non-negotiable.",
      "slaTarget": "zero leaked roles",
      "linkedRequirements": [
        "J2-S1",
        "J2-S2"
      ]
    },
    {
      "name": "Phase agreement",
      "target": 95,
      "current": 74,
      "weight": 1,
      "description": "Every player sees the same phase at the same moment.",
      "slaTarget": "within 2s across clients",
      "changeType": "modified"
    },
    {
      "name": "Action delivery",
      "target": 99,
      "current": 91,
      "weight": 0.9,
      "description": "An action submitted before the deadline is always counted.",
      "slaTarget": "zero dropped actions"
    },
    {
      "name": "Reconnect recovery",
      "target": 80,
      "weight": 0.6,
      "description": "A returning player lands on the right phase with their own role. Not yet measured — separate outcome.",
      "changeType": "added"
    },
    {
      "name": "Mobile usability",
      "target": 90,
      "current": 83,
      "weight": 0.8,
      "description": "Usable one-handed while chatting in the room.",
      "slaTarget": "one tap for every round action"
    }
  ]
}