# clbiggs/reloading architecture

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

- Interactive diagram: https://gitdiagram.com/clbiggs/reloading
- Repository: https://github.com/clbiggs/reloading

## Overview

1. **Overall shape**
   - This is a single-process Flask monolith for reloading data management.
   - The app is server-rendered: request handlers return Jinja2 templates, not a JSON API.
   - Deployment is containerized as one Docker service with persistent SQLite storage.

2. **Core runtime boundary**
   - `src/app.py` is the Flask application entry point/factory.
   - `src/database.py` initializes the database layer.
   - `src/models.py` defines the SQLAlchemy domain model, which is the main shared schema across the app.

3. **Primary domain subsystems**
   - The application is organized around reloading entities: calibers, primer types, manufacturers, bullets, primers, casings, powders.
   - These are managed through separate CRUD blueprints under `src/routes/`, each with corresponding list/form templates.
   - `order_lots`, `loads`, `firearms`, and `test_sessions` are the higher-level operational subsystems built from those base entities.

4. **Data relationships**
   - Component reference data feeds into lot tracking and recipe building.
   - Order lots capture purchase details such as lot number, cost, and quantity for bullets/powder/primers.
   - Loads link together the chosen component lots and load measurements.
   - Firearms provide a contextual anchor for loads and chronograph test sessions.

5. **Chronograph import flow**
   - `src/routes/upload.py` handles `.xlsx` import from Velocity Pro Radar Chronograph exports.
   - `src/utils/chronograph_parser.py` extracts weather, shot data, and trace indicators from those spreadsheets.
   - Imported data is used to create or populate `test_sessions`, which then become visible through the test session views.

6. **Test session and summary layer**
   - `test_sessions` stores session-level metadata, shot groups, individual velocities, and associated conditions.
   - `src/utils/calculations.py` supports computed metrics such as derived statistics and density altitude.
   - `summaries` provides aggregate/read-only views grouped by bullet, firearm, or powder, so it acts as the reporting boundary of the app.

7. **Presentation layer**
   - All user-facing pages live in `src/templates/`, organized by feature area.
   - `base.html` and `macros.html` provide shared layout and reusable UI fragments.
   - The UI is Bootstrap 5-based with a dark theme and responsive layout for desktop/mobile browsers.

8. **Feature-to-template mapping**
   - Most feature directories contain an `index.html` for listing and a `form.html` for create/edit flows.
   - Some entities have detail pages such as `loads/view.html`, `order_lots/view.html`, and `test_sessions/view.html`.
   - This reflects a classic CRUD architecture with a few richer detail/report pages.

9. **Infrastructure and persistence**
   - Data persists in SQLite at `/data/reloading.db`, which is mounted from a Docker volume.
   - `docker-compose.yml` is the recommended runtime wrapper, while `Dockerfile` packages the app for standalone deployment.
   - The README indicates Gunicorn is the production server inside the container.

10. **Repo-local supporting assets**
    - `sample_data/chronograph_exports/` contains example Excel files for exercising the import path.
    - Tooling files such as `.prettierignore`, `cspell.json`, and `.gitattributes` suggest basic repo hygiene, but they do not materially change the runtime architecture.

