# alejandrotejero/tacticalbattle architecture

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

- Interactive diagram: https://gitdiagram.com/alejandrotejero/tacticalbattle
- Repository: https://github.com/alejandrotejero/tacticalbattle

## Overview

#### Purpose and execution model
Tactical Battle is a Python 3 terminal-based, two-player tactical combat game using TCP client/server networking. The server owns connection lifecycle, lobby pairing, concurrent match capacity, and ranking persistence; each client owns its local board UI and unit state. Launch points are `Game/servidor.py` and `Game/cliente.py`.

#### Server: connection, lobby, and match orchestration
`Game/servidor.py` accepts a port, simultaneous-match limit, and ranking file path. It accepts client connections, collects player identities, places waiting players into a lobby, pairs them, selects the starting player, and manages multiple active games up to the configured capacity. The server is the control-plane boundary between independent client processes.
Paths: `Game/servidor.py`, `Game/jugador.py`, `Game/ranking_simple.txt`.

#### Client: terminal interaction and local game loop
`Game/cliente.py` is the interactive endpoint. It gathers player input, drives deployment and turn actions, renders or manages the player’s local 4x4 board, and exchanges game events with the server/opponent through the network protocol. Movement is processed locally; combat, intelligence, and other cross-player effects are communicated so the affected side applies them to its own board.
Paths: `Game/cliente.py`, `Game/personajes.py`, `Game/utils.py`.

#### Game domain: players, board units, and victory
Player/session state is modeled in `Game/jugador.py`; unit roles and their combat behavior are defined in `Game/personajes.py`. The domain includes Francotirador, Artillero, Inteligencia, and Médico, with movement, abilities, damage/healing, visibility effects, and cooldowns. Victory depends on eliminating the opposing military units (Artillero and Francotirador), rather than every support unit.
Paths: `Game/jugador.py`, `Game/personajes.py`.

#### Network protocol boundary
`Game/protocol.py` defines the custom TCP message framing layer, using message size framing to preserve application-message boundaries over a byte stream. Both `Game/cliente.py` and `Game/servidor.py` should communicate through this module rather than directly coupling game logic to raw socket reads/writes.
Paths: `Game/protocol.py`, `Game/cliente.py`, `Game/servidor.py`.

#### Core data structures and state handling
The project implements its own queue and doubly linked list, likely supporting lobby, player, turn, or collection management instead of relying exclusively on standard-library containers. These structures are internal implementation boundaries beneath the server and gameplay orchestration layers.
Paths: `Game/queue.py`, `Game/doubly_linked_list.py`, `Game/servidor.py`.

#### Persistence and external dependencies
There are no third-party dependencies or web infrastructure. Runtime requirements are Python 3, terminal I/O, local/network TCP sockets, and filesystem access. Ranking is persisted as plain text: after a game, clients submit statistics and the server calculates and writes score updates to the configured ranking file.
Paths: `Game/servidor.py`, `Game/ranking_simple.txt`, `Game/protocol.py`.

