How sharmas1ddharth/3d-bin-packing works
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)