# guille-ux/tinrux architecture

> Architecture diagram of the GitHub repository guille-ux/tinrux, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guille-ux/tinrux
- Repository: https://github.com/guille-ux/tinrux

## Overview

##### Project type and purpose
- Tinrux is a lightweight, Redis-inspired database written in pure Python.
- It runs as a standalone service with a server–client architecture and exposes a CLI and Python client interface.
- Purpose: simple key–value persistence in JSON, small-scale apps, auto-saving, cookie-based session management.

##### File structure
- Top-level: packaging files (pyproject.toml, README.md, LICENSE.txt), distribution artifacts (dist/), a sample data file (tdb.json), and tests/.
- src/tinrux: four main modules plus metadata:
- cli.py          – command-line interface entry point
- tinruxClient.py – manages socket connection from client side
- tinruxServer.py – core server engine: networking listener, command dispatch, in-memory store
- tinrux_cookies.py – cookie/session management logic
- __init__.py & __about__.py – package initialization and version info
- tests/ holds unit tests covering server and client functionality.

##### Extract additional insights from the README
- Server listens on host:port, supports commands (SET, GET, DEL, EXPIRE, SAVE, HELP).
- Auto-persistence: a timer triggers JSON dumps (tdb.json).
- Zero external dependencies: uses standard library (socket, threading, json).
- Modes: interactive client (CLI), programmatic client, standalone server.

##### Main components and their relationships
a. Client layer
- CLI driver (cli.py)
- Programmatic client API (tinruxClient.py)
→ Establishes TCP socket to the server
b. Server layer
- Network listener & request dispatcher (tinruxServer.py)
- Command interpreter & in-memory key-value store
- Cookie manager (tinrux_cookies.py) for sessions and auth
- Autosave scheduler (background thread)
→ Writes and reads JSON persistence file (tdb.json)
c. Persistence
- JSON file store (tdb.json)
– Handled via Python’s json module
d. Support
- Packaging and distribution (pyproject.toml, dist/)
- Testing framework (tests/)

##### Architectural patterns and design principles
- Client–server over TCP sockets
- Command pattern: each text command maps to a handler method
- Separation of concerns: network I/O vs. in-memory storage vs. persistence vs. session management
- Single-threaded request handling with background thread for auto-saving
- Extensible command set via modular handlers in tinruxServer.py

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        CLI["CLI Interface"]:::user
        ClientAPI["Programmatic Client API"]:::user
    end
    CLI -->|"invokes"| ClientAPI

    %% Network Layer
    ClientAPI -- "TCP Socket" --> Network["TCP Network"]:::network

    %% Server Layer
    subgraph "Server Layer"
        Engine["Server Engine"]:::core
        subgraph "Core Engine"
            Dispatch["Command Dispatcher"]:::core
            Store["In-Memory KV Store"]:::core
            Cookie["Cookie/Session Manager"]:::core
        end
        Scheduler["Autosave Scheduler"]:::core
    end
    Network -->|"incoming request"| Engine
    Engine --> Dispatch
    Engine --> Store
    Engine --> Cookie
    Dispatch --> Store
    Dispatch --> Cookie
    Scheduler -->|"auto-persistence I/O"| Persistence

    %% Persistence Layer
    Persistence["JSON Persistence File (tdb.json)"]:::persistence
    Engine -->|"SAVE command"| Persistence

    %% Support Layer
    subgraph "Support/Test"
        Metadata["Package Metadata & Init"]:::support
        Packaging["Packaging & Distribution"]:::support
        Tests["Test Suite"]:::support
    end
    Tests -->|"imports modules"| CLI
    Tests --> ClientAPI
    Tests --> Engine

    %% Click Events
    click CLI "https://github.com/guille-ux/tinrux/blob/master/src/tinrux/cli.py"
    click ClientAPI "https://github.com/guille-ux/tinrux/blob/master/src/tinrux/tinruxClient.py"
    click Engine "https://github.com/guille-ux/tinrux/blob/master/src/tinrux/tinruxServer.py"
    click Dispatch "https://github.com/guille-ux/tinrux/blob/master/src/tinrux/tinruxServer.py"
    click Store "https://github.com/guille-ux/tinrux/blob/master/src/tinrux/tinruxServer.py"
    click Scheduler "https://github.com/guille-ux/tinrux/blob/master/src/tinrux/tinruxServer.py"
    click Cookie "https://github.com/guille-ux/tinrux/blob/master/src/tinrux/tinrux_cookies.py"
    click Persistence "https://github.com/guille-ux/tinrux/blob/master/tdb.json"
    click Metadata "https://github.com/guille-ux/tinrux/blob/master/src/tinrux/__init__.py"
    click Packaging "https://github.com/guille-ux/tinrux/blob/master/pyproject.toml"
    click Tests "https://github.com/guille-ux/tinrux/tree/master/tests/"

    %% Styles
    classDef user fill:#AEDFF7,stroke:#036,stroke-width:1px
    classDef network fill:#FFD59E,stroke:#873800,stroke-width:1px
    classDef core fill:#C1E1C1,stroke:#2E8B57,stroke-width:1px
    classDef persistence fill:#FFF2A8,stroke:#C9A600,stroke-width:1px
    classDef support fill:#E2E2E2,stroke:#7A7A7A,stroke-width:1px
```
