# tucefull/3-muenzen-spiel architecture

> Architecture diagram of the GitHub repository tucefull/3-muenzen-spiel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tucefull/3-muenzen-spiel
- Repository: https://github.com/tucefull/3-muenzen-spiel

## Overview

#### Purpose and Entry Points
This is a presentation-oriented Vue 3/TypeScript simulator for the imperfect-information three-coin game. It demonstrates a randomized, small-memory Player 1 strategy and exposes each round as a trace.

The primary desktop entry is Electron: `electron/main.cjs`, which loads the Vite frontend rooted at `index.html`. The frontend bootstraps from `src/main.ts` into `src/App.vue`.

#### Desktop Shell and Runtime Boundary
Electron provides the application window and development launch integration, while Vue/Vite owns the rendered UI.

- Electron main process: `electron/main.cjs`
- Vite application document: `index.html`
- Build/runtime configuration: `vite.config.ts`, `package.json`

The game engine runs in the frontend TypeScript context; no server, database, or network service is represented.

#### Application Composition
`src/App.vue` is the top-level orchestration layer. It connects simulation state and commands to the interactive display.

- Root composition: `src/App.vue`
- Simulation state/controller composable: `src/composables/useSimulation.ts`
- Shared UI styling: `src/styles.css`

The composable is the UI-to-domain boundary: controls such as step, batch runs, seed/reset behavior, trace retention, and display state should remain outside the core game rules.

#### Simulation Control Flow
User actions flow from the application UI into `useSimulation`, which advances or resets a simulation and returns reactive state for rendering. Batch actions (“Run 10” / “Run 100”) repeatedly apply the same single-round transition.

- Controller/state layer: `src/composables/useSimulation.ts`
- Round simulation orchestration: `src/game/simulator.ts`
- Core state and trace contracts: `src/game/types.ts`

Each completed round produces state suitable for both subsequent strategy decisions and a human-readable trace record.

#### Game Domain and Rule Engine
The engine encodes the three-coin game’s authoritative transitions: Player 1 acts from only the observable count of heads/tails, Player 2 flips the selected coin and may swap the other two, and terminal states are `HHH` and `TTT`.

- Rule/state transition logic: `src/game/engine.ts`
- Simulation sequencing: `src/game/simulator.ts`
- Domain types: `src/game/types.ts`

This is the main correctness boundary: Vue components should render domain outputs, not duplicate legal-move or win/loss logic.

#### Player Strategies and Randomness
Player strategies are separated from engine mechanics. Player 1 implements the randomized, memory-limited behavior central to the demo; Player 2 supplies the adversarial flip/swap behavior. Randomness is seedable for reproducible runs.

- Player 1 strategy: `src/game/player1.ts`
- Player 2 strategy: `src/game/player2.ts`
- Seeded RNG abstraction: `src/game/rng.ts`

The RNG should be injected or passed through simulation/strategy paths rather than using uncontrolled ambient randomness, preserving deterministic traces for a given seed.

#### Presentation Components
The UI is split between current-game controls/status and the round history. Optional coin visibility is a presentation concern and must not alter Player 1’s observation model.

- Current game panel: `src/components/GamePanel.vue`
- Trace rendering: `src/components/TraceTable.vue`
- Root wiring: `src/App.vue`

