# hiravem/lunarconsole architecture

> Architecture diagram of the GitHub repository hiravem/lunarconsole, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hiravem/lunarconsole
- Repository: https://github.com/hiravem/lunarconsole

## Overview

1. **Repository shape**
   - This is a .NET 10 solution split into two main runtime projects: `Lunar.Core` and `Lunar.Console`, plus `Lunar.Core.Tests`.
   - The architecture is intentionally layered for a future Unity port: the game rules live in `Lunar.Core`; the console app only handles I/O, persistence, randomness, and wiring.

2. **Core boundary**
   - `Lunar.Core` is the business-logic center.
   - It contains the **Domain** model, **Application** orchestration, DTOs, and interfaces that abstract infrastructure concerns.
   - Nothing in `Lunar.Core` depends on console APIs, JSON storage, or random number implementation details.

3. **Domain subsystem**
   - `Lunar.Core/Domain` is organized by gameplay concepts: `Characters`, `Combat`, `Inventory`, `Items`, `Bosses`, `World`, `Skills`, and `Events`.
   - The domain uses a rich OOP style: entities and aggregates own behavior such as taking damage, equipping items, resolving combat commands, and boss phase transitions.
   - Important aggregates include `CombatSession`, `Inventory`, and `EquipmentLoadout`.

4. **Character and combat model**
   - Characters are modeled under `Domain/Characters` with shared stat/health abstractions and specialized player/enemy/boss behavior.
   - Combat is command-driven: `ICombatCommand` has concrete actions like attack, flee, skill use, and item use.
   - Combat resolution is centralized in `CombatSession`, while damage/crit calculation is pushed into domain services such as `DamageCalculator` and `CriticalCalculator`.

5. **World and encounter flow**
   - Exploration is separated from combat in `Domain/World`.
   - `EncounterTable` and `EnemyFactory` support weighted/random encounter generation, while `Explore` and encounter-related types represent the result of a day action.
   - Boss logic is isolated in `Domain/Bosses`, with factory/phase abstractions so boss behavior can evolve without changing combat orchestration.

6. **Inventory, items, and equipment**
   - Inventory and equipment are distinct aggregates rather than one flat bag-of-items implementation.
   - `Inventory` tracks item stacks and capacity; `EquipmentLoadout` manages slots and stat modifiers.
   - `ItemFactory` and item polymorphism make items data-driven and extensible, which matters for loot, save/load, and merchant flows.

7. **Application layer orchestration**
   - `Lunar.Core/Application` contains the use cases that coordinate the domain without embedding rules.
   - Key use cases include `StartGameUseCase`, `ExploreUseCase`, `CombatUseCase`, `BossBattleUseCase`, `RestUseCase`, `AdvanceDayUseCase`, `EquipItemUseCase`, `UseItemUseCase`, and save/load use cases.
   - These use cases are the main integration points for the UI and are the right abstraction level for sequence diagrams.

8. **Runtime state and save model**
   - `GameSession` is the in-memory source of truth for a running game: player state, current day, difficulty, day flags, and active combat session.
   - `GameState` is the save/load snapshot representation, designed to be serialized cleanly rather than persisting live object graphs.
   - This separation means save/load does not leak runtime object identity into storage.

9. **Event flow**
   - Domain events are defined in `Domain/Events` as pure data.
   - The application layer exposes `IEventBus`; the domain collects events, and use cases publish them after execution.
   - This creates a clear boundary: the domain records what happened, while the outer layers decide how to react.

10. **Console infrastructure**
   - `Lunar.Console/Infrastructure` implements application interfaces:
     - `JsonSaveRepository` for persistence,
     - `RandomService` for randomness,
     - `InMemoryEventBus` for event dispatch.
   - These are replaceable adapters, which is important for testing and later Unity integration.

11. **Console presentation**
   - `Lunar.Console/Presentation` is a text UI layer composed of `ConsoleGamePresenter`, `InputReader`, `OutputWriter`, and screen classes.
   - Screens are split by gameplay mode: main menu, gameplay, combat, inventory, equipment, and merchant.
   - Presentation calls use cases and renders DTOs; it should not touch domain objects directly for rules like damage, equip validation, or loot generation.

