# andre-hjr/flog architecture

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

- Interactive diagram: https://gitdiagram.com/andre-hjr/flog
- Repository: https://github.com/andre-hjr/flog

## Overview

Flog is a desktop well-log interpretation application. Users open or import well data, select curves for linked depth-track plotting, and can interactively compute interpretations or extend the workflow with plugins. The Agent offers a separate natural-language route to application tools over rpc-x; it can run plugins or sandboxed Python and write results back. The graph includes documented imaging, export, and petrophysical capabilities. Source excerpts establish core assembly and storage relationships; README.md supports documented product flows where implementation was not sampled.

Main entry points: [`src/flog/data/repository.py`](https://github.com/andre-hjr/flog/blob/main/src/flog/data/repository.py) (Curve Repository), [`src/flog/app.py`](https://github.com/andre-hjr/flog/blob/main/src/flog/app.py) (App Assembly), [`src/flog/agent/session.py`](https://github.com/andre-hjr/flog/blob/main/src/flog/agent/session.py) (Agent Session), [`src/flog/ui/main_window.py`](https://github.com/andre-hjr/flog/blob/main/src/flog/ui/main_window.py) (Main Window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_appctx["App Assembly<br/>[app.py]"]
  node_window["Main Window<br/>[main_window.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_data["Well Data"]
  node_repository["Curve Repository<br/>[repository.py]"]
  node_database[("SQLite Workspace<br/>[database.py]")]
  node_wellio["LAS Import/Export<br/>[wellio.py]"]
  node_sampling["Sampling Alignment<br/>[sampling.py]"]
  node_refs["Curve References<br/>[refs.py]"]
end

subgraph group_interpret["Interpretation"]
  node_quanti["Quanti Solver<br/>[engine.py]"]
  node_quanti_controller["Quanti Controller<br/>[controller.py]"]
  node_petro["Petrophysics<br/>[numpy_kernels.py]"]
  node_plugins["Plugin Registry<br/>[registry.py]"]
  node_plugin_contract["Plugin Contract<br/>[base.py]"]
end

subgraph group_agent["Agent and RPC"]
  node_agent_panel["Agent Panel<br/>[panel.py]"]
  node_agent_session["Agent Session<br/>[session.py]"]
  node_rpc_client["RPC Client<br/>[client.py]"]
  node_rpc_server["RPC Server<br/>[server.py]"]
  node_rpc_tools["RPC Tools<br/>[tools.py]"]
  node_providers["LLM Providers<br/>[base.py]"]
  node_sandbox["Python Sandbox<br/>[sandbox.py]"]
end

subgraph group_visual["Visualization"]
  node_plotview["Plot View<br/>[view.py]"]
  node_tracks["Track Rendering<br/>[tracks.py]"]
  node_plot_spec["Plot Specification<br/>[spec.py]"]
  node_viewers["Viewer Registry<br/>[registry.py]"]
  node_imaging["FMI/NMR Imaging<br/>[image_track.py]"]
  node_plot_export["Plot Export<br/>[exporters.py]"]
end

node_user(("Geoscientist"))
node_llm(("LLM Service"))

node_user -->|"uses"| node_window
node_appctx -->|"opens"| node_database
node_appctx -->|"constructs"| node_repository
node_appctx -->|"creates"| node_window
node_appctx -->|"loads"| node_plugins
node_appctx -->|"loads"| node_viewers
node_appctx -->|"starts"| node_rpc_server
node_appctx -->|"reads"| node_config
node_window -->|"uses"| node_repository
node_window -->|"wires"| node_plotview
node_user -->|"imports LAS"| node_wellio
node_wellio -->|"writes dataset"| node_repository
node_repository -->|"reads/writes"| node_database
node_repository -->|"uses axes"| node_sampling
node_repository -->|"returns records"| node_refs
node_plotview -.->|"loads curves"| node_repository
node_plotview -->|"renders"| node_tracks
node_tracks -->|"uses specs"| node_plot_spec
node_tracks -->|"identifies curves"| node_refs
node_viewers -.->|"registers viewer"| node_imaging
node_user -->|"adjusts parameters"| node_quanti_controller
node_quanti_controller -->|"runs solver"| node_quanti
node_quanti -->|"loads curves"| node_repository
node_quanti -->|"aligns inputs"| node_sampling
node_user -->|"extends workflow"| node_plugins
node_plugins -->|"registers plugins"| node_plugin_contract
node_plugin_contract -->|"reads curves"| node_repository
node_user -->|"asks interpretation"| node_agent_panel
node_window -->|"hosts panel"| node_agent_panel
node_agent_panel -.->|"starts session"| node_agent_session
node_agent_session -->|"queries model"| node_providers
node_providers -.->|"requests completion"| node_llm
node_agent_session -->|"calls tools"| node_rpc_client
node_rpc_client -->|"sends requests"| node_rpc_server
node_rpc_server -->|"dispatches tools"| node_rpc_tools
node_rpc_tools -->|"reads/writes data"| node_repository
node_agent_session -->|"runs Python"| node_sandbox
node_agent_session -->|"executes plugin"| node_plugins
node_rpc_tools -.->|"runs interpretation"| node_quanti
node_plotview -.->|"exports plot"| node_plot_export
node_quanti -.->|"uses kernels"| node_petro

click node_appctx "https://github.com/andre-hjr/flog/blob/main/src/flog/app.py"
click node_window "https://github.com/andre-hjr/flog/blob/main/src/flog/ui/main_window.py"
click node_config "https://github.com/andre-hjr/flog/blob/main/src/flog/config.py"
click node_repository "https://github.com/andre-hjr/flog/blob/main/src/flog/data/repository.py"
click node_database "https://github.com/andre-hjr/flog/blob/main/src/flog/data/database.py"
click node_wellio "https://github.com/andre-hjr/flog/blob/main/src/flog/data/wellio.py"
click node_sampling "https://github.com/andre-hjr/flog/blob/main/src/flog/data/sampling.py"
click node_refs "https://github.com/andre-hjr/flog/blob/main/src/flog/core/refs.py"
click node_plotview "https://github.com/andre-hjr/flog/blob/main/src/flog/plot/view.py"
click node_tracks "https://github.com/andre-hjr/flog/blob/main/src/flog/plot/tracks.py"
click node_plot_spec "https://github.com/andre-hjr/flog/blob/main/src/flog/plot/spec.py"
click node_viewers "https://github.com/andre-hjr/flog/blob/main/src/flog/viewers/registry.py"
click node_imaging "https://github.com/andre-hjr/flog/blob/main/src/flog/imaging/image_track.py"
click node_plot_export "https://github.com/andre-hjr/flog/blob/main/src/flog/plot/exporters.py"
click node_quanti "https://github.com/andre-hjr/flog/blob/main/src/flog/quanti/engine.py"
click node_quanti_controller "https://github.com/andre-hjr/flog/blob/main/src/flog/quanti/controller.py"
click node_petro "https://github.com/andre-hjr/flog/blob/main/src/flog/petrophysics/numpy_kernels.py"
click node_plugins "https://github.com/andre-hjr/flog/blob/main/src/flog/plugins/registry.py"
click node_plugin_contract "https://github.com/andre-hjr/flog/blob/main/src/flog/plugins/base.py"
click node_agent_panel "https://github.com/andre-hjr/flog/blob/main/src/flog/agent/panel.py"
click node_agent_session "https://github.com/andre-hjr/flog/blob/main/src/flog/agent/session.py"
click node_rpc_client "https://github.com/andre-hjr/flog/blob/main/src/flog/rpcx/client.py"
click node_rpc_server "https://github.com/andre-hjr/flog/blob/main/src/flog/rpcx/server.py"
click node_rpc_tools "https://github.com/andre-hjr/flog/blob/main/src/flog/rpcx/tools.py"
click node_providers "https://github.com/andre-hjr/flog/blob/main/src/flog/agent/providers/base.py"
click node_sandbox "https://github.com/andre-hjr/flog/blob/main/src/flog/agent/sandbox.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_appctx,node_window,node_config toneBlue
class node_repository,node_database,node_wellio,node_sampling,node_refs toneAmber
class node_quanti,node_quanti_controller,node_petro,node_plugins,node_plugin_contract toneMint
class node_agent_panel,node_agent_session,node_rpc_client,node_rpc_server,node_rpc_tools,node_providers,node_sandbox toneRose
class node_plotview,node_tracks,node_plot_spec,node_viewers,node_imaging,node_plot_export,node_user,node_llm toneIndigo
```

## Components

### Application

- [App Assembly](https://github.com/andre-hjr/flog/blob/main/src/flog/app.py): `src/flog/app.py`
- [Main Window](https://github.com/andre-hjr/flog/blob/main/src/flog/ui/main_window.py): `src/flog/ui/main_window.py`
- [Configuration](https://github.com/andre-hjr/flog/blob/main/src/flog/config.py): `src/flog/config.py`

### Well Data

- [Curve Repository](https://github.com/andre-hjr/flog/blob/main/src/flog/data/repository.py): `src/flog/data/repository.py`
- [SQLite Workspace](https://github.com/andre-hjr/flog/blob/main/src/flog/data/database.py): `src/flog/data/database.py`
- [LAS Import/Export](https://github.com/andre-hjr/flog/blob/main/src/flog/data/wellio.py): `src/flog/data/wellio.py`
- [Sampling Alignment](https://github.com/andre-hjr/flog/blob/main/src/flog/data/sampling.py): `src/flog/data/sampling.py`
- [Curve References](https://github.com/andre-hjr/flog/blob/main/src/flog/core/refs.py): `src/flog/core/refs.py`

### Interpretation

- [Quanti Solver](https://github.com/andre-hjr/flog/blob/main/src/flog/quanti/engine.py): `src/flog/quanti/engine.py`
- [Quanti Controller](https://github.com/andre-hjr/flog/blob/main/src/flog/quanti/controller.py): `src/flog/quanti/controller.py`
- [Petrophysics](https://github.com/andre-hjr/flog/blob/main/src/flog/petrophysics/numpy_kernels.py): `src/flog/petrophysics/numpy_kernels.py`
- [Plugin Registry](https://github.com/andre-hjr/flog/blob/main/src/flog/plugins/registry.py): `src/flog/plugins/registry.py`
- [Plugin Contract](https://github.com/andre-hjr/flog/blob/main/src/flog/plugins/base.py): `src/flog/plugins/base.py`

### Agent and RPC

- [Agent Panel](https://github.com/andre-hjr/flog/blob/main/src/flog/agent/panel.py): `src/flog/agent/panel.py`
- [Agent Session](https://github.com/andre-hjr/flog/blob/main/src/flog/agent/session.py): `src/flog/agent/session.py`
- [RPC Client](https://github.com/andre-hjr/flog/blob/main/src/flog/rpcx/client.py): `src/flog/rpcx/client.py`
- [RPC Server](https://github.com/andre-hjr/flog/blob/main/src/flog/rpcx/server.py): `src/flog/rpcx/server.py`
- [RPC Tools](https://github.com/andre-hjr/flog/blob/main/src/flog/rpcx/tools.py): `src/flog/rpcx/tools.py`
- [LLM Providers](https://github.com/andre-hjr/flog/blob/main/src/flog/agent/providers/base.py): `src/flog/agent/providers/base.py`
- [Python Sandbox](https://github.com/andre-hjr/flog/blob/main/src/flog/agent/sandbox.py): `src/flog/agent/sandbox.py`

### Visualization

- [Plot View](https://github.com/andre-hjr/flog/blob/main/src/flog/plot/view.py): `src/flog/plot/view.py`
- [Track Rendering](https://github.com/andre-hjr/flog/blob/main/src/flog/plot/tracks.py): `src/flog/plot/tracks.py`
- [Plot Specification](https://github.com/andre-hjr/flog/blob/main/src/flog/plot/spec.py): `src/flog/plot/spec.py`
- [Viewer Registry](https://github.com/andre-hjr/flog/blob/main/src/flog/viewers/registry.py): `src/flog/viewers/registry.py`
- [FMI/NMR Imaging](https://github.com/andre-hjr/flog/blob/main/src/flog/imaging/image_track.py): `src/flog/imaging/image_track.py`
- [Plot Export](https://github.com/andre-hjr/flog/blob/main/src/flog/plot/exporters.py): `src/flog/plot/exporters.py`

### Other components

- **Geoscientist**
- **LLM Service**

## Connections

- Geoscientist → Main Window: uses (evidence: `README.md`)
- App Assembly → SQLite Workspace: opens (evidence: `src/flog/app.py`)
- App Assembly → Curve Repository: constructs (evidence: `src/flog/app.py`)
- App Assembly → Main Window: creates (evidence: `src/flog/app.py`)
- App Assembly → Plugin Registry: loads (evidence: `src/flog/app.py`)
- App Assembly → Viewer Registry: loads (evidence: `src/flog/app.py`)
- App Assembly → RPC Server: starts (evidence: `src/flog/app.py`)
- App Assembly → Configuration: reads (evidence: `src/flog/app.py`)
- Main Window → Curve Repository: uses (evidence: `src/flog/ui/main_window.py`)
- Main Window → Plot View: wires (evidence: `src/flog/ui/main_window.py`)
- Geoscientist → LAS Import/Export: imports LAS (evidence: `README.md`)
- LAS Import/Export → Curve Repository: writes dataset (evidence: `src/flog/data/wellio.py`)
- Curve Repository → SQLite Workspace: reads/writes (evidence: `src/flog/data/repository.py`)
- Curve Repository → Sampling Alignment: uses axes (evidence: `src/flog/data/repository.py`)
- Curve Repository → Curve References: returns records (evidence: `src/flog/data/repository.py`)
- Plot View → Curve Repository: loads curves
- Plot View → Track Rendering: renders
- Track Rendering → Plot Specification: uses specs (evidence: `src/flog/plot/tracks.py`)
- Track Rendering → Curve References: identifies curves (evidence: `src/flog/plot/tracks.py`)
- Viewer Registry → FMI/NMR Imaging: registers viewer
- Geoscientist → Quanti Controller: adjusts parameters (evidence: `README.md`)
- Quanti Controller → Quanti Solver: runs solver (evidence: `src/flog/quanti/controller.py`)
- Quanti Solver → Curve Repository: loads curves (evidence: `src/flog/quanti/engine.py`)
- Quanti Solver → Sampling Alignment: aligns inputs (evidence: `src/flog/quanti/engine.py`)
- Geoscientist → Plugin Registry: extends workflow (evidence: `README.md`)
- Plugin Registry → Plugin Contract: registers plugins (evidence: `src/flog/plugins/registry.py`)
- Plugin Contract → Curve Repository: reads curves (evidence: `src/flog/plugins/base.py`)
- Geoscientist → Agent Panel: asks interpretation (evidence: `README.md`)
- Main Window → Agent Panel: hosts panel (evidence: `src/flog/ui/main_window.py`)
- Agent Panel → Agent Session: starts session
- Agent Session → LLM Providers: queries model (evidence: `src/flog/agent/session.py`)
- LLM Providers → LLM Service: requests completion
- Agent Session → RPC Client: calls tools (evidence: `src/flog/agent/session.py`)
- RPC Client → RPC Server: sends requests (evidence: `src/flog/rpcx/client.py`)
- RPC Server → RPC Tools: dispatches tools (evidence: `src/flog/rpcx/server.py`)
- RPC Tools → Curve Repository: reads/writes data (evidence: `src/flog/rpcx/tools.py`)
- Agent Session → Python Sandbox: runs Python (evidence: `src/flog/agent/session.py`)
- Agent Session → Plugin Registry: executes plugin (evidence: `README.md`)
- RPC Tools → Quanti Solver: runs interpretation
- Plot View → Plot Export: exports plot
- Quanti Solver → Petrophysics: uses kernels
