# nicofgr/engine-grafica architecture

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

- Interactive diagram: https://gitdiagram.com/nicofgr/engine-grafica
- Repository: https://github.com/nicofgr/engine-grafica

## Overview

1. **Top-level shape**
   - This repo is a **two-process client/server application** written mostly in C, with a small shared C++ networking layer.
   - The build is split into two executables:
     - `src/server/*` for the headless server
     - `src/client/*` for the interactive client
   - The `src/shared/*` directory holds the contract between them: common constants, types, and networking code.

2. **Server subsystem**
   - `src/server/main.c` is the server entry point.
   - `src/server/server.c/.h` contains the server runtime and likely the authoritative application logic.
   - The server side appears intentionally minimal compared to the client: no rendering code, just state, simulation, and network servicing.

3. **Client subsystem**
   - `src/client/main.c` is the client entry point.
   - `src/client/client.c/.h` is the client runtime and top-level orchestration layer.
   - The client is responsible for connection setup, receiving state from the server, and driving the local render/update loop.

4. **Shared protocol and data model**
   - `src/shared/types.c/.h` and `src/shared/constants.c/.h` define the data model used by both sides.
   - This is the main architectural boundary: anything that must be understood by both client and server is centralized here to keep the network protocol and game/application state consistent.
   - `src/shared/network.cpp/.h` suggests the networking transport abstraction is implemented in C++ and shared by both executables.

5. **Networking layer**
   - The README explicitly calls out **GameNetworkingSockets** as a dependency, so the client/server communication is built on that library rather than raw sockets.
   - The presence of `network.cpp` indicates this layer likely wraps the external transport and exposes a simpler API to the C client/server code.
   - For the architecture diagram, treat this as the transport boundary between the client process and server process.

6. **Rendering pipeline on the client**
   - Rendering is isolated under `src/client/renderer/`.
   - Main renderer components:
     - `renderer.c/.h` — core render loop and graphics setup
     - `shader.c/.h` — shader compilation/program management
     - `mesh.c/.h` — geometry buffers and draw-ready mesh data
     - `model.c/.h` — higher-level model composition
     - `gui.c/.h` — on-screen UI rendering
     - `text.c/.h` — font/text rendering
   - This is a fairly standard layered rendering stack: asset/data preparation at the bottom, scene/model abstraction in the middle, and UI/text overlays at the top.

7. **Graphics and asset dependencies**
   - `include/glad` and `src/client/glad.c` show the project uses **GLAD** for OpenGL function loading.
   - `include/cglm` is vendored, so the client uses **cglm** for matrix/vector math in rendering and camera transforms.
   - `assets/shaders/*` contains GLSL programs for points, simple geometry, text, and post-processing; these are runtime assets loaded by the client renderer.

8. **Text and font path**
   - `src/client/renderer/text.c/.h` plus the FreeType dependency in the README indicate text is rendered via font rasterization rather than bitmap-only UI assets.
   - This is a separate client-side rendering concern from the main scene pipeline, likely used by GUI overlays and debug/status text.

9. **Client platform/runtime boundary**
   - The README lists **SDL2** as a dependency, which strongly suggests the client uses SDL2 for window creation, input, timing, and the OpenGL context.
   - That makes the client a platformed interactive app, while the server remains a non-graphical process.

10. **Asset organization**
   - Runtime shader sources live under `assets/shaders/`.
   - There are no obvious large content pipelines or editor subprojects in the tree, so assets seem lightweight and directly consumed at runtime by the client.

11. **Build and vendored dependencies**
   - `Makefile` is the main repo build entry point.
   - Third-party headers are vendored under `include/`, especially `cglm` and `glad`.
   - This suggests the repo is designed for self-contained compilation, with only a few external system/runtime dependencies: SDL2, FreeType, and GameNetworkingSockets.

12. **Likely architecture diagram boundaries**
   - Best diagram split:
     - **Client process**: SDL2 window/input + OpenGL renderer + GUI/text/model/mesh + local networking client
     - **Network transport**: GameNetworkingSockets wrapper in `src/shared/network.cpp`
     - **Server process**: authoritative runtime and state management
     - **Shared contract**: constants/types used by both sides
     - **External assets**: GLSL shader files
   - The key interaction is server-authoritative state flowing to the client, with the client handling presentation and user interaction.