12. **Primary data flow**
   - The typical flow is: console input → screen/presenter → application use case → domain aggregate/service → event publication and state mutation → DTO returned → console output.
   - Example paths include:
     - New game → `StartGameUseCase` → `GameSession`
     - Explore → `ExploreUseCase` → encounter resolution → possible combat
     - Combat → `CombatUseCase` → `CombatSession` → loot/event updates
     - Save/Load → `GameSession` ↔ `GameState` ↔ `JsonSaveRepository`

13. **Testing structure**
   - `Lunar.Core.Tests` targets the core logic directly, which matches the architecture goal of keeping gameplay rules testable without the console layer.
   - The sprint-named test files indicate the repo is organized around incremental gameplay milestones rather than UI tests.
   - For an architecture diagram, this project is best shown as verifying domain/application behavior at the core boundary.

14. **What matters most for a diagram**
   - Draw `Lunar.Core` as the central reusable engine.
   - Show `Lunar.Console` as a thin shell with two branches: Infrastructure adapters and Presentation screens.
   - Emphasize that use cases orchestrate domain behavior, `GameSession` holds runtime state, and `GameState` handles persistence snapshots.
   - External effects are limited to console I/O, JSON file save/load, and random number generation.

Main entry points: [`Lunar.Core/Application/UseCases`](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/UseCases) (Use Cases), [`Lunar.Core/Domain/Combat`](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Combat) (Combat), [`Lunar.Core.Tests`](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core.Tests) (Core Tests), [`Lunar.Console/Infrastructure`](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Console/Infrastructure) (Infrastructure)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Lunar.Core"]
  node_core_app["Application<br/>orchestration layer<br/>[Application]"]
  node_core_session[("GameSession<br/>runtime state<br/>[GameSession.cs]")]
  node_core_state["GameState<br/>save snapshot<br/>[GameState.cs]"]
  node_core_presenter["Presenter Mapper<br/>dto mapper"]
  node_core_bus["Event Bus<br/>boundary interface<br/>[IEventBus.cs]"]
  node_core_save["Save Repo<br/>boundary interface<br/>[ISaveRepository.cs]"]
  node_core_rng["Random Service<br/>boundary interface<br/>[IRandomService.cs]"]
  node_core_usecases["Use Cases<br/>application services<br/>[UseCases]"]
  node_domain_combat{{"Combat<br/>domain subsystem<br/>[Combat]"}}
  node_domain_characters{{"Characters<br/>domain subsystem<br/>[Characters]"}}
  node_domain_inventory[("Inventory<br/>domain aggregate<br/>[Inventory]")]
  node_domain_items["Items<br/>domain model<br/>[Items]"]
  node_domain_world["World<br/>exploration domain<br/>[World]"]
  node_domain_bosses{{"Bosses<br/>domain subsystem<br/>[Bosses]"}}
  node_domain_events["Domain Events<br/>pure data<br/>[Events]"]
end

subgraph group_console["Lunar.Console"]
  node_console_prog["Program<br/>composition root<br/>[Program.cs]"]
  node_console_infra["Infrastructure<br/>adapters<br/>[Infrastructure]"]
  node_console_ui["Presentation<br/>text ui<br/>[Presentation]"]
  node_console_screens["Screens<br/>screen flow<br/>[Screens]"]
end

subgraph group_tests["Lunar.Core.Tests"]
  node_tests_core["Core Tests<br/>test project<br/>[Lunar.Core.Tests]"]
end

