skara-brae-common/docs/openup/analysis-design/uc-realization-mapping.md

Skara Brae — Analysis & Design Model (text form)

Version 1.0 (WI-2, 2026-10-03) · OpenUP artifact: analysis-design/uc-realization-mapping.md This is the content the EA model will carry once the modeling pipeline exists. The EA repository itself (.eapx, keyfob-station style) is planned for a later work item — EA is a human-gated interactive tool; this document is the authoritative source any future EA builder script generates from.

1. Model structure (planned EA packages)

Model: Skara Brae
├── Requirements
│   ├── Vision                      (from requirements/vision.md)
│   ├── Use Case Model
│   │   ├── Actors: Player, Administrator, Guest
│   │   └── Use Cases UC-01 … UC-12 (from requirements/use-case-model.md;
│   │        scenarios as Basic Path / Alternate / Exception with per-step Actor)
│   └── Supplementary Specifications (from requirements/supplementary-specifications.md)
└── Analysis-Design
    ├── Architecture Overview       (crate/layer diagram, dependency rule)
    ├── UC-01 Realization … UC-12 Realization   (one package per UC: analysis classes,
    │                                               design elements, realization table below)
    └── Design                      (component model of the joint architecture — server
                                    crates + skara-brae-client + skara-brae-common; §3)

Joint-model decision (2026-10-03): one EA model covers the whole product — server, client and common — because the use cases are player-facing and Requirement→realization traceability spans tiers. Client-side UC realization packages (Vue boundary elements per UC) are a future work item: no markdown source exists yet; they are NOT invented here. Today the client enters the model via the §4 component model only.

2. UC realization mapping (analysis classes → design elements)

Legend — Analysis class (OpenUP stereotype): «controller», «entity», «boundary». Design element: crate::module::item (Rust). "WI-2" marks elements introduced or re-homed by this work item; everything else exists at 899fde8.

UC	Analysis class	Stereotype	Design element	Notes
UC-01 Register	AccountRegistry	controller	sb-api::routes::{register, seed_users}	argon2 hash via sb-auth::hash; JWT via sb-auth::jwt
	UserAccount	entity	sb-shared::user::User, Role	persisted via sb-db::Database
	AuthBoundary	boundary	POST /api/auth/register, AuthResponse
UC-02 Authenticate	Authenticator	controller	sb-api::routes::login, sb-auth::{hash::verify_password, jwt::create_token}
	TokenService	boundary	POST /api/auth/login, AuthResponse, middleware::auth::auth_middleware	middleware guards all UC-03…12
UC-03 Manage Characters	CharacterFactory	controller	sb-core::character::create_character	takes injected rng (WI-1)
	Character	entity	sb-shared::character::Character (+ Race, Class, CharacterStats)
	CharacterCatalog	boundary	GET/POST /api/users/{id}/characters, GET /api/characters/{id}	store: AppState.characters
	ResourceRegenerator	entity	sb-core::character::apply_regen (+ regen constants — WI-2 names them)	included sub-flow
UC-04 Browse Catalogue	CatalogueBrowser	boundary	GET /api/{races,classes,items,enemies,adventures}; response types sb-shared::responses	data from sb-common JSON via sb-core::{character::RACES/CLASSES, data, items}
	GameData	entity	sb-core::data::{EnemyDef, ZoneDef, EncounterEntry, LootDrop}, items::load_all_items
UC-05 Train Stat	TrainingService	controller	sb-core::services::train_stat	error type DomainError (WI-2)
	TrainingGrounds	entity	sb-core::character::TRAINING_GROUNDS, training_cost (+ cost constants WI-2)
	GymBoundary	boundary	GET/POST /api/characters/{id}/gym, GymResponse, TrainStatResponse
UC-06 Manage Equipment	EquipmentService	controller	sb-core::services::{equip_item, unequip_item}	DomainError (WI-2)
	Equipment/Inventory	entity	Character.equipment / .inventory, sb-shared::item::Item
	EquipmentBoundary	boundary	POST /api/characters/{id}/{equip,unequip}
UC-07 Trade at Shop	ShopService	controller	sb-api::routes::{shop_action, buy_item, sell_item} (handler-side; extraction candidate, design note Q3)	prices: sb-core::items::{item_price, item_sell_price}
	ShopStock	entity	AppState.shop_stock	persisted via sb-db
	ShopBoundary	boundary	GET/POST /api/characters/{id}/shop, ShopResponse, ShopActionResponse
UC-08 Run Adventure	AdventureService	controller	sb-core::adventure::run_adventure (new, WI-2) + services::pick_enemy → Result (WI-2)	takes injected rng; DomainError (WI-2)
	CombatEngine	entity	sb-core::combat::{resolve_combat_full, resolve_attack, crit tables, open_ended_roll} + combat constants (WI-2)
	Combatant	entity	sb-core::combat::CombatStats	built from Character/EnemyDef
	SpellEffect / BardSong	entity	sb-core::combat::SpellEffect, sb-core::spells, sb-core::songs
	AdventureBoundary	boundary	GET /api/characters/{id}/adventure; AdventureRunResponse (new, WI-2), sb-shared::responses::CombatLog
