Most engineers can tell within minutes whether a codebase is in good shape. Explaining that assessment to a technical director or board member who never reads source code is harder. Measuring technical health turns those engineering instincts into concrete signals across architecture, maintainability, delivery, and operations.
Why Intuition Needs Backing Data
Experienced developers often have strong instincts about code quality. They spot tight coupling in a dependency graph, notice complexity in bloated methods, and anticipate where bugs will cluster. However, individual impressions do not transfer cleanly across teams or management layers.
When a new engineering lead joins, they cannot rely on the unspoken context of their predecessor. When leadership asks why shipping a feature takes three weeks instead of three days, saying the codebase is messy does not explain the bottleneck. When deciding whether to fund a modernisation effort, leaders need concrete evidence rather than vague warnings.
Measuring technical health translates day-to-day engineering observations into clear data that teams and leadership can evaluate together.
The Eight Key Domains
A thorough evaluation looks across eight distinct areas of system design, code quality, and delivery practices.
1. Architecture
Architecture health reflects how well the system structure supports current workloads and future changes. Key signals include:
- Coupling and cohesion: Components should have focused responsibilities with clear dependencies, avoiding changes that ripple unexpectedly across unrelated modules.
- Boundary clarity: System boundaries should be explicit through documented APIs, message contracts, or interfaces rather than direct access to database tables or internal classes.
- Scalability headroom: The architecture should support higher traffic volumes through standard horizontal scaling without requiring structural rewrites.
- Legacy isolation: Older subsystems should be isolated behind anti-corruption layers or adapters so they can be refactored or replaced independently.
2. Maintainability
Maintainability evaluates how easily developers can understand, modify, and extend the codebase. In a maintainable system, engineers can inspect an unfamiliar component, understand its behavior, and release changes safely.
Useful metrics include average cyclomatic complexity, the percentage of oversized methods or classes, code duplication across modules, and git churn metrics that track how many existing files are touched per new feature.
3. Security
Security health goes beyond running automated dependency scans. It evaluates whether protective controls are designed into the core system structure. Key checks include consistent authorization policies across both API controllers and service layers, automated secret rotation, encryption in transit and at rest, and least-privilege service configurations.
4. DevOps and Delivery
Delivery health measures how reliably and frequently code moves from development to production. The four standard DORA metrics provide clear benchmarks here:
- Lead time for changes: How long it takes for a committed change to reach production.
- Deployment frequency: How often the team successfully deploys to production.
- Change failure rate: The percentage of deployments that cause production incidents or require rollbacks.
- Mean time to recovery (MTTR): How long it takes to restore service when an outage occurs.
Automated pipelines, trunk-based development, and reliable smoke tests directly drive improvements across all four metrics.
5. Cloud and Infrastructure
For cloud-hosted systems, infrastructure health looks at provisioning, cost efficiency, and reliability. Key areas include defining all resources as code with tools like Bicep or Terraform, using managed platform services where appropriate, configuring automated autoscaling rules, and eliminating untracked resources that inflate monthly bills.
6. Codebase Quality
Code quality focuses on the structure of the source files. This includes meaningful test suites that verify business behavior rather than trivial mock implementations, automated linting and static analysis, consistent error handling patterns, and adherence to shared framework conventions.
7. Observability
Observability determines how quickly engineers can diagnose production issues without guessing. This requires structured logging with correlation identifiers, distributed tracing across network boundaries, operational metrics dashboards, and actionable alerts that trigger before users report outages.
8. Team and Engineering Practices
Codebases reflect the habits of the teams building them. Key factors include minimizing single points of failure where critical domain knowledge is held by only one person, keeping onboarding documentation up to date, and recording architectural decision records (ADRs) when making significant structural choices.
Scoring and Evaluation
Scoring each domain on a 0 to 100 scale provides a consistent baseline across the organization. The main value of a structured rubric is grounding discussions in concrete evidence rather than subjective impressions, helping teams agree on where the real risks lie.
An example evaluation summary might look like this:
| Domain | Score | Key Finding |
|---|---|---|
| Architecture | 72/100 | Core domain model is sound; OrderService has grown beyond its mandate |
| Maintainability | 58/100 | 14% of methods exceed complexity threshold; 23% code duplication in data access layer |
| Security | 64/100 | Authorization is consistent at API layer; internal service calls are unauthenticated |
| DevOps | 81/100 | Good CI/CD coverage; deployment frequency limited by manual approval steps |
| Cloud | 76/100 | Azure-native services used appropriately; IaC partially adopted |
| Observability | 43/100 | Structured logging present but no distributed tracing; alerting is reactive not proactive |
| Overall | 66/100 | Functional system with addressable risks; observability is the most urgent gap |
Prioritizing Improvements
An assessment is useful only when it leads to action. Grouping findings by severity and required effort helps teams build a realistic roadmap rather than trying to fix everything at once:
- High impact, low effort: Schedule for upcoming sprints. These quick wins resolve pressing bottlenecks and build team confidence.
- High impact, high effort: Plan as structured initiatives. These architectural improvements require dedicated milestones and capacity.
- Low impact, low effort: Fix opportunistically as part of regular feature work in the relevant components.
- Low impact, high effort: Document and monitor. These are known trade-offs that do not warrant immediate investment.
Cadence for Measurement
Operational indicators like DORA metrics and error rates should be tracked continuously in engineering dashboards. Comprehensive architectural reviews work best on a periodic basis or during major milestones, such as preparing for a modernisation initiative, planning for higher traffic scale, or onboarding new engineering leadership.
Automated tools track daily trends in complexity and coverage, while periodic deep assessments evaluate broader structural alignment, operational risks, and team delivery practices.
Establishing a Baseline
Establishing an initial baseline provides the reference point needed to measure progress over time. It highlights risks that individual developers might see but leadership has not yet quantified, providing the business case for investing in technical quality.
Our Software Architecture Assessment evaluates systems across these eight domains, reviewing application architecture, code health, cloud setup, security, and delivery workflows. The result is a scored assessment paired with a pragmatic remediation plan. You can explore our Contoso sample report to see how an evaluation is structured.