Loading page
About this tool
Answer a few questions to choose between git merge and rebase, submodule and subtree, monorepo and polyrepo, API keys and OAuth, edge and origin, pub/sub and queues, Poetry and pip, or the right semver bump.
Pick the decision, answer the questions about your project and get a recommendation with the trade-offs. This page brings together 8 separate architecture decision helper pages (API key vs OAuth, Edge vs origin, Git merge vs rebase, Git submodule vs subtree, Monorepo vs polyrepo, Poetry vs pip, Pub/Sub vs queue, Semver bump) so you can compare them without hunting for the right one.
Open Architecture Decision Helper on AltFTool — it loads instantly in your browser.
Choose your decision at the top: API key vs OAuth, Edge vs origin, Git merge vs rebase, Git submodule vs subtree and 4 more. On a phone it is a drop-down list.
Fill in the architecture decision helper for that decision; each of the 8 options keeps its own rules, data and defaults.
Read the result, then switch decision to compare. The page link keeps your decision (?v=api-key-vs-oauth), so you can bookmark or share it.
API key vs OAuth, Edge vs origin, Git merge vs rebase and the rest sit behind one picker, so switching decision takes a tap instead of a new search.
Every decision keeps its own rules, numbers and defaults rather than one generic template.
The link remembers the decision you picked, so a bookmark or a shared link opens straight on it.
8: API key vs OAuth, Edge vs origin, Git merge vs rebase, Git submodule vs subtree, Monorepo vs polyrepo, Poetry vs pip, Pub/Sub vs queue, Semver bump. Pick one at the top of the tool; the page link updates (for example ?v=api-key-vs-oauth) so you can bookmark or share that exact view.
When the caller is your own or a named partner's backend, there is no end user to represent, the key can be scoped and rotated automatically, and the data is not highly sensitive. The moment one end user must be able to revoke access without affecting others, a key cannot express that — revoking it disconnects every user of that integration at once.
When it can answer without crossing back to the origin region — static or cached content, redirects, auth-token checks against replicated data, geolocation logic. If every request still makes an uncached call to a single-region database, the edge adds a hop instead of removing one and is often slower.
Rebase when the branch is private — not yet pushed, or pushed but not pulled by anyone — and you want a linear history. Rebase rewrites your commits with new SHAs as it replays them onto the target, which is harmless for unpublished work and destructive for shared work; that boundary is the whole decision.
A submodule stores a pointer to an exact commit of another repository, checked out into a nested directory — the code is not in your repo. A subtree copies the other repository's files (and optionally history) into a subdirectory of your repo, so a plain git clone contains everything. Submodules pin precisely but demand submodule-aware workflows; subtrees are invisible to consumers but duplicate content.
When projects share significant code, one change regularly needs to land atomically across several projects, and you can invest in affected-only CI tooling like Nx, Turborepo or Bazel. Those three conditions are why Google and Meta run monorepos — without them, a monorepo is mostly a very large folder with slow CI.
For most new projects uv is the stronger default: its Rust resolver installs 10-100x faster than pip in Astral's published benchmarks, it writes a single cross-platform uv.lock, manages Python interpreter versions itself, and has first-class workspaces. Poetry remains an excellent choice for libraries, where its mature poetry build and poetry publish flow has years of production use.
A queue delivers each message to exactly one consumer, so adding workers spreads the load; pub/sub delivers a copy to every subscriber, so adding subscribers multiplies the work. Queues suit task distribution, pub/sub suits notification. If you find yourself creating one queue per consumer, you wanted pub/sub.
Whenever you make any backwards-incompatible change to the public API — removing or renaming exports, changing documented behaviour or types, or raising platform requirements. SemVer 2.0.0 item 8 makes this mandatory even for tiny breaking changes; the size of the change is irrelevant, only its compatibility.