# Architecture

`fuggers-py` is organized around domain-first Python modules instead of compatibility layers.

## Layers

- `core`: primitive types, calendars, day counts, and low-level interfaces
- `math`: numerical building blocks used by curves and analytics
- `curves`: term structures, calibration, bumping, and multicurve helpers
- `bonds`: instruments, schedules, conventions, pricing helpers, options
- `analytics`: standalone pricing, yield, spread, and risk functions
- `portfolio`: aggregate analytics, attribution, benchmarking, liquidity, ETF tools, stress
- `data`: identifiers, market data, reference data, pricing specs, output records
- `io`: storage and transport interfaces plus concrete adapters
- `engine`: routing, scheduling, reactive workflows, engine configuration

## Dependency direction

- `core` and `math` are foundational.
- `curves` and `bonds` build on `core` and `math`.
- `analytics` depends on `bonds`, `curves`, and `core`.
- `portfolio` depends on `analytics`, `bonds`, and `core`.
- `data` holds research-facing records and providers and may use shared lower-layer types from `bonds.types`.
- `io` depends on `data` for persisted shapes.
- `engine` depends on `analytics`, `data`, and `io`.

## Public API guidance

- Prefer explicit imports such as `fuggers_py.analytics`, `fuggers_py.portfolio.risk`, or `fuggers_py.io`.
- Use top-level `fuggers_py` only for package discovery.
- Package roots are the stable convenience facades for common entry points and base exceptions.
- Specialized exception subclasses belong in plural `errors` modules such as `fuggers_py.analytics.errors` and `fuggers_py.data.errors`.
- Importing from removed compatibility namespaces is no longer supported.
