Project Architecture & Tech Stack Markdown Table Template
A tech stack table explains what a project is built from and, more importantly, why each piece is there. In a README it replaces the wall of logos with something a reader can act on. In an onboarding doc it tells a new engineer which frameworks to learn first. In technical due diligence it is often the first artefact an acquirer, auditor, or security reviewer asks for, because it shows at a glance which licences, vendors, and runtimes the business depends on.
Edit This Template
Edit cells, add rows, or sort — the Markdown updates livePaste cells from Excel or Google Sheets into the first header to replace the table · Tab / Enter / arrows move · Shift+F10 opens row & column actions
When to Use This Table
Each column serves a different reader. Engineers read Technology and Version to know whether the docs they are about to search for match the code. Legal and procurement read License, because an AGPL-3.0 dependency or a vendor’s proprietary terms change what the company may do with its product. Platform teams read versions to plan upgrades before a runtime falls out of support. Architectural Purpose is for everyone, and it is the column that stops a later team from removing a library without understanding the job it did.
A good stack table is selective and current. It lists the components that would take real effort to replace, gives versions that match the lockfile, uses standard licence identifiers, and states a reason for each choice. A weak one dumps every entry from package.json, carries versions from the day the project started, and fills the purpose column with adjectives. Selectivity matters more than completeness here; the full dependency inventory belongs in a generated SBOM, not a hand-maintained table.
What Goes in Each Column
| Column | Alignment | What to put here |
|---|---|---|
| Tier / Layer | left :--- | A short architectural grouping from a fixed vocabulary — Frontend, API, Data, Infrastructure, Observability, Tooling — so rows can be sorted and compared across projects. Order tiers along the path a request takes, from the browser to storage, and keep rows within a tier together. |
| Technology | left :--- | The product’s official name and capitalisation (PostgreSQL, not “Postgres DB”), linked to its homepage or docs as [Next.js](https://nextjs.org/). Add the mode when it changes how the tool behaves, such as App Router versus Pages Router, or static export versus server rendering. |
| Version | center :---: | The version the lockfile actually resolves, centered. A README can use the major line (15.x) so it does not go stale weekly; an audit needs the exact version. For managed services with no installable version, write Managed or the API version you call, rather than leaving the cell empty. |
| License | center :---: | The SPDX identifier from the project’s own LICENSE file: MIT, Apache-2.0, ISC, BSD-3-Clause, MPL-2.0. For hosted services write Proprietary (SaaS). Centered because the values are short codes that readers scan for the odd one out, usually a copyleft or source-available licence. |
| Architectural Purpose | left :--- | The job the component does in this system and the constraint that led to choosing it: “static export so the site needs no server”, “Postgres for transactional data; analytics live elsewhere”. One sentence that would help someone decide whether it can be replaced. |
How to Fill It In
- 1Collect candidates from manifests and lockfiles (
package-lock.json,go.mod,uv.lock,Gemfile.lock), then from infrastructure code — DockerfileFROMlines, Terraform providers,wrangler.toml— because hosted services never appear in a package manifest. - 2Cut the list down. Keep a component when replacing it would take more than a day or two of work; drop type definitions, lint plugins, and small utilities. Most applications end up with eight to fifteen rows.
- 3Read resolved versions from the toolchain rather than the manifest’s range:
npm ls next --depth=0,pip show django, orgo list -m all. A^15.1.7range inpackage.jsonsays little about what is installed. - 4Confirm each licence against the repository’s
LICENSEfile at the version you use, since licences do change between releases. Registry metadata (npm view <pkg> license) is a fast first pass, not proof. - 5Check support windows for runtimes and databases on their official release pages, and note anything that ends within the next year.
- 6Review the table whenever a major-version upgrade merges, which Renovate or Dependabot pull requests make easy to spot.
Ready-to-Paste Variations
Compact “Built with” README section
Two columns and links, nothing else. Readers of a public README want orientation, not an audit.
| Layer | Built with |
| :--- | :--- |
| Frontend | [Next.js](https://nextjs.org/) (static export), [React](https://react.dev/) |
| Styling | [Tailwind CSS](https://tailwindcss.com/) |
| Hosting | [Cloudflare Pages](https://pages.cloudflare.com/) |
| Language | [TypeScript](https://www.typescriptlang.org/) |Licence review for due diligence
For legal or acquisition review. The obligation column is a plain-language summary to start the conversation, not legal advice.
| Component | Version | License | How it is used | Main obligation |
| :--- | :---: | :---: | :--- | :--- |
| React | `19.1.0` | `MIT` | Bundled into client JavaScript | Keep the copyright notice |
| TypeScript | `5.7.3` | `Apache-2.0` | Build tool only, not shipped | Notice file if redistributed |
| Redis | `8.0` | `AGPL-3.0-only`, RSALv2, or `SSPL-1.0` | Self-hosted cache | Depends on which of the three you accept |
| Stripe | Managed | Proprietary (SaaS) | Payment processing | Stripe’s terms of service |Runtime support windows
For platform planning. The dates are the upstream end-of-life dates published by each project.
| Runtime | In use | Upstream end of life | Plan |
| :--- | :---: | :---: | :--- |
| Node.js | `22.x` | April 2027 | Move to Node.js 24 LTS in Q1 |
| PostgreSQL | `14` | November 2026 | Upgrade to 17 with `pg_upgrade` before the deadline |
| Python | `3.12` | October 2028 | No action this year |Common Mistakes
Listing every dependency in the manifest.
A forty-row table hides the five decisions that matter. Keep architectural components here and generate the full inventory as an SBOM in CycloneDX or SPDX format for anyone who needs everything.
Writing licence names loosely, as “Apache 2.0” or just “BSD”.
Use SPDX identifiers such as
Apache-2.0andBSD-3-Clause. “BSD” alone is ambiguous between the 2-clause and 3-clause variants, and scanners and compliance tools match on the exact identifier.Assuming a dependency’s licence never changes.
Several infrastructure projects have relicensed: Terraform moved to the Business Source License from 1.6, and Redis left BSD in 7.4 before adding an AGPL option in 8.0. Record the licence of the version you actually run and recheck it at each major upgrade.
Filling Architectural Purpose with marketing words like “fast” or “modern”.
Write the job and the reason: what it does here, what it replaced, which requirement it meets. “Chosen because the team already ran it in production” is a perfectly honest reason.
Naming a technology that the code does not actually use.
Check claims against the build. If the parsing engine is plain TypeScript, do not call it WebAssembly; reviewers who open the repository will notice, and the rest of the table loses credibility.
Related Markdown Table Templates
Browse all 50 templatesPros & Cons Architectural Decision (ADR)
Evaluate technical tradeoffs, architectural decisions, library selections, and deployment approaches with balanced pros and cons.
Cross-Browser & Platform Compatibility
Display minimum supported browser versions, rendering engines, platform support levels, and known caveats.
Git Workflow & Branching Governance
Define branching conventions, source bases, pull request targets, required approval reviews, and CI automation gates.
Project Architecture & Tech Stack: Frequently Asked Questions
What belongs in a tech stack table?
Languages, frameworks, datastores, hosting, and any third-party service the product cannot run without, such as authentication, payments, or email delivery. Leave out developer conveniences like formatters unless they shape how contributors work, in which case a Tooling tier is fine.
Should I pin exact versions in a README?
Use the major line, such as 15.x, in a README so it stays true between patch releases. Use exact versions in audit documents and incident reports, where the precise build matters. Either way, take the number from the lockfile.
Do open-source licences matter for a SaaS product that is never distributed?
Yes, in two ways. JavaScript sent to browsers is distributed, so its licence notices apply. And AGPL-3.0 reaches network use: modifying an AGPL component and letting users interact with it over a network can require offering them its source code.
Can I show logos or badges in the table?
Yes, with image syntax inside the cell, for example a shields.io badge. Keep them small and always include the text name too, because images can fail to load and screen readers depend on the alt text. See images and badges in tables.