# 2. Codebase Architecture

## High-level layout

- `include/dtl/`: primary public C++ API and implementation headers
- `src/`: compiled components, including C ABI implementation units
- `bindings/python/`: pybind11 extension and high-level Python wrapper
- `bindings/fortran/`: ISO C binding module and tests
- `runtime/`: runtime registry and shared runtime support library
- `tests/`: C++ and integration tests
- `docs/`: user docs, specs, ADRs, API references

## Layers

1. Core types, status/result, policy model
2. Containers/views/algorithms
3. Communication and remote/RMA paths
4. Bindings and language adapters
5. Tooling/docs/release surfaces

## Change impact map

When changing a core contract, check all of:

- C++ public headers in `include/dtl/`
- C ABI mirrors in `include/dtl/bindings/c/` and `src/bindings/c/`
- Python wrappers in `bindings/python/src/dtl/`
- Fortran signatures in `bindings/fortran/dtl.f90`
- runtime and handle lifecycle behavior in `runtime/` and binding wrappers
- release notes

## Compatibility expectations

- Keep C++ API behavior stable unless explicitly versioned
- Keep C ABI status-code behavior deterministic
- Preserve Python and Fortran semantic parity where feasible
- Document any intentional incompatibilities before merge

## Runtime/handle references

- Runtime and handle development standards: `docs/developer_guide/12-runtime-and-handle-development.md`