# kalgoritmi/logger architecture

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

- Interactive diagram: https://gitdiagram.com/kalgoritmi/logger
- Repository: https://github.com/kalgoritmi/logger

## Overview

Binary Logger is a small Python library for writing, reading, and rolling over length-prefixed log files. A caller uses `BinaryLogger`; writes are UTF-8 encoded and synchronized through `LogState`, which manages the active file and sequential backups. Reads enumerate backups and decode records from oldest backup through the current file. The graph reflects the sampled implementation and README; Docker and test infrastructure are excluded because they are not runtime product components.

Main entry points: [`simple_logger.py`](https://github.com/kalgoritmi/logger/blob/main/simple_logger.py) (BinaryLogger API), [`utilities.py`](https://github.com/kalgoritmi/logger/blob/main/utilities.py) (Backup helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

node_caller(("Caller"))
node_logger["BinaryLogger API<br/>[simple_logger.py]"]
node_state["LogState<br/>[simple_logger.py]"]
node_encoder["Record encoder<br/>[simple_logger.py]"]
node_decoder["Record decoder<br/>[simple_logger.py]"]
node_backups["Backup helpers<br/>[utilities.py]"]
node_files[("Log files")]

node_caller -->|"calls API"| node_logger
node_logger -->|"encodes payload"| node_encoder
node_logger -->|"writes under lock"| node_state
node_state -->|"opens, rolls over"| node_files
node_state -->|"gets sequence"| node_backups
node_logger -->|"lists backups"| node_backups
node_logger -->|"reads files"| node_files
node_logger -->|"decodes records"| node_decoder
node_backups -->|"scans directory"| node_files

click node_logger "https://github.com/kalgoritmi/logger/blob/main/simple_logger.py"
click node_state "https://github.com/kalgoritmi/logger/blob/main/simple_logger.py"
click node_encoder "https://github.com/kalgoritmi/logger/blob/main/simple_logger.py"
click node_decoder "https://github.com/kalgoritmi/logger/blob/main/simple_logger.py"
click node_backups "https://github.com/kalgoritmi/logger/blob/main/utilities.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_caller toneIndigo
class node_logger toneMint
class node_state,node_encoder,node_decoder,node_backups toneTeal
class node_files toneAmber
```

## Components

### Other components

- **Caller**
- [BinaryLogger API](https://github.com/kalgoritmi/logger/blob/main/simple_logger.py): `simple_logger.py`
- [LogState](https://github.com/kalgoritmi/logger/blob/main/simple_logger.py): `simple_logger.py`
- [Record encoder](https://github.com/kalgoritmi/logger/blob/main/simple_logger.py): `simple_logger.py`
- [Record decoder](https://github.com/kalgoritmi/logger/blob/main/simple_logger.py): `simple_logger.py`
- [Backup helpers](https://github.com/kalgoritmi/logger/blob/main/utilities.py): `utilities.py`
- **Log files**

## Connections

- Caller → BinaryLogger API: calls API
- BinaryLogger API → Record encoder: encodes payload
- BinaryLogger API → LogState: writes under lock
- LogState → Log files: opens, rolls over
- LogState → Backup helpers: gets sequence
- BinaryLogger API → Backup helpers: lists backups
- BinaryLogger API → Log files: reads files
- BinaryLogger API → Record decoder: decodes records
- Backup helpers → Log files: scans directory