Maturity Score: Your Architecture's Health in a Single Grade
You have a drift score. You have conformance rules. You have insights. You have DORA metrics. Four signals, four dashboards, four numbers to check before you can answer the simplest question: is our architecture in good shape?
The answer was always scattered. A team could have perfect documentation accuracy (drift score 95) but terrible deployment practices (DORA in the basement). Another could ship ten times a day but ignore every conformance rule in the book. Each metric told a piece of the story. None told the whole thing.
The Maturity Score fixes this. One grade. Four dimensions. A single view of how healthy your architecture actually is.
A through F. That's it.
Open any project in Archyl and you'll see a letter grade:
- A (90-100) — Your architecture is well-documented, conformant, actively monitored, and ships reliably. This is the target.
- B (80-89) — Solid. Minor gaps in one or two dimensions but nothing that keeps you up at night.
- C (70-79) — Decent foundation, real weaknesses. You know where the problems are but haven't fixed them.
- D (60-69) — Struggling. Multiple dimensions are underperforming. Technical debt is compounding.
- F (below 60) — Your architecture documentation is decorative. Start with the basics.
The grade isn't a vanity metric. It's computed from four weighted dimensions, each measuring something different about your architecture practice.
Four Dimensions, One Score
Drift — Does your documentation tell the truth?
The drift dimension measures how accurately your C4 model reflects your actual codebase. File paths that no longer exist. Services that were renamed. Containers that were merged. Every documented element is validated against the repository.
A high drift score means your architecture diagrams describe the system that actually runs in production. A low one means they describe a system that existed six months ago.
Insights — Are you listening to the signals?
Archyl continuously analyzes your architecture and surfaces issues: circular dependencies, oversized components, missing documentation, unused containers. The insights dimension measures how many of these issues exist and how severe they are.
A team that resolves critical insights quickly scores high. A team that lets warnings pile up scores low. This isn't about having zero issues — it's about having a culture of acting on them.
Conformance — Do you follow your own rules?
You defined architecture rules for a reason. No frontend container should call the database directly. Every system must have at least one documented API contract. Authentication services must not depend on business logic.
The conformance dimension measures what percentage of your rules are passing. It's the difference between having governance and enforcing it.
DORA — Can you actually ship?
Architecture quality means nothing if you can't deliver. The DORA dimension tracks the four standard metrics: deployment frequency, lead time for changes, change failure rate, and mean time to recovery.
A team with beautiful architecture that deploys once a quarter has a delivery problem. DORA catches it.
Weighted, Not Averaged
The four dimensions aren't equally weighted. Each project's maturity score is a weighted composite:
| Dimension | Default Weight | What it rewards |
|---|---|---|
| Drift | 25% | Keeping documentation accurate |
| Insights | 25% | Resolving architecture issues |
| Conformance | 25% | Following your own rules |
| DORA | 25% | Shipping reliably |
The weights are visible in the detail panel — every score shows its contribution. You can see exactly why your grade is what it is and which dimension is dragging it down.
Organization-Level View
Individual project scores are useful. Seeing all your projects side by side is transformative.
The Organization Maturity dashboard shows every project as a card: grade, score, trend, and a breakdown of all four dimensions. Filter by grade. Sort by score. Search by name. In thirty seconds, you know which projects need attention.
The grade distribution bar at the top gives you the shape of your organization's architecture health. Mostly A's and B's? You're in good shape. A cluster of D's and F's? You know where to invest.
Trends Tell the Real Story
Every maturity computation is tracked over time. Each project shows a trend: improving, stable, or declining.
A project that went from C to B last month is on the right track even if it isn't an A yet. A project that's been declining for three sprints needs intervention even if it's still a B. The trend is often more actionable than the absolute score.
The Recommendation Engine
The detail panel doesn't just show you scores — it tells you what to do. The weakest dimension gets a specific, actionable recommendation:
- Drift is lowest? "Run a drift detection to update your documentation alignment."
- Insights is lowest? "Review and resolve critical architecture insights."
- Conformance is lowest? "Fix conformance rule violations to improve compliance."
- DORA is lowest? "Improve deployment practices to boost DORA metrics."
No ambiguity. No "consider improving your processes." A concrete next step tied to the thing that will move your score the most.
Why a Single Grade Matters
Teams don't act on dashboards with twelve metrics. They act on one number that's easy to understand, easy to compare, and hard to game.
The Maturity Score is deliberately opinionated:
It's holistic. You can't get an A by being great at documentation but terrible at shipping. All four dimensions matter.
It's comparable. Project A has a B. Project B has a D. The conversation about where to invest engineering time just got simpler.
It's trackable. A number you can plot over time is a number you can improve. Set a target: "All projects at C or above by end of quarter." Now you have a measurable goal.
It's honest. The grade doesn't care about intentions or roadmaps. It measures what's true right now. Your documentation either matches the code or it doesn't. Your rules either pass or they don't.
Getting Started
The Maturity Score is available today for all Archyl projects. No setup required — if you have a project with architecture documentation, you already have a score.
- Open any project. The maturity badge appears in the project header.
- Click it to see the full breakdown: overall score, four dimensions, trend, and recommendation.
- Visit the Organization Maturity page to see all projects at once.
The architecture health of your organization shouldn't be a mystery. Now it's a letter grade.