UC-09 Heal at Temple	HealingService	controller	sb-api::routes::heal_character (handler-side; extraction candidate, Q3)
	TempleBoundary	boundary	POST /api/characters/{id}/heal; HealResponse (new, WI-2)
UC-10 Practice Bard Song	SongService	controller	sb-api::routes::set_song; sb-core::songs::available_songs
	BardSong	entity	sb-core::songs::BARD_SONGS, Character.active_song
	SongBoundary	boundary	GET/POST /api/characters/{id}/songs, SongsResponse, SetSongResponse
UC-11 Study Magic	MagicService	controller	sb-api::routes::{get_spells, learn_spell_level}; sb-core::spells::{spells_for_class, spell_learn_cost, max_spell_points, caster_spell_level (WI-2)}
	Spell	entity	sb-core::spells::SpellDef, Character.{known_spells, active_spell, spell_points}
	MagicBoundary	boundary	GET/POST /api/characters/{id}/spells; SpellbookResponse, LearnSpellResponse (new, WI-2)
UC-12 Level Up	ReviewBoard	controller	sb-core::character::level_up	DomainError (WI-2)
	Progression	entity	sb-core::character::{xp_for_level, level_up_cost, MAX_LEVEL} (+ curve constants WI-2)
	ReviewBoundary	boundary	POST /api/characters/{id}/level-up, LevelUpResponse

Cross-cutting design elements (WI-2): sb-core::error::DomainError + sb-api::routes::domain_status (status mapping table, design note §4.1) realize the error paths of UC-05/06/08/12; sb-core::constants realizes NFR "no magic numbers"; sb-api::routes::responses realizes NFR-19 (wire-format freeze).

Dependency rule check (Clean Architecture): all controllers/entities above live in sb-core/sb-shared (domain side, no HTTP imports); all boundaries live in sb-api; the single current violations (ShopService, HealingService, parts of MagicService in sb-api) are recorded as debt with a follow-up question — the model must not paper over them (stale docs are defects).

2a. Analysis interactions (associations + dependencies, added 2026-10-03)

Within each realization package the analysis classes collaborate per the robustness rule boundary ↔ controller ↔ entity (boundary never touches entity directly — exception: UC-04 has no controller, its boundary reads the static catalogue entity). Each association serves the UC's Basic Path steps (boundary receives the actor request, controller applies the rules, entities hold the state). Cross-cutting: the four «uses» dependencies realize the error paths (Alternate/Exception flows) named in the cross-cutting paragraph above.

UC	From	To	Type	Serves
UC-01	AuthBoundary	AccountRegistry	Association	MSS steps 1–4
UC-01	AccountRegistry	UserAccount	Association	MSS steps 3–4
UC-02	TokenService	Authenticator	Association	MSS steps 1–3
UC-03	CharacterCatalog	CharacterFactory	Association	MSS (create) steps 1–4
UC-03	CharacterFactory	Character	Association	MSS steps 3–4
UC-03	CharacterFactory	ResourceRegenerator	Association	list/view (regen on return)
UC-04	CatalogueBrowser	GameData	Association (no controller in this realization)	MSS steps 1–2
UC-05	GymBoundary	TrainingService	Association	MSS steps 1–5
UC-05	TrainingService	TrainingGrounds	Association	MSS steps 3–4
UC-06	EquipmentBoundary	EquipmentService	Association	MSS (equip) + unequip
UC-06	EquipmentService	Equipment/Inventory	Association	MSS steps 2–3
UC-07	ShopBoundary	ShopService	Association	MSS (buy) + sell
UC-07	ShopService	ShopStock	Association	MSS steps 3–4
UC-08	AdventureBoundary	AdventureService	Association	MSS steps 1–9
UC-08	AdventureService	CombatEngine	Association	MSS step 5
UC-08	AdventureService	Combatant	Association	MSS step 5
UC-08	AdventureService	SpellEffect / BardSong	Association	MSS steps 5, 8
UC-09	TempleBoundary	HealingService	Association	MSS steps 1–3
UC-10	SongBoundary	SongService	Association	MSS steps 1–2 + clear
UC-10	SongService	BardSong	Association	MSS steps 1–2
UC-11	MagicBoundary	MagicService	Association	view + learn + activate
UC-11	MagicService	Spell	Association	learn + activate steps
UC-12	ReviewBoundary	ReviewBoard	Association	MSS steps 1–3
UC-12	ReviewBoard	Progression	Association	MSS step 2

The authoritative connector count is 24 associations (UC-01:2, UC-02:1, UC-03:3, UC-04:1, UC-05:2, UC-06:2, UC-07:2, UC-08:4 — its realization has one boundary, one controller and three entities, UC-09:1, UC-10:2, UC-11:2, UC-12:2) plus 4 cross-cutting dependencies below — 28 connectors in total.

