# Skara Brae — Use Case Model

Version 1.0 (WI-2, 2026-10-03) · OpenUP artifact: `requirements/use-case-model.md`
Scope: the **existing implemented system** (server MVP as of `wi-2-architecture-cleanup` @ 899fde8). Every flow below is derived from actual handler code (`crates/sb-api/src/routes/mod.rs`) — status codes cited are the implemented behavior and are normative.

## Actors

| Actor | Description |
|---|---|
| **Player** | Authenticated user owning one or more characters (JWT role `player`). |
| **Administrator** | Player with elevated rights (`role = admin`); may view any user's and any character's resources read-only. |
| **Guest** | Unauthenticated caller; only register/login are open. |

## Use Case Overview

| ID | Use Case | Primary Actor | Includes / Extends |
|---|---|---|---|
| UC-01 | Register Account | Guest | — |
| UC-02 | Authenticate | Guest | — |
| UC-03 | Manage Characters | Player (Admin read) | — |
| UC-04 | Browse Game Catalogue | Player | — |
| UC-05 | Train Stat | Player | includes Regenerate Resources |
| UC-06 | Manage Equipment | Player | — |
| UC-07 | Trade at Shop | Player | — |
| UC-08 | Run Adventure | Player | includes Regenerate Resources, Resolve Combat |
| UC-09 | Heal at Temple | Player | — |
| UC-10 | Practice Bard Song | Player | — |
| UC-11 | Study Magic | Player | — |
| UC-12 | Level Up at Review Board | Player | — |

![Skara Brae Use Case Overview](use-case-overview.png)

*Figure 1: Use case overview (rendered from the EA model, `docs/openup/model/skara-brae.eapx`, via `scripts/openup/export-diagram-images.ps1`).*

Shared sub-flow **Regenerate Resources**: the system recomputes time-based regeneration **at specific call sites only** — list characters, view character, run adventure, and train stat (routes/mod.rs:264–266, 331, 442, 642). Energy +1 per 180 s, nerve +1 per 300 s, HP +5% of max per 300 s (only if alive and injured), capped at maxima; `last_regen` advances to now. It is **not** applied by equip/unequip, gym view, shop, heal, songs, spells, or level-up.

---

## UC-01 Register Account

**Precondition:** none. **Main success scenario:**
1. Guest submits name (3–32 chars) and password (≥ 6 chars).
2. System verifies the name is unused → 409 CONFLICT if taken.
3. System hashes the password (argon2), assigns the `player` role and the next id, persists the user.
4. System issues a JWT (HS256, `player` role) and returns `{token, user_id, name, role}`.

**Alternate flows:** name length invalid → 400; password too short → 400; name taken → 409; hashing/token failure → 500.

## UC-02 Authenticate

**Main success scenario:**
1. Guest submits name and password.
2. System finds the user (401 if unknown) and verifies the password hash (401 on mismatch).
3. System issues a JWT carrying the user's real role (`admin`/`player`) and returns `{token, user_id, name, role}`.

**Alternate flows:** unknown name or wrong password → 401 UNAUTHORIZED; token creation failure → 500.

## UC-03 Manage Characters

**Main success scenario (create):**
1. Player submits character name, race, class for their user id (Admin may act for any user).
2. System validates the target user exists (404) and the trimmed name is 1–32 chars (400).
3. System rolls stats (d6+5 base 6–16 per stat ± race modifiers), computes max HP/energy/nerve from class, grants starting gold (50) and level-1 class spells to casters.
4. System assigns the next character id, stores and persists the character; returns it fully.

