# petbox-dev/dca architecture

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

- Interactive diagram: https://gitdiagram.com/petbox-dev/dca
- Repository: https://github.com/petbox-dev/dca

## Overview

petbox-dca is a typed petroleum-engineering library for forecasting production with decline-curve models and deriving associated gas or water phases. The main workflow is to select a primary model, evaluate its rate or cumulative production over time, optionally attach a yield model for another phase, and evaluate that phase; interval-volume helpers support reporting. The standalone Bourdet function provides derivative smoothing for diagnostics. The excerpts show the shared evaluation and phase-composition interfaces, but not every model implementation, so uncertain internal wiring is omitted.

Main entry points: [`petbox/dca/base.py`](https://github.com/petbox-dev/dca/blob/main/petbox/dca/base.py) (Decline Interface), [`petbox/dca/__init__.py`](https://github.com/petbox-dev/dca/blob/main/petbox/dca/__init__.py) (Package API), [`petbox/dca/associated.py`](https://github.com/petbox-dev/dca/blob/main/petbox/dca/associated.py) (Yield Models), [`petbox/dca/primary.py`](https://github.com/petbox-dev/dca/blob/main/petbox/dca/primary.py) (Decline Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_package["Package API<br/>[__init__.py]"]
  node_production["Production Outputs<br/>[base.py]"]
end

subgraph group_primary["Primary Forecast"]
  node_decline["Decline Interface<br/>[base.py]"]
  node_models["Decline Models<br/>[primary.py]"]
end

subgraph group_phases["Associated Phases"]
  node_phase_interfaces["Phase Interfaces<br/>[base.py]"]
  node_yield_models["Yield Models<br/>[associated.py]"]
end

subgraph group_numerics["Numerics and Diagnostics"]
  node_integrator["Numerical Integration<br/>[base.py]"]
  node_scipy["SciPy"]
  node_bourdet["Bourdet Smoothing<br/>[bourdet.py]"]
  node_numpy["NumPy"]
end

node_engineer(("Engineer"))

node_engineer -->|"uses"| node_package
node_package -->|"exports"| node_decline
node_package -->|"exports"| node_models
node_package -->|"exports"| node_phase_interfaces
node_package -->|"exports"| node_yield_models
node_package -->|"exports"| node_bourdet
node_models -->|"extends"| node_decline
node_decline -->|"dispatches"| node_models
node_decline -->|"integrates"| node_integrator
node_integrator -->|"calls"| node_scipy
node_decline -->|"returns"| node_production
node_decline -->|"attaches"| node_phase_interfaces
node_yield_models -->|"implements"| node_phase_interfaces
node_yield_models -->|"reads rate"| node_decline
node_bourdet -->|"computes with"| node_numpy
node_engineer -->|"uses"| node_bourdet

click node_package "https://github.com/petbox-dev/dca/blob/main/petbox/dca/__init__.py"
click node_decline "https://github.com/petbox-dev/dca/blob/main/petbox/dca/base.py"
click node_models "https://github.com/petbox-dev/dca/blob/main/petbox/dca/primary.py"
click node_phase_interfaces "https://github.com/petbox-dev/dca/blob/main/petbox/dca/base.py"
click node_yield_models "https://github.com/petbox-dev/dca/blob/main/petbox/dca/associated.py"
click node_production "https://github.com/petbox-dev/dca/blob/main/petbox/dca/base.py"
click node_integrator "https://github.com/petbox-dev/dca/blob/main/petbox/dca/base.py"
click node_bourdet "https://github.com/petbox-dev/dca/blob/main/petbox/dca/bourdet.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_package,node_production toneBlue
class node_decline,node_models toneAmber
class node_phase_interfaces,node_yield_models toneMint
class node_integrator,node_scipy,node_bourdet,node_numpy toneRose
class node_engineer toneIndigo
```

## Components

### Public API

- [Package API](https://github.com/petbox-dev/dca/blob/main/petbox/dca/__init__.py): `petbox/dca/__init__.py`
- [Production Outputs](https://github.com/petbox-dev/dca/blob/main/petbox/dca/base.py): `petbox/dca/base.py`

### Primary Forecast

- [Decline Interface](https://github.com/petbox-dev/dca/blob/main/petbox/dca/base.py): `petbox/dca/base.py`
- [Decline Models](https://github.com/petbox-dev/dca/blob/main/petbox/dca/primary.py): `petbox/dca/primary.py`

### Associated Phases

- [Phase Interfaces](https://github.com/petbox-dev/dca/blob/main/petbox/dca/base.py): `petbox/dca/base.py`
- [Yield Models](https://github.com/petbox-dev/dca/blob/main/petbox/dca/associated.py): `petbox/dca/associated.py`

### Numerics and Diagnostics

- [Numerical Integration](https://github.com/petbox-dev/dca/blob/main/petbox/dca/base.py): `petbox/dca/base.py`
- **SciPy**
- [Bourdet Smoothing](https://github.com/petbox-dev/dca/blob/main/petbox/dca/bourdet.py): `petbox/dca/bourdet.py`
- **NumPy**

### Other components

- **Engineer**

## Connections

- Engineer → Package API: uses
- Package API → Decline Interface: exports
- Package API → Decline Models: exports
- Package API → Phase Interfaces: exports
- Package API → Yield Models: exports
- Package API → Bourdet Smoothing: exports
- Decline Models → Decline Interface: extends
- Decline Interface → Decline Models: dispatches
- Decline Interface → Numerical Integration: integrates
- Numerical Integration → SciPy: calls
- Decline Interface → Production Outputs: returns
- Decline Interface → Phase Interfaces: attaches
- Yield Models → Phase Interfaces: implements
- Yield Models → Decline Interface: reads rate
- Bourdet Smoothing → NumPy: computes with
- Engineer → Bourdet Smoothing: uses