Tech Stack Taxonomy Audit

Systematically evaluate a project's technology choices and infrastructure maturity across 15 domains. Produces a coverage matrix, gap analysis, maturity score, and prioritized recommendations.

Most projects have blind spots. A team might have excellent CI/CD but no observability, or strong testing but zero resilience patterns. This audit makes those gaps visible before they become incidents.

When to Use

Onboarding to an unfamiliar codebase — get the full picture fast
Before major architecture decisions — know what you're building on
Planning tech debt sprints — prioritize by risk, not gut feel
Pre-launch readiness check — verify nothing critical is missing
After a major refactor or migration — confirm nothing was lost
Periodic health checks (quarterly or after team changes)

When NOT to Use

For security-specific audits — use security-audit or web-app-security-audit instead
For code quality review — use design-code-review or code-simplifier
When you already know the specific gap and just need to fix it

The 15-Domain Taxonomy

Every software project, regardless of scale, touches these 15 domains. Not all need to be at maximum maturity — but all should be consciously addressed.

1. Language & Runtime

Programming language, runtime version, build toolchain, compiler settings, language-level features (strict mode, null safety).

Scan targets: package.json, tsconfig.json, Cargo.toml, go.mod, requirements.txt, pyproject.toml, Gemfile, .python-version, .nvmrc, .tool-versions, rust-toolchain.toml

2. Framework & Libraries

Core framework, UI library, utility libraries, state management, routing, form handling.

Scan targets: package.json dependencies, Cargo.toml, go.mod, requirements.txt, Gemfile, import statements across source files

3. Data Storage

Database, cache layer, file/object storage, search index, data migrations, backup strategy.

Scan targets: docker-compose.yml, database config files, migration directories, ORM config, .env for connection strings, schema.prisma, drizzle.config.ts, alembic.ini

4. API & Communication

REST/GraphQL/gRPC endpoints, message queues, webhooks, WebSockets, API versioning, request/response schemas.

Scan targets: Route definitions, OpenAPI/Swagger specs, .proto files, GraphQL schema files, webhook handlers, WebSocket setup, API client configs

5. Authentication & Authorization

Identity provider, session management, RBAC/ABAC, OAuth/OIDC, API key management, MFA.

Scan targets: Auth middleware, session config, JWT handling, OAuth provider setup, role/permission definitions, route guards, RLS policies

6. Infrastructure & Deployment

Cloud provider, IaC (Terraform/Pulumi/CDK), containers, orchestration, CDN, DNS, domain config, environments (dev/staging/prod).

Scan targets: Dockerfile, docker-compose.yml, terraform/, pulumi/, cdk/, serverless.yml, fly.toml, render.yaml, vercel.json, netlify.toml, railway.toml, Kubernetes manifests

7. CI/CD & Build

Pipeline tool, build system, artifact registry, release strategy (semantic versioning, changelogs), branch strategy, deployment automation.

Scan targets: .github/workflows/, .gitlab-ci.yml, Jenkinsfile, bitbucket-pipelines.yml, .circleci/, Makefile, build scripts, release.config.js, CHANGELOG.md

8. Testing

Unit, integration, E2E, load, contract testing tools and coverage. Test structure, fixtures, mocking strategy.

Scan targets: jest.config.*, vitest.config.*, pytest.ini, cypress.config.*, playwright.config.*, *.test.*, *.spec.*, __tests__/, tests/, .nycrc, coverage/, k6/, artillery/

9. Observability

Logging, metrics, tracing, alerting, dashboards, error tracking, uptime monitoring.

Scan targets: Logger configuration, Sentry/Datadog/New Relic setup, OpenTelemetry config, Prometheus metrics, Grafana dashboards, PagerDuty/OpsGenie integration, health check endpoints

10. Security

Dependency scanning, SAST/DAST, secrets management, CSP headers, WAF, vulnerability disclosure policy.

Scan targets: npm audit config, Snyk/Dependabot/Renovate config, CSP meta tags or headers, .env handling, .gitignore, secrets in CI/CD, security headers in deployment config

11. Developer Experience

Linting, formatting, type checking, local dev environment, documentation, onboarding, editor config, git hooks.

Scan targets: .eslintrc.*, .prettierrc.*, biome.json, .editorconfig, lefthook.yml, .husky/, lint-staged config, Makefile, docker-compose.yml (dev services), CONTRIBUTING.md, docs/

12. Error Handling & Resilience

Circuit breakers, retries with backoff, fallbacks, graceful degradation, health checks, timeout configuration, dead letter queues.

Scan targets: Error boundary components, retry logic, circuit breaker libraries, health check endpoints, timeout configs, fallback UI, error logging patterns

13. Performance

Bundling, code splitting, caching strategy (HTTP, application, CDN), lazy loading, SSR/SSG, image optimization, database query optimization.

Scan targets: Webpack/Vite/esbuild config, bundle analysis, Cache-Control headers, CDN config, lazy/dynamic imports, SSR/SSG config, database indexes, query plans, lighthouse config

14. Accessibility & i18n