node_console_prog -->|"wires"| node_console_infra
node_console_prog -->|"runs"| node_console_ui
node_console_ui -->|"navigates"| node_console_screens
node_console_ui -->|"calls"| node_core_usecases
node_console_infra -->|"implements"| node_core_bus
node_console_infra -->|"implements"| node_core_save
node_console_infra -->|"implements"| node_core_rng
node_core_usecases -->|"mutates"| node_core_session
node_core_usecases -->|"persists"| node_core_state
node_core_usecases -->|"maps"| node_core_presenter
node_core_usecases -->|"explores"| node_domain_world
node_core_usecases -->|"resolves"| node_domain_combat
node_core_usecases -->|"applies"| node_domain_inventory
node_core_usecases -->|"spawns"| node_domain_bosses
node_domain_combat -->|"targets"| node_domain_characters
node_domain_combat -->|"uses"| node_domain_items
node_domain_inventory -->|"stores"| node_domain_items
node_domain_world -->|"generates"| node_domain_characters
node_domain_world -->|"may trigger"| node_domain_bosses
node_domain_bosses -->|"enters"| node_domain_combat
node_domain_combat -->|"emits"| node_domain_events
node_tests_core -.->|"verifies"| node_core_usecases
node_tests_core -.->|"verifies"| node_domain_combat
node_tests_core -.->|"verifies"| node_domain_inventory
node_tests_core -.->|"verifies"| node_domain_world

