# tfpf/pysorteddict architecture

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

- Interactive diagram: https://gitdiagram.com/tfpf/pysorteddict
- Repository: https://github.com/tfpf/pysorteddict

## Overview

##### Project type and purpose
- This is an open-source Python library (a CPython extension module) named **pysorteddict**.
- Its sole responsibility is to provide a `SortedDict` type—i.e. a dict whose keys are always in ascending order—implemented in C++ for performance and exposed to Python.

##### File structure
- **src/pysorteddict/**
- C++ source files (`*.cc`) and headers (`*.hh`) implementing:
– Core `SortedDict` type (`sorted_dict_type.*`)
– Key, value, item “view” types (`sorted_dict_keys_type.*`, `sorted_dict_values_type.*`, `sorted_dict_items_type.*`)
– Module initialization (`sorted_dict_module.cc`)
– Utility routines (`sorted_dict_utils.hh`)
- **setup.py** & **pyproject.toml**
- Packaging metadata, build requirements, C++ compile flags
- **tests/**
- Functional tests (`tests/functional`)
- Performance benchmark notebooks (`tests/performance`)
- **docs/**
- Sphinx documentation sources, templates, static assets
- **.github/workflows/**
- CI pipeline (build, test, coverage) and docs deployment (GitHub Pages)
- **examples/**
- Simple usage demo in pure Python

##### Key insights from README
- Purpose: enrich CPython with a faster, sorted‐key dictionary
- Delivery: published on PyPI, docs on GitHub Pages
- CI/CD: GitHub Actions ensures build, test, docs publication

##### Main components
a. **User Application Layer**
- Your Python code or REPL import and use `pysorteddict.SortedDict`.
b. **Python Interpreter**
- Loads the compiled extension module (`.so` or `.pyd`).
c. **C++ Extension Module**
- `sorted_dict_module` glue code
- Core C++ types & algorithms for sorted dict, keys, values, items
d. **Build & Packaging Layer**
- `setup.py` / Hatch config (`pyproject.toml`)
- Compiler toolchain (e.g., g++, clang)
- Linting/formatting via `.clang-format`, CI workflows
e. **Testing & Benchmarking**
- Functional tests (pytest)
- Performance notebooks (Jupyter)
f. **Documentation**
- Sphinx sources → HTML output → deployed via GitHub Pages
g. **CI/CD and Distribution**
- GitHub Actions:
- `ci.yml`: build, test, coverage
- `pages.yml`: docs build and deployment
- PyPI: final wheel/sdist distribution

##### Relationships and interactions
- Developer pushes code → GitHub Actions CI runs:
- Build & compile C++ into Python extension → run tests → measure coverage
- On docs changes: build Sphinx site → deploy to GitHub Pages
- Successful CI artifacts → package published to PyPI
- End users install via `pip install pysorteddict` → Python import → runtime calls into C++ core.

##### Architectural patterns & principles
- **Separation of concerns**:
- C++ layer for performance-critical algorithms
- Python wrapper for API and packaging
- Dedicated docs and tests directories
- **Extensibility**: C++ utility headers facilitate adding new view types
- **CI/CD**: clear pipeline for code quality (lint, format), testing, documentation, and release

##### Detailed component labeling
- Call out key config files (e.g., `setup.py`, `pyproject.toml`, `.clang-format`) near the build pipeline

##### Final advice
- **accuracy**: capture every major directory & its role
- Keep it **readable**: group related items (source vs. tests vs. docs)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Code Components
    subgraph "Source Code" 
        direction TB
        CCore["C++ Extension Core\n(sorted_dict_type)"]:::code
        CViewKeys["C++ View Types\n(keys_type)"]:::code
        CViewValues["C++ View Types\n(values_type)"]:::code
        CViewItems["C++ View Types\n(items_type)"]:::code
        CViewGeneral["C++ View Types\n(view_type)"]:::code
        CModuleGlue["Module Initialization\n(sorted_dict_module)"]:::code
        CUtils["Utility Routines\n(sorted_dict_utils)"]:::code
    end

    %% Build & Packaging Layer
    subgraph "Build & Packaging" 
        direction TB
        Setup["setup.py"]:::build
        PyProj["pyproject.toml"]:::build
        Manifest["MANIFEST.in"]:::build
        ClangFmt[".clang-format\nclang-format.bash"]:::build
    end

    %% Testing & Benchmarking
    subgraph "Testing & Benchmarking" 
        direction TB
        TestsFunc["Functional Tests\n(tests/functional)"]:::test
        TestsPerf["Performance Notebooks\n(tests/performance)"]:::test
    end

    %% Documentation
    subgraph "Documentation" 
        direction TB
        DocsSrc["Sphinx Sources\n(docs/)"]:::build
    end

    %% CI/CD & Distribution
    subgraph "CI/CD & Distribution"
        direction TB
        GitHub["GitHub Repo"]:::external
        CI["GitHub Actions CI\n(ci.yml)"]:::build
        PagesCI["Docs Workflow\n(pages.yml)"]:::build
        PyPI["PyPI"]:::external
        GHPages["GitHub Pages"]:::external
    end

    %% Examples
    Examples["Example Usage\n(examples/basic.py)"]:::code

    %% Runtime
    subgraph "Runtime Flow"
        direction TB
        UserApp["User Application\n(python code)"]:::code
        PyInterp["Python Interpreter"]:::code
        ExtMod["pysorteddict Extension\n(.so/.pyd)"]:::code
    end

    %% External Endpoints
    %% Already in CI/CD & Distribution

    %% Connections
    %% Build flow
    Setup -->|defines metadata| BuildTool[(Compiler Toolchain)]:::build
    PyProj --> BuildTool
    Manifest --> BuildTool
    ClangFmt --> CI
    BuildTool -->|compiles| CCore
    BuildTool --> CViewKeys
    BuildTool --> CViewValues
    BuildTool --> CViewItems
    BuildTool --> CViewGeneral
    BuildTool --> CModuleGlue
    BuildTool --> CUtils
    BuildTool --> ExtMod

    %% Testing flow
    CI -->|runs pytest| TestsFunc
    CI -->|runs notebooks| TestsPerf

    %% Documentation flow
    PagesCI -->|builds Sphinx| DocsSrc
    PagesCI -->|deploy| GHPages

    %% CI triggers
    GitHub --> CI
    GitHub --> PagesCI
    CI -->|on success| PyPI

    %% Runtime flow arrows
    UserApp -->|import pysorteddict| PyInterp
    PyInterp -->|loads| ExtMod
    ExtMod -->|calls| CModuleGlue
    CModuleGlue --> CCore
    CCore --> CViewKeys
    CCore --> CViewValues
    CCore --> CViewItems
    CCore --> CViewGeneral
    CCore --> CUtils

    %% Distribution
    PyPI -->|pip install pysorteddict| UserApp

    %% Examples link
    UserApp --> Examples

    %% Click events
    click CCore "https://github.com/tfpf/pysorteddict/blob/main/src/pysorteddict/sorted_dict_type.cc"
    click CCore "https://github.com/tfpf/pysorteddict/blob/main/src/pysorteddict/sorted_dict_type.hh"
    click CViewKeys "https://github.com/tfpf/pysorteddict/blob/main/src/pysorteddict/sorted_dict_keys_type.cc"
    click CViewKeys "https://github.com/tfpf/pysorteddict/blob/main/src/pysorteddict/sorted_dict_keys_type.hh"
    click CViewValues "https://github.com/tfpf/pysorteddict/blob/main/src/pysorteddict/sorted_dict_values_type.cc"
    click CViewValues "https://github.com/tfpf/pysorteddict/blob/main/src/pysorteddict/sorted_dict_values_type.hh"
    click CViewItems "https://github.com/tfpf/pysorteddict/blob/main/src/pysorteddict/sorted_dict_items_type.cc"
    click CViewItems "https://github.com/tfpf/pysorteddict/blob/main/src/pysorteddict/sorted_dict_items_type.hh"
    click CViewGeneral "https://github.com/tfpf/pysorteddict/blob/main/src/pysorteddict/sorted_dict_view_type.cc"
    click CViewGeneral "https://github.com/tfpf/pysorteddict/blob/main/src/pysorteddict/sorted_dict_view_type.hh"
    click CModuleGlue "https://github.com/tfpf/pysorteddict/blob/main/src/pysorteddict/sorted_dict_module.cc"
    click CUtils "https://github.com/tfpf/pysorteddict/blob/main/src/pysorteddict/sorted_dict_utils.hh"
    click Setup "https://github.com/tfpf/pysorteddict/blob/main/setup.py"
    click PyProj "https://github.com/tfpf/pysorteddict/blob/main/pyproject.toml"
    click Manifest "https://github.com/tfpf/pysorteddict/blob/main/MANIFEST.in"
    click ClangFmt "https://github.com/tfpf/pysorteddict/blob/main/.clang-format"
    click ClangFmt "https://github.com/tfpf/pysorteddict/blob/main/clang-format.bash"
    click CI "https://github.com/tfpf/pysorteddict/blob/main/.github/workflows/ci.yml"
    click PagesCI "https://github.com/tfpf/pysorteddict/blob/main/.github/workflows/pages.yml"
    click TestsFunc "https://github.com/tfpf/pysorteddict/tree/main/tests/functional"
    click TestsPerf "https://github.com/tfpf/pysorteddict/tree/main/tests/performance"
    click DocsSrc "https://github.com/tfpf/pysorteddict/blob/main/docs/conf.py"
    click Examples "https://github.com/tfpf/pysorteddict/blob/main/examples/basic.py"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#004080,color:#004080
    classDef build fill:#E0FFE0,stroke:#008000,color:#006400
    classDef test fill:#FFE8D0,stroke:#FF8000,color:#FF4000
    classDef external fill:#F2E0FF,stroke:#800080,color:#660066
```