Screen reader support, WCAG compliance level, keyboard navigation, translation system, RTL support, locale handling.

Scan targets: ARIA attributes, a11y lint rules, axe-core config, i18next/react-intl/vue-i18n setup, translation files, lang attributes, focus management patterns

15. Cost & Scaling

Auto-scaling config, cost monitoring/alerts, resource limits, capacity planning, usage quotas, cost optimization (reserved instances, spot instances).

Scan targets: Auto-scaling policies, cloud billing alerts, resource requests/limits in Kubernetes, cost monitoring tools (Infracost, AWS Cost Explorer), usage-based pricing config, load balancer config

The 7 Layers (per domain)

For each of the 15 domains, assess across these 7 layers to determine true maturity:

Layer	Question	Possible Values
1. Exists	Is there any tooling or config for this domain?	Yes / No / Partial
2. Tool Choice	What specific tool or service is used?	Name the tool, or "None"
3. Configuration	Is it configured beyond defaults?	Default / Custom / Tuned
4. Integration	Does it connect to other domains properly?	Isolated / Partial / Integrated
5. Automation	Is it automated (CI/CD, scripts) or manual?	Manual / Scripted / Fully Automated
6. Documentation	Is the choice and config documented?	None / Inline / Dedicated
7. Maturity	Overall maturity rating for this domain	None / Ad-hoc / Defined / Managed / Optimized

Maturity definitions:

None — Domain not addressed at all
Ad-hoc — Something exists but it's inconsistent, incomplete, or accidental
Defined — Deliberate choice made, basic configuration in place
Managed — Configured, integrated with other domains, monitored
Optimized — Automated, documented, continuously improved, team-wide adoption

Process

Step 1: Scan the Project

Read and analyze these file categories:

# Package/dependency manifests
package.json, Cargo.toml, go.mod, requirements.txt, pyproject.toml, Gemfile, pom.xml, build.gradle

# Configuration files
tsconfig.json, .eslintrc.*, .prettierrc.*, biome.json, jest.config.*, vitest.config.*

# Infrastructure files
Dockerfile, docker-compose.yml, terraform/, pulumi/, serverless.yml, fly.toml, vercel.json, netlify.toml