UC	From (controller)	To	Type	Serves
UC-05	TrainingService	DomainError (Architecture Overview)	Dependency «uses»	Alternate flows (error paths)
UC-06	EquipmentService	DomainError (Architecture Overview)	Dependency «uses»	Alternate flows (error paths)
UC-08	AdventureService	DomainError (Architecture Overview)	Dependency «uses»	Exception (unknown enemy → 500)
UC-12	ReviewBoard	DomainError (Architecture Overview)	Dependency «uses»	Alternate flows (error paths)

3. Design component model (joint architecture, added 2026-10-03)

Package Analysis-Design / Design — components of the three repos and their dependency rule (sources: design note §2–3, mapping §2 dependency paragraph, client repo @ 34dc02f, common repo @ wi-2-openup-docs). Every component note carries the UCs it serves.

Component	Kind	Notes (traceability)
skara-brae-client	Component (presentation tier)	Vue 3.5 SPA (TypeScript, Pinia, Vite); monolithic App.vue @ 34dc02f; JWT bearer; REST via Vite proxy to :8080. Serves UC-01…12 as the player-facing boundary.
sb-api	Component (boundary/adapter)	Axum routes/handlers, domain_status, responses (wire-format freeze). May import sb-core, sb-shared, sb-common, sb-db, sb-auth (design §3). Serves all UC boundaries per §2.
sb-auth	Component (adapter)	argon2 hashing + JWT (UC-01/02). Imports sb-shared.
sb-db	Component (adapter)	persistence via sb-db::Database. Imports sb-shared.
sb-core	Component (domain)	controllers/entities: adventure (UC-08), services (UC-05/06), character (UC-03/12), combat, spells (UC-11), songs (UC-10), data/items (UC-04). Must not reference axum/http/serde_json::json!/tokio/sb-db/sb-api (design §3).
sb-shared	Component (domain types)	User, Character, Item, response types. Zero HTTP imports. Entities of all UCs.
sb-common	Component (data)	bilingual data package: data/ JSON (items, enemies, spells, zones), rust/ crate, ts/ package, codegen/. UC-04 data source; consumed by sb-core + sb-api; future client codegen.

Dependencies (arrows = depends on): skara-brae-client → sb-api (REST/JSON); sb-api → {sb-core, sb-shared, sb-db, sb-auth, sb-common}; sb-core → {sb-shared, sb-common}; sb-db → sb-shared; sb-auth → sb-shared. The dependency rule: inward toward sb-core/sb-shared (domain); adapters (sb-api/sb-db/sb-auth) and the client at the edge.

Figure: joint component architecture (rendered from the EA model via scripts/openup/export-diagram-images.ps1). Per-UC realization figures: uc-01-realization.png … uc-12-realization.png in this folder; they are embedded in the Architecture Notebook (§9.2).

4. Research summary — keyfob-station EA pipeline (reference)

Source: read-only clone http://192.168.1.10:3000/jan/keyfob-station.git (inspected 2026-10-03; no modifications).

• Model file: docs/openup/model/keyfob-station.eapx (MS Access database — the EA native format; EABase-derived). Never hand-edited.
• Structure: Model → Requirements package → Use Case Model package containing Actor and UseCase elements; scenario lists are stored on each use case as named scenarios of type Basic Path / Alternate / Exception, each with ordered steps carrying a per-step Actor tag and notes. An Analysis-Design package holds one UC-N Realization package per use case (realization diagrams + design elements).
• Builders are surgical scripts: scripts/add-*.ps1 (PowerShell driving the EA COM object New-Object -ComObject EA.App, $repo.OpenFile($modelPath)). Each script opens the model, adds/rebuilds exactly one package's contents, and closes it — because EA repository IDs and package rebuilds clobber manual edits, hand edits do not survive; all content lives in the scripts (scenario text is embedded as PowerShell arrays of Name/Type/Notes/Steps). This matches our standards note: model additions are surgical; builders rebuild whole packages.
• Exports: scripts/export-model-json.ps1 walks the Use Case Model package and emits exports/use-case-model.json + supplementary-requirements.json; realization diagrams are exported to PDF/PNG into docs/openup/analysis-design/. The JSON export is the doc-machine readable form of the same content.
• Windows-only: the pipeline runs on Windows (EA is a Win32 app; scripts use .ps1 + COM). For Skara Brae, the same pattern applies when the modeling WI lands: keep docs/openup/*.md (this file set) as the source the builder scripts embed, never the reverse.

Adoption decision for Skara Brae (updated at 1B rework): the EA model + generator pipeline is in WI-2 scope. This document (§1–2) plus requirements/use-case-model.md are the content source; the model-home recommendation, agent preparation steps, generator scripts (scripts/openup/build-model.ps1, export-model.ps1), and the human-gate checklist are specified in design-wi-2-architecture-cleanup.md §11. The .eapx interactive editing session remains human-gated; everything around it is COD-phase agent work.