# connorferster/handcalcs architecture

> Architecture diagram of the GitHub repository connorferster/handcalcs, 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/connorferster/handcalcs
- Repository: https://github.com/connorferster/handcalcs

## Overview

handcalcs turns executed Python calculations into hand-formatted LaTeX, primarily through Jupyter cell magics or a function decorator. Both paths gather calculation source and computed values, then use the LaTeX renderer to classify and format expressions; Jupyter displays the result while the decorator returns rendered text with values. The package also supports SymPy cell conversion, configurable rendering, and an HTML exporter. The core rendering internals are sampled only in part, so the graph keeps their stages together rather than asserting unverified helper-to-helper calls.

Main entry points: [`src/handcalcs/render.py`](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/render.py) (Cell magics), [`src/handcalcs/decorator.py`](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/decorator.py) (Function decorator), [`src/handcalcs/handcalcs.py`](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/handcalcs.py) (LaTeX renderer), [`src/handcalcs/handcalcs_html/__init__.py`](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/handcalcs_html/__init__.py) (HTML exporter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_magics["Cell magics<br/>[render.py]"]
  node_decorator["Function decorator<br/>[decorator.py]"]
  node_scope["Scope capture<br/>[decorator.py]"]
  node_sympy["SymPy conversion<br/>[sympy_kit.py]"]
end

subgraph group_rendering["Calculation rendering"]
  node_renderer["LaTeX renderer<br/>[handcalcs.py]"]
  node_classify["Cell classification<br/>[handcalcs.py]"]
  node_latex_format["LaTeX formatting<br/>[handcalcs.py]"]
end

subgraph group_options["Configuration"]
  node_config_api["Config API<br/>[global_config.py]"]
  node_config_data["Config defaults<br/>[config.json]"]
end

subgraph group_export["Export and integrations"]
  node_html_exporter["HTML exporter<br/>[__init__.py]"]
  node_html_templates["HTML templates"]
end

node_user(("Notebook user"))
node_python_user(("Python caller"))
node_ipython["IPython"]
node_nbconvert["nbconvert"]
node_latex_output["LaTeX output"]

node_user -->|"runs magic"| node_magics
node_magics -->|"executes cell"| node_ipython
node_magics -.->|"converts SymPy"| node_sympy
node_magics -->|"renders source and values"| node_renderer
node_renderer -->|"classifies cell"| node_classify
node_classify -->|"formats lines"| node_latex_format
node_latex_format -->|"produces LaTeX"| node_latex_output
node_magics -->|"displays or prints"| node_latex_output
node_python_user -->|"calls function"| node_decorator
node_decorator -->|"captures values"| node_scope
node_decorator -->|"renders source and scope"| node_renderer
node_config_api -->|"saves options"| node_config_data
node_html_exporter -->|"extends exporter"| node_nbconvert
node_html_exporter -->|"loads templates"| node_html_templates

click node_magics "https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/render.py"
click node_decorator "https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/decorator.py"
click node_scope "https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/decorator.py"
click node_sympy "https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/sympy_kit.py"
click node_renderer "https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/handcalcs.py"
click node_classify "https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/handcalcs.py"
click node_latex_format "https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/handcalcs.py"
click node_config_api "https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/global_config.py"
click node_config_data "https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/config.json"
click node_html_exporter "https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/handcalcs_html/__init__.py"
click node_html_templates "https://github.com/connorferster/handcalcs/tree/main/src/handcalcs/handcalcs_html/classic"

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_magics,node_decorator,node_scope,node_sympy,node_user toneBlue
class node_renderer,node_classify,node_latex_format toneAmber
class node_config_api,node_config_data toneMint
class node_html_exporter,node_html_templates toneRose
class node_python_user,node_ipython,node_nbconvert,node_latex_output toneIndigo
```

## Components

### User interfaces

- [Cell magics](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/render.py): `src/handcalcs/render.py`
- [Function decorator](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/decorator.py): `src/handcalcs/decorator.py`
- [Scope capture](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/decorator.py): `src/handcalcs/decorator.py`
- [SymPy conversion](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/sympy_kit.py): `src/handcalcs/sympy_kit.py`

### Calculation rendering

- [LaTeX renderer](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/handcalcs.py): `src/handcalcs/handcalcs.py`
- [Cell classification](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/handcalcs.py): `src/handcalcs/handcalcs.py`
- [LaTeX formatting](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/handcalcs.py): `src/handcalcs/handcalcs.py`

### Configuration

- [Config API](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/global_config.py): `src/handcalcs/global_config.py`
- [Config defaults](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/config.json): `src/handcalcs/config.json`

### Export and integrations

- [HTML exporter](https://github.com/connorferster/handcalcs/blob/main/src/handcalcs/handcalcs_html/__init__.py): `src/handcalcs/handcalcs_html/__init__.py`
- [HTML templates](https://github.com/connorferster/handcalcs/tree/main/src/handcalcs/handcalcs_html/classic): `src/handcalcs/handcalcs_html/classic`

### Other components

- **Notebook user**
- **Python caller**
- **IPython**
- **nbconvert**
- **LaTeX output**

## Connections

- Notebook user → Cell magics: runs magic
- Cell magics → IPython: executes cell
- Cell magics → SymPy conversion: converts SymPy
- Cell magics → LaTeX renderer: renders source and values
- LaTeX renderer → Cell classification: classifies cell
- Cell classification → LaTeX formatting: formats lines
- LaTeX formatting → LaTeX output: produces LaTeX
- Cell magics → LaTeX output: displays or prints
- Python caller → Function decorator: calls function
- Function decorator → Scope capture: captures values
- Function decorator → LaTeX renderer: renders source and scope
- Config API → Config defaults: saves options
- HTML exporter → nbconvert: extends exporter
- HTML exporter → HTML templates: loads templates