Architecture Overview¶

This page is a technical map of the project at multiple levels of detail. It is meant to shorten onboarding and show where the more detailed documents should be opened next.

1. Documentation Architecture¶

flowchart LR
    A[Product Specification] --> B[Product Roadmap]
    A --> C[Bond Engine Architecture]
    C --> D[Analysis Models Architecture]
    D --> E[Result Model Contract]
    E --> F[Data and Persistence Contracts]
    C --> G[Family Logic Documents]
    G --> H[Per-Bond Logic Documents]
    C --> I[Telemetry Worker]

Use this graph to understand how the documentation set is layered:

the specification defines the product
the roadmap defines sequencing and dependency logic
the architecture document defines technical boundaries
the analysis-models document defines how one simulation can support multiple defended interpretations
the result model contract defines the canonical engine output boundary
the data/persistence contracts define what should be durably stored and reconstructed later
family and product documents describe calculation details
telemetry is operational and cross-cutting

Detailed documents:

2. Runtime Product Architecture¶

flowchart LR
    A[User input / future assistant] --> B[Form state and selection rules]
    B --> C[Bond engine]
    C --> D[Annual families]
    C --> E[Monthly families]
    C --> F[Product-specific strategies]
    C --> G[Internal simulation data]
    G --> H[Canonical result model]
    H --> I[Analysis models]
    I --> J[Presentation adapters]
    J --> K[Charts, tables, summary cards]
    H --> L[Saved simulations / future data layer]

This graph shows the product as a running system:

input enters through the form today and may also enter through a future assistant
selection and eligibility rules sit before the engine
the engine delegates to shared families and product-specific strategies
internal simulation data may be richer than the canonical result contract
the canonical result model feeds analysis models, adapters, and future persistence
analysis models allow the same result to be interpreted in more than one defended way without changing engine output

Detailed documents:

3. Calculation Strategy Decomposition¶

flowchart TD
    A[Bond engine] --> B[Selection boundary]
    A --> C[Shared strategy families]
    A --> D[Product-specific logic]
    C --> E[Annual accumulation]
    C --> F[Annual payout]
    D --> G[OTS / ODS]
    D --> H[ROR]
    D --> I[DOR]
    D --> J[TOS]
    D --> K[COI]
    D --> L[EDO]
    D --> M[ROS]
    D --> N[ROD]

This graph is useful when deciding where a change belongs:

selection rules should not drift into strategy code
shared families should own repeated mechanics
product-specific files should own only product-specific rules
canonical result semantics should not be redefined inside individual UI components
alternative analytical interpretations should be introduced in the analysis-model layer, not hidden in tables or charts

Detailed documents:

4. Operational and Publishing Architecture¶

flowchart LR
    A[docs/] --> B[npm run docs:sync]
    B --> C[mkdocs-site/docs/]
    C --> D[MkDocs build]
    D --> E[Published documentation site]
    F[Frontend app] --> G[Telemetry events]
    G --> H[Cloudflare Worker]
    H --> I[Stats and event history]

This graph combines two operational concerns:

how source documentation becomes the published docs site
how the deployed application reports anonymous event telemetry

Detailed documents:

5. How to Read the Architecture¶

Start with Bond engine architecture if you are new to the codebase.
Read Analysis models architecture when the feature changes result interpretation rather than only rendering.
Open a family document before touching multiple bond types with the same mechanics.
Open a product-specific logic document before changing one bond strategy.
Use Document catalog whenever you are unsure which document should own a decision.