# les-s-nik/polonium architecture

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

- Interactive diagram: https://gitdiagram.com/les-s-nik/polonium
- Repository: https://github.com/les-s-nik/polonium

## Overview

Polonium is a studying-oriented C++ HTTP/JSON API framework. Its main workflow accepts TCP connections, parses HTTP requests, dispatches by method and URI to registered router handlers, and serializes API responses back to clients. Routing also supports URI-template parameters; JSON helpers and configurable logging, sockets, and worker threads provide supporting capabilities. Relationships are limited to those shown in the README, excerpts, and SOURCE INDEX; several implementation details are unsampled.

Main entry points: [`src/sockets/connection_handler.cpp`](https://github.com/les-s-nik/polonium/blob/master/src/sockets/connection_handler.cpp) (Connection Handler), [`src/app/polonium.cpp`](https://github.com/les-s-nik/polonium/blob/master/src/app/polonium.cpp) (Polonium App), [`src/routing/uri_parser.cpp`](https://github.com/les-s-nik/polonium/blob/master/src/routing/uri_parser.cpp) (URI Templates), [`src/routing/dispatcher.cpp`](https://github.com/les-s-nik/polonium/blob/master/src/routing/dispatcher.cpp) (Route Dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server Runtime"]
  node_app["Polonium App<br/>[polonium.cpp]"]
  node_connection["Connection Handler"]
  node_socket["TCP Socket<br/>[tcp_socket.cpp]"]
  node_pool["Thread Pool<br/>[thread_pool.cpp]"]
end

subgraph group_http["HTTP and JSON"]
  node_parser["HTTP Request Parser<br/>[request_parser.cpp]"]
  node_httpactions["HTTP Actions<br/>[http_actions.cpp]"]
  node_serializer["Response Serializer"]
  node_json["JSON Helpers<br/>[json_parser.cpp]"]
end

subgraph group_routing["Routing"]
  node_dispatcher["Route Dispatcher<br/>[dispatcher.cpp]"]
  node_router["Router API"]
  node_uri["URI Templates<br/>[uri_parser.cpp]"]
  node_paramparser["Parameter Parser<br/>[params_parser.cpp]"]
  node_uriparams["URI Parameters<br/>[uri_params.cpp]"]
  node_apiresponse["API Responses<br/>[api_responses.cpp]"]
  node_example["Users Router<br/>[users_router.cpp]"]
end

subgraph group_support["Configuration and Support"]
  node_config["App Settings"]
  node_logger["Logger"]
end

node_client(("API Client"))

node_client -->|"sends requests"| node_connection
node_app -->|"includes router"| node_router
node_app -->|"starts server"| node_connection
node_connection -->|"accepts and transfers"| node_socket
node_connection -->|"queues connections"| node_pool
node_connection -->|"feeds request bytes"| node_parser
node_connection -->|"checks route"| node_dispatcher
node_connection -->|"invokes handler"| node_apiresponse
node_connection -->|"builds HTTP response"| node_httpactions
node_connection -->|"serializes response"| node_serializer
node_parser -->|"fills request"| node_httpactions
node_dispatcher -->|"matches templates"| node_uri
node_router -->|"registers routes"| node_dispatcher
node_uri -->|"parses parameters"| node_paramparser
node_uri -->|"builds parameter values"| node_uriparams
node_example -->|"defines routes"| node_router
node_apiresponse -->|"serializes JSON content"| node_json
node_app -->|"uses settings"| node_config

click node_app "https://github.com/les-s-nik/polonium/blob/master/src/app/polonium.cpp"
click node_connection "https://github.com/les-s-nik/polonium/blob/master/src/sockets/connection_handler.cpp"
click node_socket "https://github.com/les-s-nik/polonium/blob/master/src/sockets/tcp_socket.cpp"
click node_pool "https://github.com/les-s-nik/polonium/blob/master/src/thread_pool.cpp"
click node_parser "https://github.com/les-s-nik/polonium/blob/master/src/http/request_parser.cpp"
click node_httpactions "https://github.com/les-s-nik/polonium/blob/master/src/http/http_actions.cpp"
click node_serializer "https://github.com/les-s-nik/polonium/blob/master/src/http/response_serializer.cpp"
click node_json "https://github.com/les-s-nik/polonium/blob/master/src/json_parser.cpp"
click node_dispatcher "https://github.com/les-s-nik/polonium/blob/master/src/routing/dispatcher.cpp"
click node_router "https://github.com/les-s-nik/polonium/blob/master/src/routing/polonium_router.cpp"
click node_uri "https://github.com/les-s-nik/polonium/blob/master/src/routing/uri_parser.cpp"
click node_paramparser "https://github.com/les-s-nik/polonium/blob/master/src/routing/params_parser.cpp"
click node_uriparams "https://github.com/les-s-nik/polonium/blob/master/src/routing/uri_params.cpp"
click node_apiresponse "https://github.com/les-s-nik/polonium/blob/master/src/routing/api_responses.cpp"
click node_example "https://github.com/les-s-nik/polonium/blob/master/examples/users_example/src/users_router.cpp"
click node_config "https://github.com/les-s-nik/polonium/blob/master/src/app/polonium_config.cpp"
click node_logger "https://github.com/les-s-nik/polonium/blob/master/src/app/polonium_logger.cpp"

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_app,node_connection,node_socket,node_pool,node_client toneBlue
class node_parser,node_httpactions,node_serializer,node_json toneAmber
class node_dispatcher,node_router,node_uri,node_paramparser,node_uriparams,node_apiresponse,node_example toneMint
class node_config,node_logger toneRose
```

## Components

### Server Runtime

- [Polonium App](https://github.com/les-s-nik/polonium/blob/master/src/app/polonium.cpp): `src/app/polonium.cpp`
- [Connection Handler](https://github.com/les-s-nik/polonium/blob/master/src/sockets/connection_handler.cpp): `src/sockets/connection_handler.cpp`
- [TCP Socket](https://github.com/les-s-nik/polonium/blob/master/src/sockets/tcp_socket.cpp): `src/sockets/tcp_socket.cpp`
- [Thread Pool](https://github.com/les-s-nik/polonium/blob/master/src/thread_pool.cpp): `src/thread_pool.cpp`

### HTTP and JSON

- [HTTP Request Parser](https://github.com/les-s-nik/polonium/blob/master/src/http/request_parser.cpp): `src/http/request_parser.cpp`
- [HTTP Actions](https://github.com/les-s-nik/polonium/blob/master/src/http/http_actions.cpp): `src/http/http_actions.cpp`
- [Response Serializer](https://github.com/les-s-nik/polonium/blob/master/src/http/response_serializer.cpp): `src/http/response_serializer.cpp`
- [JSON Helpers](https://github.com/les-s-nik/polonium/blob/master/src/json_parser.cpp): `src/json_parser.cpp`

### Routing

- [Route Dispatcher](https://github.com/les-s-nik/polonium/blob/master/src/routing/dispatcher.cpp): `src/routing/dispatcher.cpp`
- [Router API](https://github.com/les-s-nik/polonium/blob/master/src/routing/polonium_router.cpp): `src/routing/polonium_router.cpp`
- [URI Templates](https://github.com/les-s-nik/polonium/blob/master/src/routing/uri_parser.cpp): `src/routing/uri_parser.cpp`
- [Parameter Parser](https://github.com/les-s-nik/polonium/blob/master/src/routing/params_parser.cpp): `src/routing/params_parser.cpp`
- [URI Parameters](https://github.com/les-s-nik/polonium/blob/master/src/routing/uri_params.cpp): `src/routing/uri_params.cpp`
- [API Responses](https://github.com/les-s-nik/polonium/blob/master/src/routing/api_responses.cpp): `src/routing/api_responses.cpp`
- [Users Router](https://github.com/les-s-nik/polonium/blob/master/examples/users_example/src/users_router.cpp): `examples/users_example/src/users_router.cpp`

### Configuration and Support

- [App Settings](https://github.com/les-s-nik/polonium/blob/master/src/app/polonium_config.cpp): `src/app/polonium_config.cpp`
- [Logger](https://github.com/les-s-nik/polonium/blob/master/src/app/polonium_logger.cpp): `src/app/polonium_logger.cpp`

### Other components

- **API Client**

## Connections

- API Client → Connection Handler: sends requests (evidence: `README.md`)
- Polonium App → Router API: includes router (evidence: `README.md`)
- Polonium App → Connection Handler: starts server (evidence: `README.md`)
- Connection Handler → TCP Socket: accepts and transfers (evidence: `src/sockets/connection_handler.cpp`)
- Connection Handler → Thread Pool: queues connections (evidence: `src/sockets/connection_handler.cpp`)
- Connection Handler → HTTP Request Parser: feeds request bytes (evidence: `src/sockets/connection_handler.cpp`)
- Connection Handler → Route Dispatcher: checks route (evidence: `src/sockets/connection_handler.cpp`)
- Connection Handler → API Responses: invokes handler (evidence: `src/sockets/connection_handler.cpp`)
- Connection Handler → HTTP Actions: builds HTTP response (evidence: `src/sockets/connection_handler.cpp`)
- Connection Handler → Response Serializer: serializes response (evidence: `src/sockets/connection_handler.cpp`)
- HTTP Request Parser → HTTP Actions: fills request
- Route Dispatcher → URI Templates: matches templates (evidence: `src/routing/dispatcher.cpp`)
- Router API → Route Dispatcher: registers routes (evidence: `src/routing/polonium_router.cpp`)
- URI Templates → Parameter Parser: parses parameters (evidence: `src/routing/uri_parser.cpp`)
- URI Templates → URI Parameters: builds parameter values (evidence: `src/routing/uri_parser.cpp`)
- Users Router → Router API: defines routes (evidence: `README.md`)
- API Responses → JSON Helpers: serializes JSON content (evidence: `src/routing/api_responses.cpp`)
- Polonium App → App Settings: uses settings (evidence: `README.md`)