click node_core_app "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application"
click node_core_session "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/GameSession.cs"
click node_core_state "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/GameState.cs"
click node_core_presenter "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/UseCases/GameplayPresenterMapper.cs"
click node_core_bus "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/Interfaces/IEventBus.cs"
click node_core_save "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/Interfaces/ISaveRepository.cs"
click node_core_rng "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/Interfaces/IRandomService.cs"
click node_core_usecases "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/UseCases"
click node_domain_combat "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Combat"
click node_domain_characters "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Characters"
click node_domain_inventory "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Inventory"
click node_domain_items "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Items"
click node_domain_world "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/World"
click node_domain_bosses "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Bosses"
click node_domain_events "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Events"
click node_console_prog "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Console/Program.cs"
click node_console_infra "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Console/Infrastructure"
click node_console_ui "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Console/Presentation"
click node_console_screens "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Console/Presentation/Screens"
click node_tests_core "https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core.Tests"

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_core_app,node_core_session,node_core_state,node_core_presenter,node_core_bus,node_core_save,node_core_rng,node_core_usecases,node_domain_combat,node_domain_characters,node_domain_inventory,node_domain_items,node_domain_world,node_domain_bosses,node_domain_events toneBlue
class node_console_prog,node_console_infra,node_console_ui,node_console_screens toneAmber
class node_tests_core toneMint
```

## Components

### Lunar.Core

Reusable game engine: domain rules, application orchestration, and runtime state.

- [Application](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application): orchestration layer · Coordinates game use cases, session state, DTO mapping, and boundary interfaces. · `Lunar.Core/Application`
- [GameSession](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/GameSession.cs): runtime state · In-memory source of truth for a running game: player state, day, difficulty, flags, and active combat. · `Lunar.Core/Application/GameSession.cs`
- [GameState](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/GameState.cs): save snapshot · Serializable snapshot model used for persistence instead of live object graphs. · `Lunar.Core/Application/GameState.cs`
- [Presenter Mapper](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/UseCases/GameplayPresenterMapper.cs): dto mapper · Shapes application data into presentation-friendly DTOs and views. · `Lunar.Core/Application/UseCases/GameplayPresenterMapper.cs`
- [Event Bus](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/Interfaces/IEventBus.cs): boundary interface · Application-facing event publishing abstraction used after domain execution. · `Lunar.Core/Application/Interfaces/IEventBus.cs`
- [Save Repo](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/Interfaces/ISaveRepository.cs): boundary interface · Persistence abstraction for loading and storing game state snapshots. · `Lunar.Core/Application/Interfaces/ISaveRepository.cs`
- [Random Service](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/Interfaces/IRandomService.cs): boundary interface · Randomness abstraction used by use cases and domain-adjacent logic. · `Lunar.Core/Application/Interfaces/IRandomService.cs`
- [Use Cases](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Application/UseCases): application services · Start, explore, combat, rest, equip, merchant, and save/load flows. · `Lunar.Core/Application/UseCases`
- [Combat](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Combat): domain subsystem · Command-driven combat resolution with calculators, commands, and encounter results. · `Lunar.Core/Domain/Combat`
- [Characters](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Characters): domain subsystem · Shared character model with stats, health, damage, and damageable behavior. · `Lunar.Core/Domain/Characters`
- [Inventory](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Inventory): domain aggregate · Tracks item stacks, capacity, and equipment loadout interactions. · `Lunar.Core/Domain/Inventory`
- [Items](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Items): domain model · Item polymorphism, factories, types, and loot tables. · `Lunar.Core/Domain/Items`
- [World](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/World): exploration domain · Day actions and weighted encounter generation for exploration flow. · `Lunar.Core/Domain/World`
- [Bosses](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Bosses): domain subsystem · Boss model, factory, and phase abstractions for special encounters. · `Lunar.Core/Domain/Bosses`
- [Domain Events](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core/Domain/Events): pure data · Event payloads recorded by the domain and published by the application layer. · `Lunar.Core/Domain/Events`

### Lunar.Console

Thin runtime shell for console I/O, persistence, randomness, and presentation.

- [Program](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Console/Program.cs): composition root · Bootstraps the console runtime and wires adapters to the core application. · `Lunar.Console/Program.cs`
- [Infrastructure](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Console/Infrastructure): adapters · Console-side implementations of persistence, randomness, and event dispatch. · `Lunar.Console/Infrastructure`
- [Presentation](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Console/Presentation): text ui · Console presenters and screens that read input and render DTOs. · `Lunar.Console/Presentation`
- [Screens](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Console/Presentation/Screens): screen flow · Mode-specific UI for menu, gameplay, combat, inventory, equipment, and merchant. · `Lunar.Console/Presentation/Screens`

### Lunar.Core.Tests

Core behavior tests focused on gameplay rules and application flows.

- [Core Tests](https://github.com/hiravem/lunarconsole/blob/master/Lunar.Core.Tests): test project · Verifies domain and application behavior at the reusable core boundary. · `Lunar.Core.Tests`

## Connections

- Program → Infrastructure: wires · Composition root connects adapters used by the runtime.
- Program → Presentation: runs · Program starts the text UI shell.
- Presentation → Screens: navigates · Presenter delegates to gameplay-specific screens.
- Presentation → Use Cases: calls · Screens invoke application use cases rather than domain objects directly.
- Infrastructure → Event Bus: implements · Console event bus adapter satisfies the application boundary.
- Infrastructure → Save Repo: implements · JSON repository persists and loads game snapshots.
- Infrastructure → Random Service: implements · Console random service supplies randomness to the core.
- Use Cases → GameSession: mutates · Use cases coordinate runtime state changes.
- Use Cases → GameState: persists · Save/load use cases translate to and from snapshot state.
- Use Cases → Presenter Mapper: maps · Use cases prepare DTOs for presentation.
- Use Cases → World: explores · Exploration use cases drive encounter generation.
- Use Cases → Combat: resolves · Combat and boss battle use cases execute combat sessions.
- Use Cases → Inventory: applies · Equip and item use cases manipulate inventory and loadout.
- Use Cases → Bosses: spawns · Boss battle flows create or advance boss encounters.
- Combat → Characters: targets · Combat commands and calculators act on characters.
- Combat → Items: uses · Item use commands pull from the item model.
- Inventory → Items: stores · Inventory and loadout manage item stacks and equipment.
- World → Characters: generates · Encounter tables and enemy factories produce combatants.
- World → Bosses: may trigger · Exploration can lead into boss encounters.
- Bosses → Combat: enters · Boss phases resolve through the combat engine.
- Combat → Domain Events: emits · Combat records domain events for later publication.
- Core Tests → Use Cases: verifies · Tests cover orchestration and boundary behavior.
- Core Tests → Combat: verifies · Tests cover core combat rules and outcomes.
- Core Tests → Inventory: verifies · Tests cover item, equip, and capacity behavior.
- Core Tests → World: verifies · Tests cover exploration and encounter selection.