Main entry points: [`Game/cliente.py`](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/cliente.py) (Terminal client), [`Game/servidor.py`](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/servidor.py) (Server), [`Game/jugador.py`](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/jugador.py) (Player state), [`Game/protocol.py`](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/protocol.py) (TCP framing protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server runtime"]
  node_server_entry["Server<br/>Python entry point<br/>[servidor.py]"]
  node_lobby_matches["Lobby &amp; match manager<br/>server orchestration<br/>[servidor.py]"]
  node_ranking["Ranking persistence<br/>plain-text ranking<br/>[ranking_simple.txt]"]
  node_queue["Custom queue<br/>data structure<br/>[queue.py]"]
end

subgraph group_client["Client runtime"]
  node_client_entry["Terminal client<br/>Python entry point<br/>[cliente.py]"]
  node_local_board["Local 4x4 board<br/>client game state<br/>[cliente.py]"]
  node_utils["Game utilities<br/>shared utility module<br/>[utils.py]"]
end

subgraph group_domain["Game domain"]
  node_player_state["Player state<br/>session model<br/>[jugador.py]"]
  node_units["Combat units<br/>unit roles<br/>[personajes.py]"]
  node_victory["Victory rules<br/>game rule<br/>[personajes.py]"]
  node_linked_list["Doubly linked list<br/>data structure"]
end

node_protocol{{"TCP framing protocol<br/>network protocol<br/>[protocol.py]"}}
node_tcp(("TCP sockets<br/>runtime transport"))

node_server_entry -->|"manages"| node_lobby_matches
node_lobby_matches -->|"uses"| node_queue
node_server_entry -->|"updates scores"| node_ranking
node_server_entry -->|"uses"| node_protocol
node_client_entry -->|"uses"| node_protocol
node_protocol -->|"frames messages over"| node_tcp
node_tcp -->|"connections"| node_server_entry
node_tcp -->|"connections"| node_client_entry
node_lobby_matches -->|"creates sessions"| node_player_state
node_client_entry -->|"drives"| node_local_board
node_client_entry -->|"tracks player"| node_player_state
node_local_board -->|"places and updates"| node_units
node_units -->|"determines"| node_victory
node_client_entry -->|"uses"| node_utils
node_player_state -.->|"uses collections"| node_linked_list
node_client_entry -.->|"game events and statistics"| node_server_entry

click node_server_entry "https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/servidor.py"
click node_lobby_matches "https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/servidor.py"
click node_ranking "https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/ranking_simple.txt"
click node_client_entry "https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/cliente.py"
click node_local_board "https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/cliente.py"
click node_player_state "https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/jugador.py"
click node_units "https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/personajes.py"
click node_victory "https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/personajes.py"
click node_protocol "https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/protocol.py"
click node_queue "https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/queue.py"
click node_linked_list "https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/doubly_linked_list.py"
click node_utils "https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/utils.py"

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_server_entry,node_lobby_matches,node_ranking,node_queue toneBlue
class node_client_entry,node_local_board,node_utils toneAmber
class node_player_state,node_units,node_victory,node_linked_list toneMint
class node_protocol,node_tcp toneNeutral
```

## Components

### Server runtime

Owns connections, pairing, matches, and rankings.

- [Server](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/servidor.py): Python entry point · Accepts connections and orchestrates concurrent matches. · `Game/servidor.py`
- [Lobby & match manager](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/servidor.py): server orchestration · Pairs waiting players, selects starters, and enforces match capacity. · `Game/servidor.py`
- [Ranking persistence](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/ranking_simple.txt): plain-text ranking · Stores server-calculated post-game scores. · `Game/ranking_simple.txt`
- [Custom queue](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/queue.py): data structure · Supports server-side waiting or game collections. · `Game/queue.py`

### Client runtime

Each player runs a local terminal game client.

- [Terminal client](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/cliente.py): Python entry point · Runs deployment, turns, input, and local board interaction. · `Game/cliente.py`
- [Local 4x4 board](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/cliente.py): client game state · Each client owns and updates its own board state. · `Game/cliente.py`
- [Game utilities](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/utils.py): shared utility module · `Game/utils.py`

### Game domain

- [Player state](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/jugador.py): session model · `Game/jugador.py`
- [Combat units](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/personajes.py): unit roles · Francotirador, Artillero, Inteligencia, and Médico behaviors. · `Game/personajes.py`
- [Victory rules](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/personajes.py): game rule · Victory requires eliminating Artillero and Francotirador. · `Game/personajes.py`
- [Doubly linked list](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/doubly_linked_list.py): data structure · Internal collection structure for orchestration or gameplay state. · `Game/doubly_linked_list.py`

### Other components

- [TCP framing protocol](https://github.com/alejandrotejero/tacticalbattle/blob/main/Game/protocol.py): network protocol · Preserves application-message boundaries over TCP streams. · `Game/protocol.py`
- **TCP sockets**: runtime transport

## Connections

- Server → Lobby & match manager: manages
- Lobby & match manager → Custom queue: uses
- Server → Ranking persistence: updates scores
- Server → TCP framing protocol: uses
- Terminal client → TCP framing protocol: uses
- TCP framing protocol → TCP sockets: frames messages over
- TCP sockets → Server: connections
- TCP sockets → Terminal client: connections
- Lobby & match manager → Player state: creates sessions
- Terminal client → Local 4x4 board: drives
- Terminal client → Player state: tracks player
- Local 4x4 board → Combat units: places and updates
- Combat units → Victory rules: determines
- Terminal client → Game utilities: uses
- Player state → Doubly linked list: uses collections
- Terminal client → Server: game events and statistics