# CI/CD configs
.github/workflows/*.yml, .gitlab-ci.yml, Jenkinsfile, bitbucket-pipelines.yml

# Documentation
README.md, docs/, CONTRIBUTING.md, CHANGELOG.md, ADRs

# Source patterns (sample key directories)
src/, lib/, app/, pages/, components/, middleware/, routes/, migrations/

For each file found, extract: tools used, versions pinned or floating, configuration depth, connections to other domains.

Step 2: Map Findings to the Taxonomy

For each of the 15 domains, fill in all 7 layers based on evidence found in the scan. Do not guess — mark "Unknown" if evidence is insufficient and note what would need manual verification.

Step 3: Produce the Coverage Matrix

Build the full 15x7 matrix. Use icons for quick scanning:

Exists: Y / N / ~
Configuration: D (default) / C (custom) / T (tuned)
Automation: M (manual) / S (scripted) / A (automated)
Documentation: 0 / 1 / 2
Maturity: 0-4 scale (None=0, Ad-hoc=1, Defined=2, Managed=3, Optimized=4)

Step 4: Identify Gaps and Risks

Flag domains that are:

Missing entirely (Exists = No) — severity depends on project type
Present but immature (Maturity = Ad-hoc) — often worse than missing because it creates false confidence
Isolated (Integration = Isolated) — tools that don't talk to each other waste effort
Undocumented (Documentation = None) — bus factor risk
Manual (Automation = Manual) — toil that compounds over time

Step 5: Rate Overall Project Maturity

Calculate a maturity score (0-100):

Score = (sum of all domain maturity ratings) / (15 domains x 4 max) x 100

Where maturity ratings are:
  None = 0, Ad-hoc = 1, Defined = 2, Managed = 3, Optimized = 4

Score Range	Rating	Interpretation
0-20	Prototype	Minimal infrastructure, acceptable for experiments
21-40	Early	Key gaps exist, not ready for production traffic
41-60	Developing	Core domains covered, gaps in supporting domains
61-80	Mature	Most domains addressed, focus on optimization
81-100	Optimized	Comprehensive coverage, continuous improvement

Deliverable Template

# Tech Stack Audit Report
**Project:** [name]
**Date:** [date]
**Auditor:** [name]

## Executive Summary
[2-3 sentences: overall maturity rating, biggest strengths, most critical gaps]

**Maturity Score: XX/100 — [Rating]**

## Coverage Matrix

| Domain | Exists | Tool | Config | Integration | Automation | Docs | Maturity |
|--------|--------|------|--------|-------------|------------|------|----------|
| 1. Language & Runtime | Y | Node 20 + TS 5.3 | C | Integrated | A | 1 | Defined |
| 2. Framework & Libraries | Y | Next.js 14 | C | Integrated | A | 1 | Managed |
| 3. Data Storage | Y | PostgreSQL + Redis | C | Integrated | S | 1 | Managed |
| 4. API & Communication | Y | REST + tRPC | C | Partial | S | 0 | Defined |
| 5. Auth & AuthZ | Y | NextAuth.js | D | Partial | M | 0 | Ad-hoc |
| 6. Infrastructure | ~ | Vercel | D | Isolated | A | 0 | Ad-hoc |
| 7. CI/CD & Build | Y | GitHub Actions | C | Integrated | A | 1 | Managed |
| 8. Testing | ~ | Vitest (unit only) | D | Isolated | S | 0 | Ad-hoc |
| 9. Observability | N | — | — | — | — | — | None |
| 10. Security | ~ | npm audit only | D | Isolated | M | 0 | Ad-hoc |
| 11. Developer Experience | Y | ESLint + Prettier | C | Integrated | A | 1 | Managed |
| 12. Error Handling | ~ | React Error Boundary | D | Isolated | M | 0 | Ad-hoc |
| 13. Performance | ~ | Next.js defaults | D | Partial | M | 0 | Ad-hoc |
| 14. Accessibility & i18n | N | — | — | — | — | — | None |
| 15. Cost & Scaling | N | — | — | — | — | — | None |

## Gap Analysis

### Critical Gaps (address before production)
| Domain | Gap | Severity | Risk |
|--------|-----|----------|------|
| Observability | No logging, metrics, or error tracking | HIGH | Blind to production issues, slow incident response |
| Auth & AuthZ | Default NextAuth config, no RBAC | HIGH | Potential unauthorized access |
| Security | No SAST, no secrets management, no CSP | HIGH | Vulnerable to common attacks |

### Important Gaps (address within next quarter)
| Domain | Gap | Severity | Risk |
|--------|-----|----------|------|
| Testing | No integration or E2E tests | MEDIUM | Regressions caught late |
| Error Handling | No retry logic, no circuit breakers | MEDIUM | Cascade failures under load |
| Accessibility | No a11y testing or ARIA patterns | MEDIUM | Excludes users, legal risk |

### Nice-to-Have (plan for future)
| Domain | Gap | Severity | Risk |
|--------|-----|----------|------|
| Cost & Scaling | No auto-scaling or cost monitoring | LOW | Surprise bills, manual scaling |
| Performance | No bundle analysis or caching strategy | LOW | Suboptimal load times |

## Recommendations (prioritized by risk)

### Immediate (this sprint)
1. **Add error tracking** — integrate Sentry or equivalent. Connects observability to error handling.
2. **Configure CSP headers** — add Content-Security-Policy to deployment config.
3. **Set up RBAC** — define roles and enforce in middleware, not just UI.

### Short-term (next 2-4 weeks)
4. **Add E2E tests** — cover critical user flows with Playwright.
5. **Set up structured logging** — use pino/winston with correlation IDs.
6. **Add dependency scanning** — enable Dependabot or Renovate.

### Medium-term (next quarter)
7. **Implement retry/circuit breaker patterns** for external service calls.
8. **Add accessibility testing** — axe-core in CI, manual screen reader testing.
9. **Set up cost monitoring** — billing alerts at 50%, 80%, 100% of budget.

## Stack Diagram
[Optional: dependency graph showing how domains connect]

## Notes
[Caveats, assumptions, areas that need manual verification]

Calibrating Expectations by Project Type

Not every project needs all 15 domains at Optimized. Use this guide to set appropriate expectations:

Project Type	Must Be Managed+	Should Be Defined+	Can Be Ad-hoc/None
Solo side project	1, 2, 8	3, 7, 11	5, 6, 9, 10, 12-15
Startup MVP	1, 2, 3, 5, 7	4, 6, 8, 10, 11	9, 12, 13, 14, 15
Production SaaS	1-11	12, 13	14, 15 (depends on market)
Enterprise platform	1-13	14, 15	None — all should be Defined+
Open source library	1, 2, 7, 8, 11	10	3-6, 9, 12-15

Anti-Patterns

Anti-Pattern	Why It's Wrong	What to Do Instead
Auditing only `package.json`	Misses IaC, CI/CD, deployment config, documentation, and runtime configuration	Scan all file categories listed in Step 1
Treating "exists" as "mature"	Having Jest installed doesn't mean good test coverage; having a Dockerfile doesn't mean proper container security	Assess all 7 layers for each domain
Recommending tools without context	Suggesting Kubernetes for a solo dev project wastes time and adds complexity	Use the calibration table to set appropriate expectations
Over-engineering the stack	Not every project needs all 15 domains at Optimized — some domains are irrelevant for certain project types	Match recommendations to project type and team size
Rating based on tool count	More tools does not mean more mature — three overlapping linters is worse than one well-configured one	Rate based on integration, automation, and actual effectiveness
Ignoring the "documentation" layer	Undocumented choices create bus factor risk and slow onboarding	Flag undocumented domains even if tooling is solid
Auditing in isolation	A stack audit without action items is just a report that gets filed and forgotten	Always end with prioritized, actionable recommendations
Conflating this with security audit	This audit covers breadth across 15 domains; security depth requires a dedicated security audit skill	Use this for coverage overview, `security-audit` for depth

stack-audit