{"canonical_url":"https://engineer.company/glossary/codebase/","content_markdown":"# Codebase\n\n## What it is\n\nA codebase, sometimes written as two words, code base, is the whole body of\nsource that a team edits, reviews and ships as one thing. When engineers say\n“the codebase”, they mean the place where every change to an application lands:\nthe code itself, its tests, the scripts that build and check it, the database\nchanges, and the documents that explain how the pieces fit.\n\nThe [Twelve-Factor App](https://12factor.net/), a methodology for building web\nservices, gives the most useful working definition, because it makes the\nboundary something you can test. In a centralised version control system such as\nSubversion, a codebase is one repository. In a distributed system such as Git,\nit is any set of repositories that share a root commit, the first commit in the\nhistory, the one with no parent. Two repositories that grew from the same first\ncommit are one codebase, however far apart they have drifted. Two that started\nseparately are two codebases, even if they hold nearly identical files.\n\nThe same document pairs that definition with a second rule: one codebase, many\ndeploys. Each deploy is one running instance of the application, and there are\nusually several at once. Production is one, staging another, and every\ndeveloper’s local copy counts as well. They all run the same codebase, often at\ndifferent commits: a developer has work staging has not seen, and staging has\nwork production has not seen.\n\nWhat belongs inside follows from that. The source and everything needed to turn\nit into a working program belong there, including a manifest that names each\ndependency and its version. The dependencies themselves usually stay outside,\nfetched by a package manager. Values that change from one deploy to the next\nstay outside too, and above all credentials: a password committed once travels\nwith every copy of the history afterwards.\n\nA codebase can hold several programs. A monorepo keeps a frontend, an API and\nthe database code side by side in one repository, so a single commit can change\nall three. By the root-commit rule that is still one codebase. The opposite\nchoice spreads an application across repositories with separate histories, and\nthen each repository is its own codebase. Twelve-factor is blunt about the\nresult: if there are several codebases, it is a distributed system, and each\ncomponent is an app in its own right.\n\n## Why it matters\n\nThe boundary decides what can change together. Inside one codebase, a change to\nan API and the screen that calls it can be written, reviewed and merged as one\nunit. Across two codebases the same change becomes two pull requests, two\nreleases and a period in which one side is ahead of the other. Both are\nworkable; the price is set by where the line was drawn.\n\nThe codebase is also the unit that standards run over. A test suite, a linter, a\nformatter, a commit message rule and a task runner all take “the codebase” as\ntheir scope, and whatever sits outside it is checked by none of them.\n\nEarly decisions harden in a codebase faster than anywhere else. Every line\nwritten after a choice assumes that choice, so a layering rule or a quality bar\nset in the first weeks becomes the shape of everything that follows, and\nreversing it later means rewriting the code that grew around it.\n\nFor people, a codebase is the thing a newcomer receives. If it holds everything\nneeded to build, test and run the application, one clone and one command get\nthem started. If the knowledge lives partly in the code and partly in someone’s\nmemory, the first week goes on finding out which is which.\n\n## What it looks like in practice\n\nGo, TypeScript, SQL, Python and shell share one platform's repository, where\n[the codebase is a polyglot monorepo](/portfolio/authored-578-go-task-automation-targets/)\nand each language arrives with its own way to build, test and lint. The answer\nwas a single entry point: a go-task layer that grew to 578 named targets, 50 in\nthe root file and 528 in namespaced files beneath it, covering native, Docker\nand HTTPS development modes, code quality, database management and deployment.\nAnyone can run `task --list` and see the whole toolchain. The number is also a\nwarning: 578 targets is past what anyone can hold in their head, so the naming\nand the namespacing are what keep it usable.\n\nAnother project began with an empty repository on 25 November 2025, and\n[three decisions made in its first weeks](/portfolio/set-the-platforms-founding-technical-decisions/)\nstill held nine months and several thousand commits later: a layered stack, data\naccess behind stored functions, and a zero-warnings bar put in before there was\nmuch code to hold to it. The reasoning behind that last one is the heart of this\narticle: a standard introduced at commit 5,000 is a cleanup project, whereas the\nsame standard at commit 50 is just how the repository works.\n\nThe walls inside a codebase can be the design itself. In the founder's\n[architecture contribution under NextMariner](/portfolio/a-maritime-platform-built-in-clean-layers/),\na maritime platform built in three layers, the Next.js frontend handles\npresentation and nothing else, a deliberately thin Go API built with Huma over\nFiber routes, validates and orchestrates, and the business logic lives in\nPostgreSQL functions. When a rule changes, it changes in one layer, in SQL. The\nboundaries were written down and enforced in review, because a convention\nnobody polices stops being one.\n\nThis site’s own codebase draws a different kind of line. Its project pages are\nwritten in a separate repository, exported into this one by a script and\ncommitted, so the site builds on its own. Inside this codebase those pages are\ngenerated files, and the instructions for working here say they are never edited\nby hand.\n\n## Where it goes wrong\n\n### Copied code drifts apart\n\nTwo applications need the same helper, and the fastest move is to copy it\nacross. A year later there are two versions with different fixes, and a bug\npatched in one is still live in the other. Twelve-factor calls several apps\nsharing the same code a violation and names the fix: move the shared part into a\nlibrary, pull it in through the dependency manager, and let each codebase state\nthe version it uses.\n\n### A secret lands in the history\n\nA connection string or an API key gets committed in a configuration file, and\nfrom then on it sits in the history that every clone carries, even after a later\ncommit deletes the line. The twelve-factor test is worth running before each\ncommit: could this codebase be published as open source today without exposing a\nsingle credential? Anything that would fail that test belongs in the environment\nof each deploy.\n\n### A generated file gets a hand edit\n\nA file written by a script looks like any other source file, so someone fixes a\ntypo in it directly. The next run of the script writes the old text back and the\nfix vanishes without a word. Mark generated paths clearly, keep the generator as\ntheir only writer, and send every correction to the generator’s input.\n\n### Internal walls wear thin\n\nUnder a deadline, a query goes straight into a request handler because it is the\nshortest path, and the layering the project started with stops describing the\ncode. Each shortcut is small. Together they turn a two-line change into one that\ntouches every layer. A written rule helps, review helps more, and a check that\nfails the build when one layer reaches into another helps most.\n\n### A standard covers half the code\n\nA linter set up for the frontend leaves the shell scripts and the SQL alone, and\nthose files collect exactly the problems the linter was meant to stop. A\ncodebase-wide bar has to name every language in the codebase, which is the\nhidden price of a polyglot repository.\n\n### A fork starts a second product\n\nA team copies a repository to start a related product. Both copies keep the same\nroot commit, so by the twelve-factor rule they are still one codebase, now\nserving two apps, and the drift described above begins at the scale of a whole\nrepository. Comparing root commits shows which situation you are in:\n\n```sh\ngit -C app-a rev-list --max-parents=0 HEAD\ngit -C app-b rev-list --max-parents=0 HEAD\n```\n\nIdentical output means a shared root and a shared codebase; different output\nmeans two separate histories.\n\n## Further reading\n\n- [I. Codebase](https://12factor.net/codebase) — the one-codebase, many-deploys\n  rule and the shared-root-commit test behind it.\n- [II. Dependencies](https://12factor.net/dependencies) — declaring every\n  dependency in a manifest and isolating it, so a codebase states exactly what\n  it pulls in.\n- [III. Config](https://12factor.net/config) — the open-source litmus test for\n  what has to stay out of a codebase.\n- [gitsubmodules](https://git-scm.com/docs/gitsubmodules) — how Git embeds one\n  repository in another while each keeps its own history.\n- [git-rev-list](https://git-scm.com/docs/git-rev-list) — the reference for\n  listing commits, including the root commits of a history.\n\n\u003chttps://engineer.company/glossary/codebase/\u003e\n","date_modified":"2026-11-08T02:22:23Z","description":"Where one codebase ends and the next begins, what belongs inside one, and how a codebase quietly splits apart or fills up with things it should not hold.","formats":{"gemtext":"https://engineer.company/glossary/codebase/index.gmi","gopher":"https://engineer.company/glossary/codebase/gophermap","html":"https://engineer.company/glossary/codebase/","json":"https://engineer.company/glossary/codebase/index.json","markdown":"https://engineer.company/glossary/codebase/index.md","pdf":"https://engineer.company/glossary/codebase/index.pdf"},"kind":"page","language":"en","title":"What is a codebase?","url":"https://engineer.company/glossary/codebase/","version":1}