# mdlacasse/owl architecture

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

- Interactive diagram: https://gitdiagram.com/mdlacasse/owl
- Repository: https://github.com/mdlacasse/owl

## Overview

Owl is a retirement-planning optimizer exposed through a Streamlit application, command-line interface, and MCP tools. Users provide household, account, goals, tax, and rate assumptions; Owl builds a multi-year plan, optimizes withdrawals and conversions under tax and benefit rules, then presents results and stress tests. README documentation establishes capabilities beyond the sampled implementation excerpts, including tax coverage and stochastic analysis; those are represented at subsystem level. The excerpts do not establish every UI or CLI call path, so uncertain wiring is omitted.

Main entry points: [`src/owlplanner/plan.py`](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/plan.py) (Retirement plan), [`src/owlplanner/assistant/tools.py`](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/assistant/tools.py) (Assistant tools), [`src/owlplanner/plotting/factory.py`](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/plotting/factory.py) (Plotting), [`ui/main.py`](https://github.com/mdlacasse/owl/blob/main/ui/main.py) (Streamlit app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web["Streamlit app<br/>[main.py]"]
  node_cli["CLI<br/>[_main.py]"]
end

subgraph group_planning["Plan modeling"]
  node_config["Case configuration<br/>[schema.py]"]
  node_bridge["UI config bridge<br/>[ui_bridge.py]"]
  node_plan["Retirement plan<br/>[plan.py]"]
  node_tax["Tax and benefits<br/>[tax_federal.py]"]
  node_rates["Rate models<br/>[loader.py]"]
  node_ratefamilies["Built-in rate models<br/>[builtin.py]"]
end

subgraph group_optimization["Optimization and analysis"]
  node_solver["Plan optimizer<br/>[plan.py]"]
  node_stress["Stress analysis<br/>[stresstests.py]"]
  node_compare["Baseline comparison<br/>[tools.py]"]
  node_explain["Optimization explanation<br/>[explain.py]"]
end

subgraph group_assistant["AI integration"]
  node_assistant_tools["Assistant tools<br/>[tools.py]"]
  node_mcp["MCP service<br/>[cmd_serve.py]"]
end

subgraph group_presentation["Results and views"]
  node_plots["Plotting<br/>[factory.py]"]
  node_plotbackend["Plot backends<br/>[plotly_backend.py]"]
  node_reports["Reports and exports<br/>[export.py]"]
end

node_retiree(("Planner"))
node_assistant_client(("MCP-compatible AI"))

node_retiree -->|"enters assumptions"| node_web
node_retiree -->|"runs commands"| node_cli
node_web -->|"maps case values"| node_bridge
node_bridge -->|"forms configuration"| node_config
node_cli -->|"loads case"| node_config
node_config -->|"configures plan"| node_plan
node_plan -->|"loads rate model"| node_rates
node_rates -->|"selects model"| node_ratefamilies
node_plan -->|"models tax rules"| node_tax
node_plan -->|"builds optimization"| node_solver
node_solver -->|"returns solution"| node_plan
node_plan -->|"runs scenarios"| node_stress
node_assistant_tools -->|"builds and runs"| node_plan
node_assistant_tools -->|"computes frontiers"| node_stress
node_assistant_tools -->|"compares strategies"| node_compare
node_assistant_tools -->|"explains results"| node_explain
node_assistant_client -->|"requests tools"| node_mcp
node_mcp -->|"dispatches tools"| node_assistant_tools
node_web -->|"presents charts"| node_plots
node_cli -.->|"requests charts"| node_plots
node_plots -->|"renders figures"| node_plotbackend
node_plan -.->|"exports plan results"| node_reports
node_stress -->|"provides scenario results"| node_plots

click node_web "https://github.com/mdlacasse/owl/blob/main/ui/main.py"
click node_cli "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/cli/_main.py"
click node_config "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/config/schema.py"
click node_bridge "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/config/ui_bridge.py"
click node_plan "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/plan.py"
click node_tax "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/tax_federal.py"
click node_rates "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/rate_models/loader.py"
click node_ratefamilies "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/rate_models/builtin.py"
click node_solver "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/plan.py"
click node_stress "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/stresstests.py"
click node_compare "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/assistant/tools.py"
click node_explain "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/assistant/explain.py"
click node_plots "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/plotting/factory.py"
click node_plotbackend "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/plotting/plotly_backend.py"
click node_reports "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/export.py"
click node_assistant_tools "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/assistant/tools.py"
click node_mcp "https://github.com/mdlacasse/owl/blob/main/src/owlplanner/cli/cmd_serve.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_web,node_cli toneBlue
class node_config,node_bridge,node_plan,node_tax,node_rates,node_ratefamilies toneAmber
class node_solver,node_stress,node_compare,node_explain toneMint
class node_assistant_tools,node_mcp toneRose
class node_plots,node_plotbackend,node_reports,node_retiree,node_assistant_client toneIndigo
```

## Components

### User interfaces

- [Streamlit app](https://github.com/mdlacasse/owl/blob/main/ui/main.py): `ui/main.py`
- [CLI](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/cli/_main.py): `src/owlplanner/cli/_main.py`

### Plan modeling

- [Case configuration](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/config/schema.py): `src/owlplanner/config/schema.py`
- [UI config bridge](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/config/ui_bridge.py): `src/owlplanner/config/ui_bridge.py`
- [Retirement plan](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/plan.py): `src/owlplanner/plan.py`
- [Tax and benefits](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/tax_federal.py): `src/owlplanner/tax_federal.py`
- [Rate models](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/rate_models/loader.py): `src/owlplanner/rate_models/loader.py`
- [Built-in rate models](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/rate_models/builtin.py): `src/owlplanner/rate_models/builtin.py`

### Optimization and analysis

- [Plan optimizer](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/plan.py): `src/owlplanner/plan.py`
- [Stress analysis](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/stresstests.py): `src/owlplanner/stresstests.py`
- [Baseline comparison](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/assistant/tools.py): `src/owlplanner/assistant/tools.py`
- [Optimization explanation](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/assistant/explain.py): `src/owlplanner/assistant/explain.py`

### AI integration

- [Assistant tools](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/assistant/tools.py): `src/owlplanner/assistant/tools.py`
- [MCP service](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/cli/cmd_serve.py): `src/owlplanner/cli/cmd_serve.py`

### Results and views

- [Plotting](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/plotting/factory.py): `src/owlplanner/plotting/factory.py`
- [Plot backends](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/plotting/plotly_backend.py): `src/owlplanner/plotting/plotly_backend.py`
- [Reports and exports](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/export.py): `src/owlplanner/export.py`

### Other components

- **Planner**
- **MCP-compatible AI**

## Connections

- Planner → Streamlit app: enters assumptions
- Planner → CLI: runs commands
- Streamlit app → UI config bridge: maps case values
- UI config bridge → Case configuration: forms configuration
- CLI → Case configuration: loads case
- Case configuration → Retirement plan: configures plan
- Retirement plan → Rate models: loads rate model
- Rate models → Built-in rate models: selects model
- Retirement plan → Tax and benefits: models tax rules
- Retirement plan → Plan optimizer: builds optimization
- Plan optimizer → Retirement plan: returns solution
- Retirement plan → Stress analysis: runs scenarios
- Assistant tools → Retirement plan: builds and runs
- Assistant tools → Stress analysis: computes frontiers
- Assistant tools → Baseline comparison: compares strategies
- Assistant tools → Optimization explanation: explains results
- MCP-compatible AI → MCP service: requests tools
- MCP service → Assistant tools: dispatches tools
- Streamlit app → Plotting: presents charts
- CLI → Plotting: requests charts
- Plotting → Plot backends: renders figures
- Retirement plan → Reports and exports: exports plan results
- Stress analysis → Plotting: provides scenario results