# sharmas1ddharth/3d-bin-packing architecture

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

- Interactive diagram: https://gitdiagram.com/sharmas1ddharth/3d-bin-packing
- Repository: https://github.com/sharmas1ddharth/3d-bin-packing

## Overview

##### Project Type and Purpose
- This is a backend microservice exposing a 3D Bin Packing algorithm over HTTP.
- Written in Python with a Cython-optimized core for performance.

##### Main Components
a. External Client
- Any consumer that sends HTTP requests (e.g., web app, CLI tool, another service).
b. API Layer (app/api & app/main.py)
- FastAPI (or similar) application instance, defined in app/main.py and app/api/app.py.
- Routing module (app/api/routing/binpacking_router) handles HTTP endpoints.
c. Schema Layer (app/schema/model.py)
- Pydantic models for request validation and response serialization.
d. Service Layer (app/src)
- items_packing.py – Python orchestration logic.
- load_combinations_generator.py – generates candidate load configurations.
e. Cython Core (app/src/load_optimiser_core)
- .pyx and .c modules (auxiliary_methods, constants, item, main) compiled at build time.
- High-performance routines for evaluating and scoring packings.
f. Build & CI (pyproject.toml, uv.lock, .github/workflows/pylint.yml)
- Defines build (Cython compilation), linting, and packaging.

##### Relationships & Data Flows
1. Client → HTTP request → API Layer (FastAPI)
2. API Layer → deserialize into Pydantic schema
3. Router/controller → calls Service Layer functions
4. Service Layer → invokes Cython Core functions via Python wrappers
5. Cython Core → computes packing solution → returns to Service Layer
6. Service Layer → wraps result in Pydantic model → API Layer
7. API Layer → serializes to JSON → HTTP response → Client

##### Architectural Patterns & Principles
- Layered Architecture (Controller → Service → Native Core)
- Clear separation of concerns:
- Validation/serialization (schema)
- Orchestration/business logic (service)
- Performance-critical code (Cython core)
- Build-time Cython compilation via pyproject.toml

##### Technologies & Frameworks to Highlight
- FastAPI (or starlette) for HTTP API
- Pydantic for schemas
- Cython for native extensions
- GitHub Actions for CI (pylint workflow)
- pyproject.toml for build configuration

- Client → FastAPI App (HTTP Request)
- App → Schema (validation)
- Router → Service (function call)
- Service → Cython Core (native call)
- Cython Core → Service (result)
- Service → App → Client (JSON response)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["External Client"]:::external

    subgraph "API Layer"
        FastAPI_Main["FastAPI App\n(app/main.py)"]:::python
        API_App["API Module\n(app/api/app.py)"]:::python
        BinRouter["Router / Controller\n(binpacking_router.py)"]:::python
        RouterUtils["Router Utils\n(utils.py)"]:::python
    end

    Schema["Schema (Pydantic)\n(model.py)"]:::python

    subgraph "Service Layer"
        ItemsPacking["Items Packing\n(items_packing.py)"]:::python
        LoadGen["Load Combinations Generator\n(load_combinations_generator.py)"]:::python
    end

    subgraph "Cython Core"
        CO_Init["__init__.py"]:::cython
        AuxPxy["auxiliary_methods.pyx"]:::cython
        AuxC["auxiliary_methods.c"]:::cython
        ConstPxy["constants.pyx"]:::cython
        ConstC["constants.c"]:::cython
        ItemPxy["item.pyx"]:::cython
        ItemC["item.c"]:::cython
        MainPy["main.py"]:::cython
    end

    subgraph "Build & CI"
        pyproject["pyproject.toml"]:::build
        uvlock["uv.lock"]:::build
        CI["pylint Workflow\n(.github/workflows/pylint.yml)"]:::build
    end

    Client -->|"HTTP POST /pack"| FastAPI_Main
    FastAPI_Main -->|"calls FastAPI App"| API_App
    API_App -->|"routes request"| BinRouter
    BinRouter -->|"validate"| Schema
    BinRouter -->|"calls"| ItemsPacking
    ItemsPacking -->|"calls"| LoadGen
    ItemsPacking -->|"native call"| MainPy
    MainPy -->|"result"| ItemsPacking
    ItemsPacking -->|"wrap result"| Schema
    Schema -->|"serialize JSON"| API_App
    API_App -->|"HTTP Response"| Client

    pyproject -->|"compiles .pyx → .c → .so"| AuxPxy
    uvlock -->|"locks deps"| FastAPI_Main
    CI -->|"runs lint"| FastAPI_Main

    click FastAPI_Main "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/main.py"
    click API_App "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/api/app.py"
    click BinRouter "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/api/routing/binpacking_router/binpacking_router.py"
    click RouterUtils "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/api/routing/binpacking_router/utils.py"
    click Schema "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/schema/model.py"
    click ItemsPacking "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/src/items_packing.py"
    click LoadGen "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/src/load_combinations_generator.py"
    click CO_Init "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/src/load_optimiser_core/__init__.py"
    click AuxPxy "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/src/load_optimiser_core/auxiliary_methods.pyx"
    click AuxC "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/src/load_optimiser_core/auxiliary_methods.c"
    click ConstPxy "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/src/load_optimiser_core/constants.pyx"
    click ConstC "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/src/load_optimiser_core/constants.c"
    click ItemPxy "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/src/load_optimiser_core/item.pyx"
    click ItemC "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/src/load_optimiser_core/item.c"
    click MainPy "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/app/src/load_optimiser_core/main.py"
    click pyproject "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/pyproject.toml"
    click uvlock "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/uv.lock"
    click CI "https://github.com/sharmas1ddharth/3d-bin-packing/blob/main/.github/workflows/pylint.yml"

    classDef external fill:#aaaaaa,stroke:#333,stroke-width:1px
    classDef python fill:#1f77b4,stroke:#333,stroke-width:1px,color:#fff
    classDef cython fill:#ff7f0e,stroke:#333,stroke-width:1px
    classDef build fill:#7f7f7f,stroke:#333,stroke-width:1px,color:#fff
```
