# a1j9o94/eclipse-rougelike architecture

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

- Interactive diagram: https://gitdiagram.com/a1j9o94/eclipse-rougelike
- Repository: https://github.com/a1j9o94/eclipse-rougelike

## Overview

Eclipse · Second Dawn is a browser-based strategy game with solo AI, multiplayer rooms, resumable profiles, and an authoritative shared rules engine. Players create or join a game, take decisions through the board, and receive persisted game state and history; room play also supports spectators, recovery/undo, and leaderboard results. The graph separates client workflows, shared game rules, and Convex identity, room, match, and history services. Relationship evidence is limited to the README and supplied excerpts/index references; unsampled subsystem links are omitted rather than inferred.

Main entry points: [`convex/eclipseMatches.ts`](https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseMatches.ts) (Solo matches), [`convex/eclipseRooms.ts`](https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseRooms.ts) (Multiplayer rooms), [`src/second-dawn-game`](https://github.com/a1j9o94/eclipse-rougelike/tree/main/src/second-dawn-game) (Game workflows), [`shared/eclipse/engine.ts`](https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/engine.ts) (Command engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Game client"]
  node_game_ui["Game workflows"]
  node_board["Board and decisions"]
  node_session["Session sync"]
  node_drafts["Action drafts"]
  node_settings["Presentation settings"]
end

subgraph group_rules["Rules and gameplay"]
  node_game_rules["Rule options<br/>[gameRules.ts]"]
  node_setup["Game setup<br/>[setup.ts]"]
  node_catalog["Faction catalog<br/>[catalog.ts]"]
  node_state["Game state<br/>[rulesState.ts]"]
  node_engine["Command engine<br/>[engine.ts]"]
  node_combat["Combat resolution<br/>[battleEngine.ts]"]
  node_ai["AI planning<br/>[aiSearch.ts]"]
  node_history["History journal<br/>[history.ts]"]
end

subgraph group_backend["Convex services"]
  node_matches["Solo matches<br/>[eclipseMatches.ts]"]
  node_rooms["Multiplayer rooms<br/>[eclipseRooms.ts]"]
  node_store[("Persistent game data<br/>[schema.ts]")]
  node_upkeep["Scheduled upkeep"]
  node_validators["Input validation"]
end

subgraph group_account["Identity and records"]
  node_identity["Guest identity<br/>[eclipseIdentity.ts]"]
  node_public_history["Public history"]
  node_recovery["History recovery"]
  node_leaderboard["Leaderboard"]
  node_profiles["Player records"]
end

node_player(("Player"))

node_player -->|"plays"| node_game_ui
node_game_ui -.->|"renders"| node_board
node_board -->|"stores drafts"| node_drafts
node_game_ui -->|"syncs activity"| node_session
node_game_ui -->|"configures"| node_settings
node_game_rules -.->|"configures rules"| node_setup
node_setup -.->|"selects factions"| node_catalog
node_matches -->|"validates options"| node_game_rules
node_matches -->|"checks guest"| node_identity
node_rooms -->|"checks guest"| node_identity
node_matches -->|"creates game"| node_setup
node_matches -->|"applies command"| node_engine
node_engine -->|"resolves combat"| node_combat
node_engine -->|"updates state"| node_state
node_matches -->|"persists snapshot"| node_store
node_rooms -.->|"persists room"| node_store
node_matches -->|"journals actions"| node_history
node_matches -->|"reads history"| node_public_history
node_public_history -->|"formats entries"| node_history
node_player -->|"joins room"| node_rooms
node_rooms -.->|"starts match"| node_matches
node_matches -->|"plans AI turns"| node_ai
node_matches -->|"schedules upkeep"| node_upkeep
node_matches -.->|"syncs results"| node_leaderboard
node_rooms -->|"syncs results"| node_leaderboard
node_matches -.->|"recovers checkpoints"| node_recovery
node_session -.->|"loads saved games"| node_matches
node_validators -->|"validates selections"| node_catalog
node_profiles -.->|"links player"| node_identity

click node_game_ui "https://github.com/a1j9o94/eclipse-rougelike/tree/main/src/second-dawn-game"
click node_board "https://github.com/a1j9o94/eclipse-rougelike/blob/main/src/second-dawn-game/SecondDawnBoard.tsx"
click node_session "https://github.com/a1j9o94/eclipse-rougelike/tree/main/src/second-dawn-session"
click node_drafts "https://github.com/a1j9o94/eclipse-rougelike/blob/main/src/second-dawn-game/actionDraftStorage.ts"
click node_settings "https://github.com/a1j9o94/eclipse-rougelike/blob/main/src/second-dawn-game/presentationSettings.ts"
click node_game_rules "https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/gameRules.ts"
click node_setup "https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/setup.ts"
click node_catalog "https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/catalog.ts"
click node_state "https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/rulesState.ts"
click node_engine "https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/engine.ts"
click node_combat "https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/battleEngine.ts"
click node_ai "https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/aiSearch.ts"
click node_history "https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/history.ts"
click node_identity "https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseIdentity.ts"
click node_matches "https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseMatches.ts"
click node_rooms "https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseRooms.ts"
click node_store "https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/schema.ts"
click node_public_history "https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipsePublicHistory.ts"
click node_recovery "https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseHistoryRecovery.ts"
click node_leaderboard "https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseLeaderboardStore.ts"
click node_upkeep "https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseUpkeepTimer.ts"
click node_validators "https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseValidators.ts"
click node_profiles "https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipsePlayerStore.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_game_ui,node_board,node_session,node_drafts,node_settings toneBlue
class node_game_rules,node_setup,node_catalog,node_state,node_engine,node_combat,node_ai,node_history toneAmber
class node_matches,node_rooms,node_store,node_upkeep,node_validators toneMint
class node_identity,node_public_history,node_recovery,node_leaderboard,node_profiles toneRose
class node_player toneIndigo
```

## Components

### Game client

- [Game workflows](https://github.com/a1j9o94/eclipse-rougelike/tree/main/src/second-dawn-game): `src/second-dawn-game`
- [Board and decisions](https://github.com/a1j9o94/eclipse-rougelike/blob/main/src/second-dawn-game/SecondDawnBoard.tsx): `src/second-dawn-game/SecondDawnBoard.tsx`
- [Session sync](https://github.com/a1j9o94/eclipse-rougelike/tree/main/src/second-dawn-session): `src/second-dawn-session`
- [Action drafts](https://github.com/a1j9o94/eclipse-rougelike/blob/main/src/second-dawn-game/actionDraftStorage.ts): `src/second-dawn-game/actionDraftStorage.ts`
- [Presentation settings](https://github.com/a1j9o94/eclipse-rougelike/blob/main/src/second-dawn-game/presentationSettings.ts): `src/second-dawn-game/presentationSettings.ts`

### Rules and gameplay

- [Rule options](https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/gameRules.ts): `shared/eclipse/gameRules.ts`
- [Game setup](https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/setup.ts): `shared/eclipse/setup.ts`
- [Faction catalog](https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/catalog.ts): `shared/eclipse/catalog.ts`
- [Game state](https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/rulesState.ts): `shared/eclipse/rulesState.ts`
- [Command engine](https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/engine.ts): `shared/eclipse/engine.ts`
- [Combat resolution](https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/battleEngine.ts): `shared/eclipse/battleEngine.ts`
- [AI planning](https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/aiSearch.ts): `shared/eclipse/aiSearch.ts`
- [History journal](https://github.com/a1j9o94/eclipse-rougelike/blob/main/shared/eclipse/history.ts): `shared/eclipse/history.ts`

### Convex services

- [Solo matches](https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseMatches.ts): `convex/eclipseMatches.ts`
- [Multiplayer rooms](https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseRooms.ts): `convex/eclipseRooms.ts`
- [Persistent game data](https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/schema.ts): `convex/schema.ts`
- [Scheduled upkeep](https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseUpkeepTimer.ts): `convex/eclipseUpkeepTimer.ts`
- [Input validation](https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseValidators.ts): `convex/eclipseValidators.ts`

### Identity and records

- [Guest identity](https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseIdentity.ts): `convex/eclipseIdentity.ts`
- [Public history](https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipsePublicHistory.ts): `convex/eclipsePublicHistory.ts`
- [History recovery](https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseHistoryRecovery.ts): `convex/eclipseHistoryRecovery.ts`
- [Leaderboard](https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipseLeaderboardStore.ts): `convex/eclipseLeaderboardStore.ts`
- [Player records](https://github.com/a1j9o94/eclipse-rougelike/blob/main/convex/eclipsePlayerStore.ts): `convex/eclipsePlayerStore.ts`

### Other components

- **Player**

## Connections

- Player → Game workflows: plays (evidence: `README.md`)
- Game workflows → Board and decisions: renders (evidence: `src/second-dawn-game/actionDraftStorage.ts`)
- Board and decisions → Action drafts: stores drafts (evidence: `src/second-dawn-game/actionDraftStorage.ts`)
- Game workflows → Session sync: syncs activity (evidence: `README.md`)
- Game workflows → Presentation settings: configures (evidence: `src/second-dawn-game/sound/useGameSoundFeedback.ts`)
- Rule options → Game setup: configures rules
- Game setup → Faction catalog: selects factions
- Solo matches → Rule options: validates options (evidence: `convex/eclipseMatches.ts`)
- Solo matches → Guest identity: checks guest (evidence: `convex/eclipseMatches.ts`)
- Multiplayer rooms → Guest identity: checks guest (evidence: `convex/eclipseRooms.ts`)
- Solo matches → Game setup: creates game (evidence: `convex/eclipseMatches.ts`)
- Solo matches → Command engine: applies command (evidence: `convex/eclipseMatches.ts`)
- Command engine → Combat resolution: resolves combat (evidence: `shared/eclipse/engine.ts`)
- Command engine → Game state: updates state (evidence: `shared/eclipse/engine.ts`)
- Solo matches → Persistent game data: persists snapshot (evidence: `convex/eclipseMatches.ts`)
- Multiplayer rooms → Persistent game data: persists room
- Solo matches → History journal: journals actions (evidence: `convex/eclipseMatches.ts`)
- Solo matches → Public history: reads history (evidence: `convex/eclipseMatches.ts`)
- Public history → History journal: formats entries (evidence: `convex/eclipsePublicHistory.ts`)
- Player → Multiplayer rooms: joins room (evidence: `README.md`)
- Multiplayer rooms → Solo matches: starts match (evidence: `convex/eclipseRooms.ts`)
- Solo matches → AI planning: plans AI turns (evidence: `convex/eclipseMatches.ts`)
- Solo matches → Scheduled upkeep: schedules upkeep (evidence: `convex/eclipseMatches.ts`)
- Solo matches → Leaderboard: syncs results (evidence: `convex/eclipseMatches.ts`)
- Multiplayer rooms → Leaderboard: syncs results (evidence: `convex/eclipseRooms.ts`)
- Solo matches → History recovery: recovers checkpoints
- Session sync → Solo matches: loads saved games
- Input validation → Faction catalog: validates selections (evidence: `convex/eclipseValidators.ts`)
- Player records → Guest identity: links player
