# deepsarda/project-armada architecture

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

- Interactive diagram: https://gitdiagram.com/deepsarda/project-armada
- Repository: https://github.com/deepsarda/project-armada

## Overview

Project Armada is a terminal-based, turn-based multiplayer strategy game. A player uses the TUI to host a match or discover/join one over LAN or a direct IP; the client exchanges lobby, match, turn, and action events with the server, which manages players and authoritative game state. The README describes economic upgrades, repairs, attacks, turn-taking, and victory conditions. Sampled code supports the client event flow, server networking, and gameplay callbacks; some documented features, including LAN discovery and portions of the UI, are represented at their enclosing source paths because their implementations were not fully sampled.

Main entry points: [`src/client/launcher.cpp`](https://github.com/deepsarda/project-armada/blob/main/src/client/launcher.cpp) (Host and Play TUI), [`src/networking/server.c`](https://github.com/deepsarda/project-armada/blob/main/src/networking/server.c) (Lobby and Turn Handling), [`src/networking/client.c`](https://github.com/deepsarda/project-armada/blob/main/src/networking/client.c) (Client Transport), [`include/common/events.h`](https://github.com/deepsarda/project-armada/blob/main/include/common/events.h) (Game Event Protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Terminal Interface"]
  node_entry["Application Entry<br/>[main.cpp]"]
  node_tui["Host and Play TUI<br/>[launcher.cpp]"]
  node_notifications["UI Notifications"]
end

subgraph group_client["Client Session"]
  node_client_api["Client Session API<br/>[client.c]"]
  node_client_state["Client Session State<br/>[client_api.h]"]
  node_client_callbacks["Client UI Callbacks<br/>[launcher.cpp]"]
end

subgraph group_server["Server and Game"]
  node_server_api["Server Lifecycle<br/>[server.c]"]
  node_server_handlers["Lobby and Turn Handling<br/>[server.c]"]
  node_gameplay["Gameplay Rules<br/>[main.c]"]
  node_game_state["Authoritative Game State<br/>[server_api.h]"]
  node_server_callbacks["Server Callbacks<br/>[main.c]"]
  node_server_headers["Server Contracts<br/>[main.h]"]
end

subgraph group_network["Networking and Protocol"]
  node_wire_protocol["Game Event Protocol<br/>[events.h]"]
  node_game_types["Game State Types<br/>[game_types.h]"]
  node_network_api["Socket Operations<br/>[network.c]"]
  node_client_transport["Client Transport<br/>[client.c]"]
  node_platform["Platform Sockets and Threads<br/>[net_platform.h]"]
end

node_player(("Player"))
node_remote_players(("Other Players"))

node_player -->|"launches"| node_entry
node_entry -->|"starts"| node_tui
node_player -->|"uses"| node_tui
node_tui -->|"joins and acts"| node_client_api
node_tui -->|"hosts locally"| node_server_api
node_tui -->|"reads session"| node_client_state
node_client_api -->|"updates"| node_client_state
node_client_api -->|"sends and pumps"| node_client_transport
node_client_transport -->|"uses sockets"| node_network_api
node_network_api -->|"uses"| node_platform
node_client_transport -->|"encodes events"| node_wire_protocol
node_wire_protocol -->|"carries state"| node_game_types
node_client_transport -->|"dispatches events"| node_client_callbacks
node_client_callbacks -->|"updates interface"| node_tui
node_tui -->|"logs activity"| node_notifications
node_server_api -->|"dispatches clients"| node_server_handlers
node_server_handlers -->|"uses sockets"| node_network_api
node_server_handlers -->|"handles events"| node_wire_protocol
node_server_handlers -->|"reads and updates"| node_game_state
node_server_handlers -->|"processes actions"| node_gameplay
node_gameplay -->|"applies game rules"| node_game_state
node_server_handlers -->|"reports lifecycle"| node_server_callbacks
node_server_callbacks -->|"logs activity"| node_notifications
node_server_headers -.->|"declares handlers"| node_server_handlers
node_server_api -->|"accepts connections"| node_remote_players
node_tui -.->|"starts discovery scan"| node_server_api

click node_entry "https://github.com/deepsarda/project-armada/blob/main/src/main.cpp"
click node_tui "https://github.com/deepsarda/project-armada/blob/main/src/client/launcher.cpp"
click node_client_api "https://github.com/deepsarda/project-armada/blob/main/src/networking/client.c"
click node_client_state "https://github.com/deepsarda/project-armada/blob/main/include/client/client_api.h"
click node_client_callbacks "https://github.com/deepsarda/project-armada/blob/main/src/client/launcher.cpp"
click node_notifications "https://github.com/deepsarda/project-armada/blob/main/src/client/ui_notifications.cpp"
click node_server_api "https://github.com/deepsarda/project-armada/blob/main/src/networking/server.c"
click node_server_handlers "https://github.com/deepsarda/project-armada/blob/main/src/networking/server.c"
click node_gameplay "https://github.com/deepsarda/project-armada/blob/main/src/server/main.c"
click node_game_state "https://github.com/deepsarda/project-armada/blob/main/include/server/server_api.h"
click node_server_callbacks "https://github.com/deepsarda/project-armada/blob/main/src/server/main.c"
click node_server_headers "https://github.com/deepsarda/project-armada/blob/main/include/server/main.h"
click node_wire_protocol "https://github.com/deepsarda/project-armada/blob/main/include/common/events.h"
click node_game_types "https://github.com/deepsarda/project-armada/blob/main/include/common/game_types.h"
click node_network_api "https://github.com/deepsarda/project-armada/blob/main/src/networking/network.c"
click node_client_transport "https://github.com/deepsarda/project-armada/blob/main/src/networking/client.c"
click node_platform "https://github.com/deepsarda/project-armada/blob/main/include/networking/net_platform.h"

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_entry,node_tui,node_notifications toneBlue
class node_client_api,node_client_state,node_client_callbacks toneAmber
class node_server_api,node_server_handlers,node_gameplay,node_game_state,node_server_callbacks,node_server_headers toneMint
class node_wire_protocol,node_game_types,node_network_api,node_client_transport,node_platform toneRose
class node_player,node_remote_players toneIndigo
```

## Components

### Terminal Interface

- [Application Entry](https://github.com/deepsarda/project-armada/blob/main/src/main.cpp): `src/main.cpp`
- [Host and Play TUI](https://github.com/deepsarda/project-armada/blob/main/src/client/launcher.cpp): `src/client/launcher.cpp`
- [UI Notifications](https://github.com/deepsarda/project-armada/blob/main/src/client/ui_notifications.cpp): `src/client/ui_notifications.cpp`

### Client Session

- [Client Session API](https://github.com/deepsarda/project-armada/blob/main/src/networking/client.c): `src/networking/client.c`
- [Client Session State](https://github.com/deepsarda/project-armada/blob/main/include/client/client_api.h): `include/client/client_api.h`
- [Client UI Callbacks](https://github.com/deepsarda/project-armada/blob/main/src/client/launcher.cpp): `src/client/launcher.cpp`

### Server and Game

- [Server Lifecycle](https://github.com/deepsarda/project-armada/blob/main/src/networking/server.c): `src/networking/server.c`
- [Lobby and Turn Handling](https://github.com/deepsarda/project-armada/blob/main/src/networking/server.c): `src/networking/server.c`
- [Gameplay Rules](https://github.com/deepsarda/project-armada/blob/main/src/server/main.c): `src/server/main.c`
- [Authoritative Game State](https://github.com/deepsarda/project-armada/blob/main/include/server/server_api.h): `include/server/server_api.h`
- [Server Callbacks](https://github.com/deepsarda/project-armada/blob/main/src/server/main.c): `src/server/main.c`
- [Server Contracts](https://github.com/deepsarda/project-armada/blob/main/include/server/main.h): `include/server/main.h`

### Networking and Protocol

- [Game Event Protocol](https://github.com/deepsarda/project-armada/blob/main/include/common/events.h): `include/common/events.h`
- [Game State Types](https://github.com/deepsarda/project-armada/blob/main/include/common/game_types.h): `include/common/game_types.h`
- [Socket Operations](https://github.com/deepsarda/project-armada/blob/main/src/networking/network.c): `src/networking/network.c`
- [Client Transport](https://github.com/deepsarda/project-armada/blob/main/src/networking/client.c): `src/networking/client.c`
- [Platform Sockets and Threads](https://github.com/deepsarda/project-armada/blob/main/include/networking/net_platform.h): `include/networking/net_platform.h`

### Other components

- **Player**
- **Other Players**

## Connections

- Player → Application Entry: launches
- Application Entry → Host and Play TUI: starts
- Player → Host and Play TUI: uses
- Host and Play TUI → Client Session API: joins and acts
- Host and Play TUI → Server Lifecycle: hosts locally
- Host and Play TUI → Client Session State: reads session
- Client Session API → Client Session State: updates
- Client Session API → Client Transport: sends and pumps
- Client Transport → Socket Operations: uses sockets
- Socket Operations → Platform Sockets and Threads: uses
- Client Transport → Game Event Protocol: encodes events
- Game Event Protocol → Game State Types: carries state
- Client Transport → Client UI Callbacks: dispatches events
- Client UI Callbacks → Host and Play TUI: updates interface
- Host and Play TUI → UI Notifications: logs activity
- Server Lifecycle → Lobby and Turn Handling: dispatches clients
- Lobby and Turn Handling → Socket Operations: uses sockets
- Lobby and Turn Handling → Game Event Protocol: handles events
- Lobby and Turn Handling → Authoritative Game State: reads and updates
- Lobby and Turn Handling → Gameplay Rules: processes actions
- Gameplay Rules → Authoritative Game State: applies game rules
- Lobby and Turn Handling → Server Callbacks: reports lifecycle
- Server Callbacks → UI Notifications: logs activity
- Server Contracts → Lobby and Turn Handling: declares handlers
- Server Lifecycle → Other Players: accepts connections
- Host and Play TUI → Server Lifecycle: starts discovery scan