# raghavtandonn/orcs-vs-elves architecture

> Architecture diagram of the GitHub repository raghavtandonn/orcs-vs-elves, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raghavtandonn/orcs-vs-elves
- Repository: https://github.com/raghavtandonn/orcs-vs-elves
- Video tour (about a minute): https://gitdiagram.com/raghavtandonn/orcs-vs-elves/video

## Overview

Orcs vs Elves is a server-authoritative, single-player Roblox bubble-battle game. A player enters through the title screen, aims and launches bouncing bubbles, and the server simulation resolves hits, enemy fire, combos, waves, score, and lives; client rendering and HUD present the run. Score progression, revive/gamepass support, cosmetics and crates, saved data, and period-based leaderboards are distinct supporting capabilities. The README establishes the product structure and capabilities; runtime source excerpts were not provided, so implementation-level links are omitted or marked unverified rather than inferred.

Main entry points: [`src/Client/ArenaRenderer.luau`](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/ArenaRenderer.luau) (Arena Renderer), [`src/Server/ShopService.luau`](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/ShopService.luau) (Shop Service), [`src/Server/ArenaServer.luau`](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/ArenaServer.luau) (Arena Server), [`src/Server/LeaderboardService.luau`](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/LeaderboardService.luau) (Leaderboard Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Experience"]
  node_title["Title Screen<br/>[TitleScreen.luau]"]
  node_aim["Aim Controls<br/>[AimController.luau]"]
  node_arena_view["Arena Renderer<br/>[ArenaRenderer.luau]"]
  node_units["Unit Sprites<br/>[UnitSprite.luau]"]
  node_hud["Game HUD<br/>[Hud.luau]"]
  node_effects["Game Effects<br/>[Effects.luau]"]
  node_shop_ui["Shop Interface<br/>[ShopGui.luau]"]
  node_crate_ui["Crate Opener<br/>[CrateOpener.luau]"]
  node_leaderboard_ui["Leaderboard UI"]
end

subgraph group_server["Server Game Services"]
  node_arena_server["Arena Server<br/>[ArenaServer.luau]"]
  node_save["Save Service<br/>[SaveService.luau]"]
  node_shop["Shop Service<br/>[ShopService.luau]"]
  node_gamepass["Gamepass Service"]
  node_leaderboard["Leaderboard Service"]
end

subgraph group_shared["Shared Game Logic"]
  node_sim["Arena Simulation<br/>[ArenaSim.luau]"]
  node_arena_config["Arena Tuning<br/>[ArenaConfig.luau]"]
  node_net["Network Definitions<br/>[Net.luau]"]
  node_cosmetics["Cosmetics Catalog<br/>[Cosmetics.luau]"]
  node_crates["Crate Catalog<br/>[Crates.luau]"]
end

node_player(("Player"))
node_roblox{{"Roblox Services"}}
node_datastore[("Ordered DataStores")]

node_player -.->|"enters"| node_title
node_player -.->|"aims and launches"| node_aim
node_aim -.->|"sends launch"| node_arena_server
node_arena_server -.->|"resolves gameplay"| node_sim
node_arena_config -.->|"tunes"| node_sim
node_arena_server -.->|"replicates run state"| node_arena_view
node_arena_view -.->|"draws units"| node_units
node_arena_view -.->|"presents impacts"| node_effects
node_arena_view -.->|"presents run status"| node_hud
node_shop_ui -.->|"requests purchases"| node_shop
node_crate_ui -.->|"requests crate actions"| node_shop
node_crates -.->|"defines contents"| node_crate_ui
node_cosmetics -.->|"catalogs items"| node_shop
node_shop -.->|"persists purchases"| node_save
node_leaderboard_ui -.->|"requests rankings"| node_leaderboard
node_leaderboard -.->|"stores rankings"| node_datastore
node_save -.->|"uses persistence"| node_roblox
node_gamepass -.->|"checks entitlement"| node_roblox
node_leaderboard -.->|"uses platform services"| node_roblox

click node_title "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/TitleScreen.luau"
click node_aim "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/AimController.luau"
click node_arena_view "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/ArenaRenderer.luau"
click node_units "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/UnitSprite.luau"
click node_hud "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/Hud.luau"
click node_effects "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/Effects.luau"
click node_shop_ui "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/ShopGui.luau"
click node_crate_ui "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/CrateOpener.luau"
click node_leaderboard_ui "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/LeaderboardGui.luau"
click node_arena_server "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/ArenaServer.luau"
click node_save "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/SaveService.luau"
click node_shop "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/ShopService.luau"
click node_gamepass "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/GamepassService.luau"
click node_leaderboard "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/LeaderboardService.luau"
click node_sim "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Shared/ArenaSim.luau"
click node_arena_config "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Shared/ArenaConfig.luau"
click node_net "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Shared/Net.luau"
click node_cosmetics "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Shared/Cosmetics.luau"
click node_crates "https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Shared/Crates.luau"

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_title,node_aim,node_arena_view,node_units,node_hud,node_effects,node_shop_ui,node_crate_ui,node_leaderboard_ui toneBlue
class node_arena_server,node_save,node_shop,node_gamepass,node_leaderboard,node_datastore toneAmber
class node_sim,node_arena_config,node_net,node_cosmetics,node_crates toneMint
class node_player,node_roblox toneIndigo
```

## Components

### Client Experience

- [Title Screen](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/TitleScreen.luau): `src/Client/TitleScreen.luau`
- [Aim Controls](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/AimController.luau): `src/Client/AimController.luau`
- [Arena Renderer](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/ArenaRenderer.luau): `src/Client/ArenaRenderer.luau`
- [Unit Sprites](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/UnitSprite.luau): `src/Client/UnitSprite.luau`
- [Game HUD](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/Hud.luau): `src/Client/Hud.luau`
- [Game Effects](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/Effects.luau): `src/Client/Effects.luau`
- [Shop Interface](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/ShopGui.luau): `src/Client/ShopGui.luau`
- [Crate Opener](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/CrateOpener.luau): `src/Client/CrateOpener.luau`
- [Leaderboard UI](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Client/LeaderboardGui.luau): `src/Client/LeaderboardGui.luau`

### Server Game Services

- [Arena Server](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/ArenaServer.luau): `src/Server/ArenaServer.luau`
- [Save Service](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/SaveService.luau): `src/Server/SaveService.luau`
- [Shop Service](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/ShopService.luau): `src/Server/ShopService.luau`
- [Gamepass Service](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/GamepassService.luau): `src/Server/GamepassService.luau`
- [Leaderboard Service](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Server/LeaderboardService.luau): `src/Server/LeaderboardService.luau`

### Shared Game Logic

- [Arena Simulation](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Shared/ArenaSim.luau): `src/Shared/ArenaSim.luau`
- [Arena Tuning](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Shared/ArenaConfig.luau): `src/Shared/ArenaConfig.luau`
- [Network Definitions](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Shared/Net.luau): `src/Shared/Net.luau`
- [Cosmetics Catalog](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Shared/Cosmetics.luau): `src/Shared/Cosmetics.luau`
- [Crate Catalog](https://github.com/raghavtandonn/orcs-vs-elves/blob/main/src/Shared/Crates.luau): `src/Shared/Crates.luau`

### Other components

- **Player**
- **Roblox Services**
- **Ordered DataStores**

## Connections

- Player → Title Screen: enters
- Player → Aim Controls: aims and launches
- Aim Controls → Arena Server: sends launch
- Arena Server → Arena Simulation: resolves gameplay
- Arena Tuning → Arena Simulation: tunes
- Arena Server → Arena Renderer: replicates run state
- Arena Renderer → Unit Sprites: draws units
- Arena Renderer → Game Effects: presents impacts
- Arena Renderer → Game HUD: presents run status
- Shop Interface → Shop Service: requests purchases
- Crate Opener → Shop Service: requests crate actions
- Crate Catalog → Crate Opener: defines contents
- Cosmetics Catalog → Shop Service: catalogs items
- Shop Service → Save Service: persists purchases
- Leaderboard UI → Leaderboard Service: requests rankings
- Leaderboard Service → Ordered DataStores: stores rankings
- Save Service → Roblox Services: uses persistence
- Gamepass Service → Roblox Services: checks entitlement
- Leaderboard Service → Roblox Services: uses platform services