Main entry points: [`src/routes/__init__.py`](https://github.com/clbiggs/reloading/blob/main/src/routes/__init__.py) (Routes), [`src/app.py`](https://github.com/clbiggs/reloading/blob/main/src/app.py) (App), [`src/routes/summaries.py`](https://github.com/clbiggs/reloading/blob/main/src/routes/summaries.py) (Summaries), [`src/routes/test_sessions.py`](https://github.com/clbiggs/reloading/blob/main/src/routes/test_sessions.py) (Test Sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app["App<br/>flask entrypoint<br/>[app.py]"]
  node_database[("Database<br/>sqlite init<br/>[database.py]")]
  node_models["Models<br/>sqlalchemy schema<br/>[models.py]"]
  node_routes_init["Routes<br/>blueprint registry<br/>[__init__.py]"]
end

subgraph group_domain["Domain"]
  node_calibers["Calibers<br/>crud blueprint<br/>[calibers.py]"]
  node_primer_types["Primer Types<br/>crud blueprint<br/>[primer_types.py]"]
  node_manufacturers["Manufacturers<br/>crud blueprint<br/>[manufacturers.py]"]
  node_bullets["Bullets<br/>crud blueprint<br/>[bullets.py]"]
  node_primers["Primers<br/>crud blueprint<br/>[primers.py]"]
  node_casings["Casings<br/>crud blueprint<br/>[casings.py]"]
  node_powders["Powders<br/>crud blueprint<br/>[powders.py]"]
  node_order_lots["Order Lots<br/>inventory blueprint<br/>[order_lots.py]"]
  node_loads["Loads<br/>load recipe blueprint<br/>[loads.py]"]
  node_firearms["Firearms<br/>context blueprint<br/>[firearms.py]"]
  node_test_sessions["Test Sessions<br/>chronograph blueprint<br/>[test_sessions.py]"]
  node_upload["Upload<br/>xlsx import<br/>[upload.py]"]
  node_summaries["Summaries<br/>reporting blueprint<br/>[summaries.py]"]
  node_calculations["Calculations<br/>metrics utils<br/>[calculations.py]"]
  node_chronograph_parser["Parser"]
end

subgraph group_presentation["Templates"]
  node_base_template["Base UI<br/>shared template<br/>[base.html]"]
  node_macros_template["Macros<br/>shared template<br/>[macros.html]"]
  node_summary_templates["Summary Views<br/>report templates<br/>[index.html]"]
end

subgraph group_ops["Deployment"]
  node_deployment["Docker<br/>container runtime"]
  node_compose["Compose<br/>service config<br/>[docker-compose.yml]"]
end

node_app -->|"initializes"| node_database
node_app -->|"uses"| node_models
node_app -->|"registers"| node_routes_init
node_routes_init -->|"includes"| node_calibers
node_routes_init -->|"includes"| node_primer_types
node_routes_init -->|"includes"| node_manufacturers
node_routes_init -->|"includes"| node_bullets
node_routes_init -->|"includes"| node_primers
node_routes_init -->|"includes"| node_casings
node_routes_init -->|"includes"| node_powders
node_routes_init -->|"includes"| node_order_lots
node_routes_init -->|"includes"| node_loads
node_routes_init -->|"includes"| node_firearms
node_routes_init -->|"includes"| node_test_sessions
node_routes_init -->|"includes"| node_upload
node_routes_init -->|"includes"| node_summaries
node_order_lots -->|"feeds"| node_loads
node_firearms -->|"anchors"| node_loads
node_upload -->|"parses"| node_chronograph_parser
node_chronograph_parser -->|"populates"| node_test_sessions
node_test_sessions -->|"computes"| node_calculations
node_summaries -->|"aggregates"| node_calculations
node_app -->|"renders"| node_base_template
node_app -->|"reuses"| node_macros_template
node_summaries -->|"renders"| node_summary_templates
node_deployment -->|"orchestrates"| node_compose
node_compose -->|"mounts"| node_database

click node_app "https://github.com/clbiggs/reloading/blob/main/src/app.py"
click node_database "https://github.com/clbiggs/reloading/blob/main/src/database.py"
click node_models "https://github.com/clbiggs/reloading/blob/main/src/models.py"
click node_routes_init "https://github.com/clbiggs/reloading/blob/main/src/routes/__init__.py"
click node_calibers "https://github.com/clbiggs/reloading/blob/main/src/routes/calibers.py"
click node_primer_types "https://github.com/clbiggs/reloading/blob/main/src/routes/primer_types.py"
click node_manufacturers "https://github.com/clbiggs/reloading/blob/main/src/routes/manufacturers.py"
click node_bullets "https://github.com/clbiggs/reloading/blob/main/src/routes/bullets.py"
click node_primers "https://github.com/clbiggs/reloading/blob/main/src/routes/primers.py"
click node_casings "https://github.com/clbiggs/reloading/blob/main/src/routes/casings.py"
click node_powders "https://github.com/clbiggs/reloading/blob/main/src/routes/powders.py"
click node_order_lots "https://github.com/clbiggs/reloading/blob/main/src/routes/order_lots.py"
click node_loads "https://github.com/clbiggs/reloading/blob/main/src/routes/loads.py"
click node_firearms "https://github.com/clbiggs/reloading/blob/main/src/routes/firearms.py"
click node_test_sessions "https://github.com/clbiggs/reloading/blob/main/src/routes/test_sessions.py"
click node_upload "https://github.com/clbiggs/reloading/blob/main/src/routes/upload.py"
click node_summaries "https://github.com/clbiggs/reloading/blob/main/src/routes/summaries.py"
click node_calculations "https://github.com/clbiggs/reloading/blob/main/src/utils/calculations.py"
click node_chronograph_parser "https://github.com/clbiggs/reloading/blob/main/src/utils/chronograph_parser.py"
click node_base_template "https://github.com/clbiggs/reloading/blob/main/src/templates/base.html"
click node_macros_template "https://github.com/clbiggs/reloading/blob/main/src/templates/macros.html"
click node_summary_templates "https://github.com/clbiggs/reloading/blob/main/src/templates/summaries/index.html"
click node_deployment "https://github.com/clbiggs/reloading/tree/main/Dockerfile"
click node_compose "https://github.com/clbiggs/reloading/blob/main/docker-compose.yml"

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_app,node_database,node_models,node_routes_init toneBlue
class node_calibers,node_primer_types,node_manufacturers,node_bullets,node_primers,node_casings,node_powders,node_order_lots,node_loads,node_firearms,node_test_sessions,node_upload,node_summaries,node_calculations,node_chronograph_parser toneAmber
class node_base_template,node_macros_template,node_summary_templates toneMint
class node_deployment,node_compose toneRose
```

## Components

### Runtime

Flask app, database, and shared domain schema

- [App](https://github.com/clbiggs/reloading/blob/main/src/app.py): flask entrypoint · Flask application factory and request wiring · `src/app.py`
- [Database](https://github.com/clbiggs/reloading/blob/main/src/database.py): sqlite init · Database initialization and connection setup · `src/database.py`
- [Models](https://github.com/clbiggs/reloading/blob/main/src/models.py): sqlalchemy schema · Shared domain model used across the app · `src/models.py`
- [Routes](https://github.com/clbiggs/reloading/blob/main/src/routes/__init__.py): blueprint registry · Route package that assembles feature blueprints · `src/routes/__init__.py`

### Domain

CRUD and operational reloading features

- [Calibers](https://github.com/clbiggs/reloading/blob/main/src/routes/calibers.py): crud blueprint · Reference data for cartridge calibers · `src/routes/calibers.py`
- [Primer Types](https://github.com/clbiggs/reloading/blob/main/src/routes/primer_types.py): crud blueprint · Reference data for primer categories · `src/routes/primer_types.py`
- [Manufacturers](https://github.com/clbiggs/reloading/blob/main/src/routes/manufacturers.py): crud blueprint · Manufacturer reference management · `src/routes/manufacturers.py`
- [Bullets](https://github.com/clbiggs/reloading/blob/main/src/routes/bullets.py): crud blueprint · Bullet reference management · `src/routes/bullets.py`
- [Primers](https://github.com/clbiggs/reloading/blob/main/src/routes/primers.py): crud blueprint · Primer reference management · `src/routes/primers.py`
- [Casings](https://github.com/clbiggs/reloading/blob/main/src/routes/casings.py): crud blueprint · Casing reference management · `src/routes/casings.py`
- [Powders](https://github.com/clbiggs/reloading/blob/main/src/routes/powders.py): crud blueprint · Powder reference management · `src/routes/powders.py`
- [Order Lots](https://github.com/clbiggs/reloading/blob/main/src/routes/order_lots.py): inventory blueprint · Purchase lots with cost, quantity, and lot tracking · `src/routes/order_lots.py`
- [Loads](https://github.com/clbiggs/reloading/blob/main/src/routes/loads.py): load recipe blueprint · Load recipes built from component lots and measurements · `src/routes/loads.py`
- [Firearms](https://github.com/clbiggs/reloading/blob/main/src/routes/firearms.py): context blueprint · Firearm records used to anchor loads and tests · `src/routes/firearms.py`
- [Test Sessions](https://github.com/clbiggs/reloading/blob/main/src/routes/test_sessions.py): chronograph blueprint · Chronograph sessions, shots, velocities, and conditions · `src/routes/test_sessions.py`
- [Upload](https://github.com/clbiggs/reloading/blob/main/src/routes/upload.py): xlsx import · Velocity Pro Radar Chronograph spreadsheet import flow · `src/routes/upload.py`
- [Summaries](https://github.com/clbiggs/reloading/blob/main/src/routes/summaries.py): reporting blueprint · Read-only aggregation views by bullet, firearm, and powder · `src/routes/summaries.py`
- [Calculations](https://github.com/clbiggs/reloading/blob/main/src/utils/calculations.py): metrics utils · Derived metrics such as statistics and density altitude · `src/utils/calculations.py`
- [Parser](https://github.com/clbiggs/reloading/blob/main/src/utils/chronograph_parser.py): xlsx parser · Extracts weather, shot data, and trace indicators from exports · `src/utils/chronograph_parser.py`

### Templates

Server-rendered UI by feature area

- [Base UI](https://github.com/clbiggs/reloading/blob/main/src/templates/base.html): shared template · Shared layout for all pages · `src/templates/base.html`
- [Macros](https://github.com/clbiggs/reloading/blob/main/src/templates/macros.html): shared template · Reusable UI fragments and helpers · `src/templates/macros.html`
- [Summary Views](https://github.com/clbiggs/reloading/blob/main/src/templates/summaries/index.html): report templates · Aggregate report pages by bullet, firearm, and powder · `src/templates/summaries/index.html`

### Deployment

Containerization and persistent storage

- [Docker](https://github.com/clbiggs/reloading/tree/main/Dockerfile): container runtime · Containerized deployment with Gunicorn and mounted SQLite storage · `Dockerfile`
- [Compose](https://github.com/clbiggs/reloading/blob/main/docker-compose.yml): service config · Recommended runtime wrapper and persistent volume wiring · `docker-compose.yml`

## Connections

- App → Database: initializes · The Flask app sets up the database layer
- App → Models: uses · Request handlers share the SQLAlchemy model schema
- App → Routes: registers · The application loads the blueprint package
- Routes → Calibers: includes · Blueprint registry exposes the caliber CRUD route
- Routes → Primer Types: includes · Blueprint registry exposes the primer type CRUD route
- Routes → Manufacturers: includes · Blueprint registry exposes the manufacturer CRUD route
- Routes → Bullets: includes · Blueprint registry exposes the bullet CRUD route
- Routes → Primers: includes · Blueprint registry exposes the primer CRUD route
- Routes → Casings: includes · Blueprint registry exposes the casing CRUD route
- Routes → Powders: includes · Blueprint registry exposes the powder CRUD route
- Routes → Order Lots: includes · Blueprint registry exposes inventory lot tracking
- Routes → Loads: includes · Blueprint registry exposes load recipes
- Routes → Firearms: includes · Blueprint registry exposes firearm records
- Routes → Test Sessions: includes · Blueprint registry exposes chronograph sessions
- Routes → Upload: includes · Blueprint registry exposes spreadsheet import
- Routes → Summaries: includes · Blueprint registry exposes reporting views
- Order Lots → Loads: feeds · Purchased lots supply the load-building workflow
- Firearms → Loads: anchors · Firearm records contextualize loads
- Upload → Parser: parses · Upload flow delegates spreadsheet extraction
- Parser → Test Sessions: populates · Imported session data becomes test session records
- Test Sessions → Calculations: computes · Session views rely on derived metrics
- Summaries → Calculations: aggregates · Reports reuse calculation helpers for rollups
- App → Base UI: renders · Pages inherit the shared base layout
- App → Macros: reuses · UI fragments are shared across templates
- Summaries → Summary Views: renders · Reporting blueprint serves summary pages
- Docker → Compose: orchestrates · Compose wraps the containerized service
- Compose → Database: mounts · Persistent SQLite storage is mounted into the container