Main entry points: [`src/game/simulator.ts`](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/simulator.ts) (Round simulator), [`src/game/types.ts`](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/types.ts) (Game contracts), [`src/App.vue`](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/App.vue) (App root), [`src/composables/useSimulation.ts`](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/composables/useSimulation.ts) (Simulation controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop shell"]
  node_electron["Electron main<br/>desktop process<br/>[main.cjs]"]
  node_document["Vite document<br/>app document<br/>[index.html]"]
  node_vite["Vite config<br/>build config<br/>[vite.config.ts]"]
end

subgraph group_ui["Vue presentation"]
  node_app["App root<br/>Vue root<br/>[App.vue]"]
  node_main["Vue bootstrap<br/>frontend entry<br/>[main.ts]"]
  node_game_panel["Game panel<br/>Vue component<br/>[GamePanel.vue]"]
  node_trace_table["Trace table<br/>Vue component<br/>[TraceTable.vue]"]
  node_styles["Shared styles<br/>CSS<br/>[styles.css]"]
end

subgraph group_simulation["Simulation domain"]
  node_simulation_state["Simulation controller<br/>Vue composable<br/>[useSimulation.ts]"]
  node_simulator["Round simulator<br/>simulation orchestration<br/>[simulator.ts]"]
  node_engine{{"Game engine<br/>rule engine<br/>[engine.ts]"}}
  node_types["Game contracts<br/>domain types<br/>[types.ts]"]
  node_player1["Player 1 strategy<br/>randomized strategy<br/>[player1.ts]"]
  node_player2["Player 2 strategy<br/>adversarial strategy<br/>[player2.ts]"]
  node_rng["Seeded RNG<br/>randomness service<br/>[rng.ts]"]
end

node_electron -->|"loads frontend"| node_document
node_vite -->|"builds"| node_document
node_document -->|"starts"| node_main
node_main -->|"mounts"| node_app
node_app -->|"uses"| node_simulation_state
node_app -->|"renders"| node_game_panel
node_app -->|"renders"| node_trace_table
node_app -.->|"applies"| node_styles
node_game_panel -->|"issues controls"| node_simulation_state
node_simulation_state -->|"steps and resets"| node_simulator
node_simulation_state -->|"exposes reactive state"| node_types
node_trace_table -->|"displays traces"| node_types
node_simulator -->|"applies transitions"| node_engine
node_simulator -->|"gets Player 1 action"| node_player1
node_simulator -->|"gets Player 2 action"| node_player2
node_simulator -->|"passes seeded randomness"| node_rng
node_simulator -->|"creates round trace"| node_types
node_engine -->|"reads and produces state"| node_types
node_player1 -->|"randomizes choices"| node_rng
node_player1 -->|"uses observation contract"| node_types
node_player2 -->|"uses action contract"| node_types

click node_electron "https://github.com/tucefull/3-muenzen-spiel/blob/master/electron/main.cjs"
click node_document "https://github.com/tucefull/3-muenzen-spiel/blob/master/index.html"
click node_vite "https://github.com/tucefull/3-muenzen-spiel/blob/master/vite.config.ts"
click node_app "https://github.com/tucefull/3-muenzen-spiel/blob/master/src/App.vue"
click node_main "https://github.com/tucefull/3-muenzen-spiel/blob/master/src/main.ts"
click node_game_panel "https://github.com/tucefull/3-muenzen-spiel/blob/master/src/components/GamePanel.vue"
click node_trace_table "https://github.com/tucefull/3-muenzen-spiel/blob/master/src/components/TraceTable.vue"
click node_styles "https://github.com/tucefull/3-muenzen-spiel/blob/master/src/styles.css"
click node_simulation_state "https://github.com/tucefull/3-muenzen-spiel/blob/master/src/composables/useSimulation.ts"
click node_simulator "https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/simulator.ts"
click node_engine "https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/engine.ts"
click node_types "https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/types.ts"
click node_player1 "https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/player1.ts"
click node_player2 "https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/player2.ts"
click node_rng "https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/rng.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_electron,node_document,node_vite toneBlue
class node_app,node_main,node_game_panel,node_trace_table,node_styles toneAmber
class node_simulation_state,node_simulator,node_engine,node_types,node_player1,node_player2,node_rng toneMint
```

## Components

### Desktop shell

- [Electron main](https://github.com/tucefull/3-muenzen-spiel/blob/master/electron/main.cjs): desktop process · Creates the application window and loads the frontend. · `electron/main.cjs`
- [Vite document](https://github.com/tucefull/3-muenzen-spiel/blob/master/index.html): app document · `index.html`
- [Vite config](https://github.com/tucefull/3-muenzen-spiel/blob/master/vite.config.ts): build config · `vite.config.ts`

### Vue presentation

- [App root](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/App.vue): Vue root · Composes simulation state with presentation components. · `src/App.vue`
- [Vue bootstrap](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/main.ts): frontend entry · `src/main.ts`
- [Game panel](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/components/GamePanel.vue): Vue component · Shows current state, controls, and status. · `src/components/GamePanel.vue`
- [Trace table](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/components/TraceTable.vue): Vue component · Renders completed-round history. · `src/components/TraceTable.vue`
- [Shared styles](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/styles.css): CSS · `src/styles.css`

### Simulation domain

- [Simulation controller](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/composables/useSimulation.ts): Vue composable · Owns reactive state, commands, seed/reset, and trace retention. · `src/composables/useSimulation.ts`
- [Round simulator](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/simulator.ts): simulation orchestration · Sequences one-round transitions and trace creation. · `src/game/simulator.ts`
- [Game engine](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/engine.ts): rule engine · Authoritative legal moves and terminal-state transitions. · `src/game/engine.ts`
- [Game contracts](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/types.ts): domain types · State and trace contracts shared across the simulation. · `src/game/types.ts`
- [Player 1 strategy](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/player1.ts): randomized strategy · Uses only observable heads/tails counts. · `src/game/player1.ts`
- [Player 2 strategy](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/player2.ts): adversarial strategy · Flips the selected coin and may swap the others. · `src/game/player2.ts`
- [Seeded RNG](https://github.com/tucefull/3-muenzen-spiel/blob/master/src/game/rng.ts): randomness service · Provides reproducible random decisions. · `src/game/rng.ts`

## Connections

- Electron main → Vite document: loads frontend
- Vite config → Vite document: builds
- Vite document → Vue bootstrap: starts
- Vue bootstrap → App root: mounts
- App root → Simulation controller: uses
- App root → Game panel: renders
- App root → Trace table: renders
- App root → Shared styles: applies
- Game panel → Simulation controller: issues controls
- Simulation controller → Round simulator: steps and resets
- Simulation controller → Game contracts: exposes reactive state
- Trace table → Game contracts: displays traces
- Round simulator → Game engine: applies transitions
- Round simulator → Player 1 strategy: gets Player 1 action
- Round simulator → Player 2 strategy: gets Player 2 action
- Round simulator → Seeded RNG: passes seeded randomness
- Round simulator → Game contracts: creates round trace
- Game engine → Game contracts: reads and produces state
- Player 1 strategy → Seeded RNG: randomizes choices
- Player 1 strategy → Game contracts: uses observation contract
- Player 2 strategy → Game contracts: uses action contract