# hasnard/pdefa architecture

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

- Interactive diagram: https://gitdiagram.com/hasnard/pdefa
- Repository: https://github.com/hasnard/pdefa

## Overview

pdefa is a CPU inference engine exposed to Python through ctypes, with image loading and preprocessing plus YOLO-oriented postprocessing. Its main workflow prepares an image tensor, loads an engine model, runs a session, and decodes model output. The tree supports the native engine and image pipeline; the README also mentions an ONNX-to-engine converter, but no converter source path appears in the supplied tree, so it is not mapped here.

Main entry points: [`pdefa/python/src/pdefa/_bindings.py`](https://github.com/hasnard/pdefa/blob/main/pdefa/python/src/pdefa/_bindings.py) (ctypes bindings), [`PDEFA1.0/src/core/session.cpp`](https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/core/session.cpp) (Inference session), [`pdefa/src/pdefa_c_api.cpp`](https://github.com/hasnard/pdefa/blob/main/pdefa/src/pdefa_c_api.cpp) (Image API bridge), [`imageloader/src/preprocess.cpp`](https://github.com/hasnard/pdefa/blob/main/imageloader/src/preprocess.cpp) (Letterbox preprocess)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python API"]
  node_pyapi["Python API<br/>[__init__.py]"]
  node_bindings["ctypes bindings<br/>[_bindings.py]"]
  node_batch["Batch inference<br/>[batch.py]"]
  node_decode["YOLO postprocess<br/>[_bindings.py]"]
end

subgraph group_images["Image pipeline"]
  node_decoder["Image decoding<br/>[loader.cpp]"]
  node_formats["PNG / JPEG decoders<br/>[png_decoder.cpp]"]
  node_preprocess["Letterbox preprocess<br/>[preprocess.cpp]"]
  node_imageapi["Image API bridge<br/>[pdefa_c_api.cpp]"]
end

subgraph group_engine["Inference engine"]
  node_context["Context and threads<br/>[engine_api.cpp]"]
  node_model["Model loader<br/>[model.cpp]"]
  node_customloader["Custom format loader<br/>[custom_loader.cpp]"]
  node_session["Inference session<br/>[session.cpp]"]
  node_output["Inference output<br/>[session.cpp]"]
end

subgraph group_compute["Compute internals"]
  node_optimizer["Graph optimization"]
  node_layout["Layout transforms"]
  node_ops["Operator dispatch<br/>[conv2d.cpp]"]
  node_kernels["SIMD kernels"]
  node_memory["Tensor memory<br/>[memory_plan.cpp]"]
end

node_user(("Python caller"))
node_imagefile["Image file"]
node_model_file["Engine model file"]
node_results["Detection results"]

node_user -->|"calls"| node_pyapi
node_pyapi -->|"uses"| node_bindings
node_user -->|"selects"| node_imagefile
node_bindings -->|"calls"| node_imageapi
node_imageapi -->|"loads image"| node_decoder
node_decoder -->|"dispatches format"| node_formats
node_imageapi -->|"prepares tensor"| node_preprocess
node_preprocess -->|"returns tensor and metadata"| node_bindings
node_user -->|"selects"| node_model_file
node_bindings -->|"creates context"| node_context
node_bindings -->|"loads model"| node_model
node_model -->|"parses model"| node_customloader
node_bindings -->|"creates and runs"| node_session
node_session -->|"optimizes graph"| node_optimizer
node_session -->|"transforms tensors"| node_layout
node_session -->|"dispatches operators"| node_ops
node_ops -->|"selects kernels"| node_kernels
node_session -->|"plans tensor storage"| node_memory
node_session -->|"produces tensors"| node_output
node_bindings -->|"decodes output"| node_decode
node_output -->|"provides raw tensor"| node_decode
node_decode -->|"returns detections"| node_results
node_batch -->|"runs sessions"| node_session
node_batch -->|"prepares images"| node_preprocess

click node_pyapi "https://github.com/hasnard/pdefa/blob/main/pdefa/python/src/pdefa/__init__.py"
click node_bindings "https://github.com/hasnard/pdefa/blob/main/pdefa/python/src/pdefa/_bindings.py"
click node_batch "https://github.com/hasnard/pdefa/blob/main/pdefa/python/src/pdefa/batch.py"
click node_decoder "https://github.com/hasnard/pdefa/blob/main/imageloader/src/loader.cpp"
click node_formats "https://github.com/hasnard/pdefa/blob/main/imageloader/src/png/png_decoder.cpp"
click node_preprocess "https://github.com/hasnard/pdefa/blob/main/imageloader/src/preprocess.cpp"
click node_imageapi "https://github.com/hasnard/pdefa/blob/main/pdefa/src/pdefa_c_api.cpp"
click node_context "https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/api/engine_api.cpp"
click node_model "https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/core/model.cpp"
click node_customloader "https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/loader/custom_loader.cpp"
click node_session "https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/core/session.cpp"
click node_optimizer "https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/optimizer/graph_optimizer.cpp"
click node_layout "https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/optimizer/layout_transform.cpp"
click node_ops "https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/ops/conv2d.cpp"
click node_kernels "https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/kernels/kernel_registry.cpp"
click node_memory "https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/memory/memory_plan.cpp"
click node_output "https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/core/session.cpp"
click node_decode "https://github.com/hasnard/pdefa/blob/main/pdefa/python/src/pdefa/_bindings.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_pyapi,node_bindings,node_batch,node_decode toneBlue
class node_decoder,node_formats,node_preprocess,node_imageapi toneAmber
class node_context,node_model,node_customloader,node_session,node_output toneMint
class node_optimizer,node_layout,node_ops,node_kernels,node_memory toneRose
class node_user,node_imagefile,node_model_file,node_results toneIndigo
```

## Components

### Python API

- [Python API](https://github.com/hasnard/pdefa/blob/main/pdefa/python/src/pdefa/__init__.py): `pdefa/python/src/pdefa/__init__.py`
- [ctypes bindings](https://github.com/hasnard/pdefa/blob/main/pdefa/python/src/pdefa/_bindings.py): `pdefa/python/src/pdefa/_bindings.py`
- [Batch inference](https://github.com/hasnard/pdefa/blob/main/pdefa/python/src/pdefa/batch.py): `pdefa/python/src/pdefa/batch.py`
- [YOLO postprocess](https://github.com/hasnard/pdefa/blob/main/pdefa/python/src/pdefa/_bindings.py): `pdefa/python/src/pdefa/_bindings.py`

### Image pipeline

- [Image decoding](https://github.com/hasnard/pdefa/blob/main/imageloader/src/loader.cpp): `imageloader/src/loader.cpp`
- [PNG / JPEG decoders](https://github.com/hasnard/pdefa/blob/main/imageloader/src/png/png_decoder.cpp): `imageloader/src/png/png_decoder.cpp`
- [Letterbox preprocess](https://github.com/hasnard/pdefa/blob/main/imageloader/src/preprocess.cpp): `imageloader/src/preprocess.cpp`
- [Image API bridge](https://github.com/hasnard/pdefa/blob/main/pdefa/src/pdefa_c_api.cpp): `pdefa/src/pdefa_c_api.cpp`

### Inference engine

- [Context and threads](https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/api/engine_api.cpp): `PDEFA1.0/src/api/engine_api.cpp`
- [Model loader](https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/core/model.cpp): `PDEFA1.0/src/core/model.cpp`
- [Custom format loader](https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/loader/custom_loader.cpp): `PDEFA1.0/src/loader/custom_loader.cpp`
- [Inference session](https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/core/session.cpp): `PDEFA1.0/src/core/session.cpp`
- [Inference output](https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/core/session.cpp): `PDEFA1.0/src/core/session.cpp`

### Compute internals

- [Graph optimization](https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/optimizer/graph_optimizer.cpp): `PDEFA1.0/src/optimizer/graph_optimizer.cpp`
- [Layout transforms](https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/optimizer/layout_transform.cpp): `PDEFA1.0/src/optimizer/layout_transform.cpp`
- [Operator dispatch](https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/ops/conv2d.cpp): `PDEFA1.0/src/ops/conv2d.cpp`
- [SIMD kernels](https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/kernels/kernel_registry.cpp): `PDEFA1.0/src/kernels/kernel_registry.cpp`
- [Tensor memory](https://github.com/hasnard/pdefa/blob/main/PDEFA1.0/src/memory/memory_plan.cpp): `PDEFA1.0/src/memory/memory_plan.cpp`

### Other components

- **Python caller**
- **Image file**
- **Engine model file**
- **Detection results**

## Connections

- Python caller → Python API: calls
- Python API → ctypes bindings: uses
- Python caller → Image file: selects
- ctypes bindings → Image API bridge: calls
- Image API bridge → Image decoding: loads image
- Image decoding → PNG / JPEG decoders: dispatches format
- Image API bridge → Letterbox preprocess: prepares tensor
- Letterbox preprocess → ctypes bindings: returns tensor and metadata
- Python caller → Engine model file: selects
- ctypes bindings → Context and threads: creates context
- ctypes bindings → Model loader: loads model
- Model loader → Custom format loader: parses model
- ctypes bindings → Inference session: creates and runs
- Inference session → Graph optimization: optimizes graph
- Inference session → Layout transforms: transforms tensors
- Inference session → Operator dispatch: dispatches operators
- Operator dispatch → SIMD kernels: selects kernels
- Inference session → Tensor memory: plans tensor storage
- Inference session → Inference output: produces tensors
- ctypes bindings → YOLO postprocess: decodes output
- Inference output → YOLO postprocess: provides raw tensor
- YOLO postprocess → Detection results: returns detections
- Batch inference → Inference session: runs sessions
- Batch inference → Letterbox preprocess: prepares images