Main entry points: [`src/client/client.c`](https://github.com/nicofgr/engine-grafica/blob/main/src/client/client.c) (Client core), [`src/client/renderer/renderer.c`](https://github.com/nicofgr/engine-grafica/blob/main/src/client/renderer/renderer.c) (Renderer), [`src/server/server.c`](https://github.com/nicofgr/engine-grafica/blob/main/src/server/server.c) (Server core), [`src/client/renderer/shader.c`](https://github.com/nicofgr/engine-grafica/blob/main/src/client/renderer/shader.c) (Shaders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client process"]
  node_client_main(("Main<br/>entry point<br/>[main.c]"))
  node_client_runtime["Client core<br/>runtime<br/>[client.c]"]
  node_sdl_glue["SDL2 runtime<br/>platform layer"]
  node_net_client["Net client<br/>connection layer<br/>[network.cpp]"]
  node_renderer_core["Renderer<br/>graphics runtime<br/>[renderer.c]"]
  node_shader_system["Shaders<br/>gpu program mgmt<br/>[shader.c]"]
  node_mesh_model["Mesh model<br/>scene data<br/>[mesh.c]"]
  node_gui_text["UI text<br/>overlay rendering<br/>[gui.c]"]
  node_client_main2["Client API<br/>client interface<br/>[client.h]"]
end

subgraph group_server["Server process"]
  node_server_main(("Main<br/>entry point<br/>[main.c]"))
  node_server_runtime["Server core<br/>runtime<br/>[server.c]"]
  node_server_api["Server API<br/>server interface<br/>[server.h]"]
end

subgraph group_shared["Shared contract"]
  node_shared_types["Types<br/>data model<br/>[types.c]"]
  node_shared_consts["Constants<br/>[constants.c]"]
  node_shared_net["Transport<br/>network wrapper<br/>[network.cpp]"]
end

subgraph group_assets["Runtime assets"]
  node_shaders_points["Point shader<br/>glsl asset<br/>[point_shader.vert]"]
  node_shaders_simple["Simple shader<br/>glsl asset<br/>[simple_shader.vert]"]
  node_shaders_text["Text shader<br/>glsl asset<br/>[text.vert]"]
end

subgraph group_deps["Vendored deps"]
  node_client_glad["GLAD<br/>opengl loader<br/>[glad.c]"]
  node_cglm["cglm<br/>math library<br/>[cglm.h]"]
end

node_client_main -->|"starts"| node_client_runtime
node_server_main -->|"starts"| node_server_runtime
node_client_runtime -->|"uses"| node_sdl_glue
node_client_runtime -->|"connects"| node_net_client
node_client_runtime -->|"drives"| node_renderer_core
node_renderer_core -->|"binds"| node_shader_system
node_renderer_core -->|"draws"| node_mesh_model
node_renderer_core -->|"overlays"| node_gui_text
node_renderer_core -->|"loads GL"| node_client_glad
node_renderer_core -->|"math"| node_cglm
node_shader_system -->|"loads"| node_shaders_points
node_shader_system -->|"loads"| node_shaders_simple
node_shader_system -->|"loads"| node_shaders_text
node_server_runtime -->|"exposes"| node_server_api
node_client_runtime -->|"exposes"| node_client_main2
node_client_runtime -->|"reads/writes"| node_shared_types
node_server_runtime -->|"reads/writes"| node_shared_types
node_client_runtime -->|"uses"| node_shared_consts
node_server_runtime -->|"uses"| node_shared_consts
node_client_runtime -->|"uses"| node_shared_net
node_server_runtime -->|"uses"| node_shared_net
node_shared_net -->|"client side"| node_net_client
node_shared_net -->|"server side"| node_server_runtime

click node_client_main "https://github.com/nicofgr/engine-grafica/blob/main/src/client/main.c"
click node_client_runtime "https://github.com/nicofgr/engine-grafica/blob/main/src/client/client.c"
click node_net_client "https://github.com/nicofgr/engine-grafica/blob/main/src/shared/network.cpp"
click node_renderer_core "https://github.com/nicofgr/engine-grafica/blob/main/src/client/renderer/renderer.c"
click node_shader_system "https://github.com/nicofgr/engine-grafica/blob/main/src/client/renderer/shader.c"
click node_mesh_model "https://github.com/nicofgr/engine-grafica/blob/main/src/client/mesh.c"
click node_gui_text "https://github.com/nicofgr/engine-grafica/blob/main/src/client/renderer/gui.c"
click node_client_glad "https://github.com/nicofgr/engine-grafica/blob/main/src/client/glad.c"
click node_client_main2 "https://github.com/nicofgr/engine-grafica/blob/main/src/client/client.h"
click node_server_main "https://github.com/nicofgr/engine-grafica/blob/main/src/server/main.c"
click node_server_runtime "https://github.com/nicofgr/engine-grafica/blob/main/src/server/server.c"
click node_server_api "https://github.com/nicofgr/engine-grafica/blob/main/src/server/server.h"
click node_shared_types "https://github.com/nicofgr/engine-grafica/blob/main/src/shared/types.c"
click node_shared_consts "https://github.com/nicofgr/engine-grafica/blob/main/src/shared/constants.c"
click node_shared_net "https://github.com/nicofgr/engine-grafica/blob/main/src/shared/network.cpp"
click node_shaders_points "https://github.com/nicofgr/engine-grafica/blob/main/assets/shaders/point_shader.vert"
click node_shaders_simple "https://github.com/nicofgr/engine-grafica/blob/main/assets/shaders/simple_shader.vert"
click node_shaders_text "https://github.com/nicofgr/engine-grafica/blob/main/assets/shaders/text.vert"
click node_cglm "https://github.com/nicofgr/engine-grafica/blob/main/include/cglm/cglm.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_client_main,node_client_runtime,node_sdl_glue,node_net_client,node_renderer_core,node_shader_system,node_mesh_model,node_gui_text,node_client_main2 toneBlue
class node_server_main,node_server_runtime,node_server_api toneAmber
class node_shared_types,node_shared_consts,node_shared_net toneMint
class node_shaders_points,node_shaders_simple,node_shaders_text toneRose
class node_client_glad,node_cglm toneIndigo
```

## Components

### Client process

Interactive SDL/OpenGL client that receives server state and renders the local view.

- [Main](https://github.com/nicofgr/engine-grafica/blob/main/src/client/main.c): entry point · Client executable entry point. · `src/client/main.c`
- [Client core](https://github.com/nicofgr/engine-grafica/blob/main/src/client/client.c): runtime · Top-level client orchestration for connection, update, and render flow. · `src/client/client.c`
- **SDL2 runtime**: platform layer · Windowing, input, timing, and OpenGL context boundary implied by the client build.
- [Net client](https://github.com/nicofgr/engine-grafica/blob/main/src/shared/network.cpp): connection layer · Client-side networking path built on the shared transport wrapper. · `src/shared/network.cpp`
- [Renderer](https://github.com/nicofgr/engine-grafica/blob/main/src/client/renderer/renderer.c): graphics runtime · Client render loop and graphics setup. · `src/client/renderer/renderer.c`
- [Shaders](https://github.com/nicofgr/engine-grafica/blob/main/src/client/renderer/shader.c): gpu program mgmt · Shader compilation, linking, and program handling. · `src/client/renderer/shader.c`
- [Mesh model](https://github.com/nicofgr/engine-grafica/blob/main/src/client/mesh.c): scene data · Geometry buffers and higher-level model composition for rendering. · `src/client/mesh.c`
- [UI text](https://github.com/nicofgr/engine-grafica/blob/main/src/client/renderer/gui.c): overlay rendering · On-screen GUI and font/text rendering for overlays and status output. · `src/client/renderer/gui.c`
- [Client API](https://github.com/nicofgr/engine-grafica/blob/main/src/client/client.h): client interface · Client-facing orchestration and state access contract. · `src/client/client.h`

### Server process

Headless authoritative runtime that simulates state and services network traffic.

- [Main](https://github.com/nicofgr/engine-grafica/blob/main/src/server/main.c): entry point · Server executable entry point. · `src/server/main.c`
- [Server core](https://github.com/nicofgr/engine-grafica/blob/main/src/server/server.c): runtime · Authoritative server runtime and application logic. · `src/server/server.c`
- [Server API](https://github.com/nicofgr/engine-grafica/blob/main/src/server/server.h): server interface · Server-facing orchestration and state access contract. · `src/server/server.h`

### Shared contract

Common protocol, types, and transport wrapper used by both executables.

- [Types](https://github.com/nicofgr/engine-grafica/blob/main/src/shared/types.c): data model · Shared data structures for the wire protocol and application state. · `src/shared/types.c`
- [Constants](https://github.com/nicofgr/engine-grafica/blob/main/src/shared/constants.c): protocol constants · Shared constants that keep client and server aligned. · `src/shared/constants.c`
- [Transport](https://github.com/nicofgr/engine-grafica/blob/main/src/shared/network.cpp): network wrapper · C++ wrapper around GameNetworkingSockets used by both processes. · `src/shared/network.cpp`

### Runtime assets

Shader sources loaded by the client renderer at runtime.

- [Point shader](https://github.com/nicofgr/engine-grafica/blob/main/assets/shaders/point_shader.vert): glsl asset · Runtime shader for point rendering. · `assets/shaders/point_shader.vert`
- [Simple shader](https://github.com/nicofgr/engine-grafica/blob/main/assets/shaders/simple_shader.vert): glsl asset · Runtime shader for simple geometry rendering. · `assets/shaders/simple_shader.vert`
- [Text shader](https://github.com/nicofgr/engine-grafica/blob/main/assets/shaders/text.vert): glsl asset · Runtime shader for font/text rendering. · `assets/shaders/text.vert`

### Vendored deps

Third-party headers and loaders bundled in-tree for self-contained builds.

- [GLAD](https://github.com/nicofgr/engine-grafica/blob/main/src/client/glad.c): opengl loader · OpenGL function loading used by the client renderer. · `src/client/glad.c`
- [cglm](https://github.com/nicofgr/engine-grafica/blob/main/include/cglm/cglm.h): math library · Vendored vector/matrix math used by client rendering and transforms. · `include/cglm/cglm.h`

## Connections

- Main → Client core: starts · Client entry initializes the runtime.
- Main → Server core: starts · Server entry initializes the authoritative runtime.
- Client core → SDL2 runtime: uses · Client runtime depends on platform window/input/timing services.
- Client core → Net client: connects · Client runtime communicates with the server through the shared transport.
- Client core → Renderer: drives · Client runtime runs the local presentation loop.
- Renderer → Shaders: binds · Renderer manages GPU programs and shader setup.
- Renderer → Mesh model: draws · Renderer consumes scene geometry and model data.
- Renderer → UI text: overlays · Renderer draws GUI and text on top of the scene.
- Renderer → GLAD: loads GL · Renderer relies on GLAD for OpenGL function access.
- Renderer → cglm: math · Renderer uses cglm for transforms and camera math.
- Shaders → Point shader: loads · Shader system consumes runtime GLSL assets.
- Shaders → Simple shader: loads · Shader system consumes runtime GLSL assets.
- Shaders → Text shader: loads · Shader system consumes runtime GLSL assets.
- Server core → Server API: exposes · Server implementation is organized behind its local interface.
- Client core → Client API: exposes · Client implementation is organized behind its local interface.
- Client core → Types: reads/writes · Client uses shared state definitions for protocol handling.
- Server core → Types: reads/writes · Server uses shared state definitions for protocol handling.
- Client core → Constants: uses · Client relies on shared constants to stay protocol-compatible.
- Server core → Constants: uses · Server relies on shared constants to stay protocol-compatible.
- Client core → Transport: uses · Client uses the shared networking wrapper for transport.
- Server core → Transport: uses · Server uses the shared networking wrapper for transport.
- Transport → Net client: client side · Transport wrapper forms the client connection boundary.
- Transport → Server core: server side · Transport wrapper forms the server communication boundary.
