detections/_docs/02_document/00_discovery.md

Codebase Discovery

Directory Tree

detections/
├── main.py                    # FastAPI entry point
├── setup.py                   # Cython build configuration
├── requirements.txt           # CPU dependencies
├── requirements-gpu.txt       # GPU dependencies (extends requirements.txt)
├── classes.json               # Object detection class definitions (19 classes)
├── .gitignore
├── inference.pyx / .pxd       # Core inference orchestrator (Cython)
├── inference_engine.pyx / .pxd # Abstract base engine class (Cython)
├── onnx_engine.pyx            # ONNX Runtime inference engine (Cython)
├── tensorrt_engine.pyx / .pxd # TensorRT inference engine (Cython)
├── annotation.pyx / .pxd      # Detection & Annotation data models (Cython)
├── ai_config.pyx / .pxd       # AI recognition config (Cython)
├── ai_availability_status.pyx / .pxd # AI status enum & state (Cython)
├── constants_inf.pyx / .pxd   # Constants, logging, class registry (Cython)
└── loader_http_client.py      # HTTP client for model loading/uploading

Tech Stack Summary

Aspect	Technology
Language	Python 3 + Cython
Web Framework	FastAPI + Uvicorn
ML Inference (CPU)	ONNX Runtime 1.22.0
ML Inference (GPU)	TensorRT 10.11.0 + PyCUDA 2025.1.1
Image Processing	OpenCV 4.10.0
Serialization	msgpack 1.1.1
HTTP Client	requests 2.32.4
Logging	loguru 0.7.3
GPU Monitoring	pynvml 12.0.0
Numeric	NumPy 2.3.0
Build	Cython 3.1.3 + setuptools

Dependency Graph

Internal Module Dependencies

constants_inf       ← (leaf) no internal deps
ai_config           ← (leaf) no internal deps
inference_engine    ← (leaf) no internal deps
loader_http_client  ← (leaf) no internal deps

ai_availability_status → constants_inf
annotation             → constants_inf

onnx_engine     → inference_engine, constants_inf
tensorrt_engine → inference_engine, constants_inf

inference → constants_inf, ai_availability_status, annotation, ai_config,
            onnx_engine | tensorrt_engine (conditional on GPU availability)

main → inference, constants_inf, loader_http_client

Mermaid Diagram

graph TD
    main["main.py (FastAPI)"]
    inference["inference"]
    onnx_engine["onnx_engine"]
    tensorrt_engine["tensorrt_engine"]
    inference_engine["inference_engine (abstract)"]
    annotation["annotation"]
    ai_availability_status["ai_availability_status"]
    ai_config["ai_config"]
    constants_inf["constants_inf"]
    loader_http_client["loader_http_client"]

    main --> inference
    main --> constants_inf
    main --> loader_http_client

    inference --> constants_inf
    inference --> ai_availability_status
    inference --> annotation
    inference --> ai_config
    inference -.->|GPU available| tensorrt_engine
    inference -.->|CPU fallback| onnx_engine

    onnx_engine --> inference_engine
    onnx_engine --> constants_inf

    tensorrt_engine --> inference_engine
    tensorrt_engine --> constants_inf

    ai_availability_status --> constants_inf
    annotation --> constants_inf

Topological Processing Order

1. constants_inf (leaf)
2. ai_config (leaf)
3. inference_engine (leaf)
4. loader_http_client (leaf)
5. ai_availability_status (depends: constants_inf)
6. annotation (depends: constants_inf)
7. onnx_engine (depends: inference_engine, constants_inf)
8. tensorrt_engine (depends: inference_engine, constants_inf)
9. inference (depends: constants_inf, ai_availability_status, annotation, ai_config, onnx_engine/tensorrt_engine)
10. main (depends: inference, constants_inf, loader_http_client)

Entry Points

• main.py — FastAPI application, serves HTTP API on uvicorn

Leaf Modules

• constants_inf — constants, logging, class registry
• ai_config — recognition configuration data class
• inference_engine — abstract base class for engines
• loader_http_client — HTTP client for external loader service

Cycles

None detected.

External Services

Service	URL Source	Purpose
Loader	LOADER_URL env var (default http://loader:8080)	Download/upload AI models
Annotations	ANNOTATIONS_URL env var (default http://annotations:8080)	Post detection results, refresh auth tokens

Data Files

• classes.json — 19 object detection classes with Ukrainian short names, colors, and max physical size in meters (ArmorVehicle, Truck, Vehicle, Artillery, Shadow, Trenches, MilitaryMan, TyreTracks, etc.)