**Scenario (list/view):** Player lists their characters (Admin: any user's); the system applies Regenerate Resources to each returned character and returns them. Viewing one character applies regen then returns it.

**Alternate flows:** foreign user/character without admin role → 403 FORBIDDEN; user/character not found → 404; invalid name → 400.

## UC-04 Browse Game Catalogue

**Main success scenario:**
1. Player requests the catalogue: races, classes, items (optional type/quality/slot filters), enemies, or adventure zones.
2. System returns static game data loaded from `skara-brae-common` JSON (class info is enriched with `is_caster`).

**Alternate flows:** single item by unknown id → 404; filters may return an empty list (not an error).

## UC-05 Train Stat

**Precondition:** character exists and caller may act on it. **Main success scenario:**
1. Player selects a training ground (strength / dexterity / constitution / intelligence / luck) and submits the stat name.
2. System applies Regenerate Resources.
3. System checks energy ≥ 1 and gold ≥ training cost (cost grows ~1.3× per 10 stat points).
4. System deducts 1 energy and the gold cost, increments the stat; constitution training recomputes max HP (current HP clamped).
5. System persists and returns `{success, message, character}`.

**Alternate flows:** foreign character → 403; character not found → 404; not enough energy → 422; not enough gold → 422; unknown stat name → 400.

## UC-06 Manage Equipment

**Main success scenario (equip):**
1. Player submits an item id from their inventory.
2. System moves the item from inventory to its slot; a previously equipped item in that slot returns to inventory.
3. System persists and returns the updated character.

**Scenario (unequip):** Player submits a slot name; the system moves the equipped item back to inventory.

**Alternate flows:** foreign character → 403; character/item not found → 404; item not in inventory → 400; nothing equipped in slot → 400.

## UC-07 Trade at Shop

**Main success scenario (buy):**
1. Player views the shop: always-stocked items plus rotating stock (with quantities) alongside their inventory.
2. Player submits `buy` + item id.
3. System checks gold ≥ price (422), and for non-always-in-stock items decrements the limited stock (410 GONE if 0).
4. System deducts gold, adds the item to inventory, persists character and stock; returns `{success, message, gold}`.

**Scenario (sell):** Player submits `sell` + item id; system removes the first matching inventory item, pays half the item value, increments shop stock for non-permanent items.

**Alternate flows:** unknown action or item not owned (sell) → 400; item not found → 404; insufficient gold → 422; stock exhausted → 410.

## UC-08 Run Adventure

**Precondition:** character exists and caller may act on it. **Main success scenario:**
1. Player requests an adventure for a zone (default `skara_brae_streets`).
2. System validates the zone (404) and applies Regenerate Resources.
3. System refuses incapacitated characters (HP ≤ 0 → 400) and characters with nerve below the zone cost (422); otherwise deducts the nerve cost.
4. System draws one enemy from the zone's weighted encounter table.
5. System resolves turn-based combat: open-ended d100 attack rolls, OB vs DB, RoleMaster crit tables with level-gap damage caps, active bard song effects, active spell damage/heal per round.
6. On player victory: XP and gold per the enemy definition, character HP set to the last round's defender HP, and loot dropped per-item chance rolls (only items existing in the catalogue).
7. On defeat: character HP set to 0; no rewards.
8. Spell-point upkeep is charged whenever a spell was active, win or lose.
9. System persists the character and returns `{zone, enemy, combat_log, loot}` (loot = item display names).

**Alternate flows:** foreign character → 403; character/zone not found → 404; incapacitated → 400; insufficient nerve → 422. **Exception:** encounter references an unknown enemy (data error) → 500 (post WI-2; previously a panic).

## UC-09 Heal at Temple

**Main success scenario:**
1. Player requests healing, optionally `partial`.
2. System computes missing HP; full heals all, partial heals half (rounded up); cost = amount healed, minimum 1 gold.
3. System checks gold (422), deducts it, restores HP, persists; returns `{hp, max_hp, gold, healed: true}`.

**Alternate flows:** foreign character → 403; not found → 404; already at full HP → 400; insufficient gold → 422.

## UC-10 Practice Bard Song

**Precondition:** character class is Bard. **Main success scenario:**
1. Player views available songs (level-gated, with combat effect descriptions) and the active song.
2. Player submits a song id; system validates level requirement (422) and sets it active; returns `{success, message, active_song}`.

**Scenario (clear):** submitting no song id clears the active song. **Alternate flows:** non-Bard → 403; unknown song → 404; level too low → 422; foreign character → 403; not found → 404.

## UC-11 Study Magic

**Precondition:** character belongs to a caster class (Mage→magician, Wizard, Conjurer, Sorcerer). Spell level = (character level / 3) + 1 — **uncapped by code** (level 100 → spell level 34); learn *requests* are validated to 1–7, and the practical ceiling is emergent from the data (spells are defined only through level 7, so higher computed levels surface no new spells).

**Scenario (view spellbook):**
1. Player requests their spellbook: caster class, current spell level, spell points, spells up to the achievable level (each marked known), and the learn-cost table for levels 2–7.

**Scenario (learn spell level):**
1. Player submits a spell level (1–7).
2. System validates caster class (403), level range (400), level not above the character's current spell level (422), gold ≥ learn cost (422), and that new spells exist (400).
3. System deducts gold, adds all unknown spell ids of that level, recomputes and refills max spell points; returns `{learned_count, spell_points, max_spell_points, gold}`.

**Scenario (activate/clear active spell):**
1. Player submits a spell id (or empty to clear).
2. System validates the spell is known (403), exists (404), and spell points suffice (422); deducts the spell's points and sets it active; returns `{active_spell, spell_points}`.

## UC-12 Level Up at Review Board

**Main success scenario:**
1. Player requests a level-up.
2. System validates: below max level 100, XP ≥ 18·100·(level)² for the next level (i.e. `xp_for_level(next)`), gold ≥ 500·next level.
3. System deducts the gold cost, increments the level, recomputes and fully restores HP/energy/nerve and max spell points; persists; returns `{success, message, character}`.

**Alternate flows (all 422):** already at max level; not enough XP; not enough gold. Foreign character → 403; not found → 404.

---

## Traceability Notes

- UC-08 is the design driver for WI-2's service extraction (`sb_core::adventure`); its status mapping feeds `DomainError` (see `analysis-design/design-wi-2-architecture-cleanup.md` §4.1–4.2).
- Catalogue data backing UC-04 lives in `skara-brae-common/data/` (items, enemies, zones, spells, crit tables).