# oktaybobus/laytime architecture

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

- Interactive diagram: https://gitdiagram.com/oktaybobus/laytime
- Repository: https://github.com/oktaybobus/laytime

## Overview

laytime is a dependency-free Python calculator for GENCON-style voyage-charter laytime, demurrage and despatch. Callers provide a replayable JSON basis; either the public Python API or CLI passes it to the pure calculation engine and receives a result mapping or JSON. The engine handles port timing, calendar exceptions, interruptions, reversible allowances and monetary settlement. The CLI also reads files or stdin and reports invalid or incomplete bases. Internal calculation detail is grouped under the engine because the excerpts do not establish separate runtime modules for those stages.

Main entry points: [`src/laytime/cli.py`](https://github.com/oktaybobus/laytime/blob/main/src/laytime/cli.py) (JSON CLI), [`src/laytime/engine.py`](https://github.com/oktaybobus/laytime/blob/main/src/laytime/engine.py) (Laytime engine), [`src/laytime/__init__.py`](https://github.com/oktaybobus/laytime/blob/main/src/laytime/__init__.py) (Python API), [`src/laytime/__main__.py`](https://github.com/oktaybobus/laytime/blob/main/src/laytime/__main__.py) (Module entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_cli["JSON CLI<br/>[cli.py]"]
  node_entry["Module entry<br/>[__main__.py]"]
  node_api["Python API<br/>[__init__.py]"]
end

subgraph group_calculation["Calculation"]
  node_engine["Laytime engine<br/>[engine.py]"]
end

node_caller(("Basis provider"))
node_basis["Charter basis"]
node_result["Calculation result"]

node_caller -->|"provides basis"| node_api
node_api -->|"exports calculation"| node_engine
node_caller -->|"supplies JSON"| node_basis
node_basis -->|"read from input"| node_cli
node_entry -->|"calls main"| node_cli
node_cli -->|"calls compute"| node_engine
node_engine -->|"returns calculation"| node_result
node_cli -->|"writes JSON"| node_result

click node_cli "https://github.com/oktaybobus/laytime/blob/main/src/laytime/cli.py"
click node_entry "https://github.com/oktaybobus/laytime/blob/main/src/laytime/__main__.py"
click node_api "https://github.com/oktaybobus/laytime/blob/main/src/laytime/__init__.py"
click node_engine "https://github.com/oktaybobus/laytime/blob/main/src/laytime/engine.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_cli,node_entry,node_api toneBlue
class node_engine toneAmber
class node_caller,node_basis,node_result toneIndigo
```

## Components

### User interfaces

- [JSON CLI](https://github.com/oktaybobus/laytime/blob/main/src/laytime/cli.py): `src/laytime/cli.py`
- [Module entry](https://github.com/oktaybobus/laytime/blob/main/src/laytime/__main__.py): `src/laytime/__main__.py`
- [Python API](https://github.com/oktaybobus/laytime/blob/main/src/laytime/__init__.py): `src/laytime/__init__.py`

### Calculation

- [Laytime engine](https://github.com/oktaybobus/laytime/blob/main/src/laytime/engine.py): `src/laytime/engine.py`

### Other components

- **Basis provider**
- **Charter basis**
- **Calculation result**

## Connections

- Basis provider → Python API: provides basis (evidence: `src/laytime/__init__.py`)
- Python API → Laytime engine: exports calculation (evidence: `src/laytime/__init__.py`)
- Basis provider → Charter basis: supplies JSON (evidence: `README.md`)
- Charter basis → JSON CLI: read from input (evidence: `src/laytime/cli.py`)
- Module entry → JSON CLI: calls main (evidence: `src/laytime/__main__.py`)
- JSON CLI → Laytime engine: calls compute (evidence: `src/laytime/cli.py`)
- Laytime engine → Calculation result: returns calculation (evidence: `src/laytime/engine.py`)
- JSON CLI → Calculation result: writes JSON (evidence: `src/laytime/cli.py`)
