design decisions from scratch

Published 2026-01-24T19:47:00Z by Physics Derivation Graph

Currently https://allofphysics.com/design_documentation is sparse. This post is draft content to expand that page. This page will be deleted after content is moved to allofphyics.com repo.

Restating the goal from https://allofphysics.com/,

Goal: Write down all known mathematical physics in a way that can be both read by humans and checked by a computer algebra system.

Decision: what constitutes "all known mathematical physics"?

Dirac notation, calculus, differential equations, algebra, trigonometry.
Not geometry.

Decision: what does "human-readable" mean?

Reasonable for a human to understand without use of specialized knowledge.
\int_0^{\infty} is out of scope, so is contentML

Decision: what does "checkable by CAS" mean?

Just writing down symbols and expressions is not meaningful.

Decision: which Computer Algebra System(s) to use?

https://github.com/allofphysicsgraph/task-tracker/issues/117

Mathematica, MathCad, Sage

Decision: which proof assistant(s) to use?

https://github.com/allofphysicsgraph/task-tracker/issues/106

COQ, Isabelle, Lean

Decision: how to represent expressions?

Latex, Content MathML, Presentation ML, Mathematica,

Decision: How to render graphs visually?

https://github.com/allofphysicsgraph/task-tracker/issues/97

d3js, graphviz, networkx

Decision: Which Property Graph database?

https://github.com/allofphysicsgraph/task-tracker/issues/43

Decision: upgrade path from JSON/SQL to Neo4j

I had ui_v7 for JSON/SQL and ui_v8 for Neo4j. The ui_v7 had a working implementation of Google authentication. I had trouble getting Google authentication working in ui_v8, and I didn't want to have to refactor all the static content from ui_v7, so I decided to create a new repo, "allofphysics.com".

Although getting Neo4j into ui_v7 was do-able, the "mash together to repos" ended up being a bad decision from a troubleshooting and cleanliness-of-design experience.

Decision: naming of repo

I decided to name the repo "allofphysics.com" to make it clear which repo hosted the website on the Internet. Also, the alternative repo name "a mashup of v7 and v8" wasn't a good name, though it would have been more descriptive.

In retrospect, that was a bad naming convention because I later reverted to using ui_v7 for the website.

Decision: page scope

Rendered HTML pages should have a single scope. (As opposed to a single-page website.)

Decision: Which VPS provider service company to use?

DigitalOcean, AWS, Oracle, Azure

https://github.com/allofphysicsgraph/task-tracker/issues/56

https://physicsderivationgraph.blogspot.com/2026/01/vps-price-comparison-september-2024.html
https://physicsderivationgraph.blogspot.com/2026/01/vps-price-comparison-january-2026.html

Decision: separate non-interactive workflow pages (e.g., user_documentation) into a separate Python file

Having all the routes in a single file (e.g., pdg_app.py) results in a huge file with thousands of lines.

Happily, Flask provides a way to separate routes into separate files (e.g., pdg_other_routes.py) using blueprints.

The file pdg_app.py contains

from pdg_other_routes import other_routes_bp
web_app.register_blueprint(other_routes_bp)

and then pdg_other_routes.py contains

other_routes_bp = Blueprint("other_routes", __name__)

@other_routes_bp.route("/api_via_js")
def to_api_via_js() -> str:
    return render_template("js_with_api/api_js.html")

So far, so good. The cost of this separation is that Flask namespaces the endpoints to ensure there are no name collisions between different files. The url_for function in Jinja2 templates (and in the Python code) now expects the format:

other_routes.function_name

That would require figuring out which url_for functions point to routes in pdg_other_routes.py and which routes are in pdg_app.py

Therefore, having all routes in pdg_app.py is easiest.

Decision: Which languages to use?

Languages I'm comfortable with and are widely used - Python; HTML; Docker

Decision: Interface

Why web ui? Why not a GUI? Or command line?

Accessibility