> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octokraft.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture Intelligence
> Architecture reviews, conventions, decision records, and living documentation
# Architecture Intelligence
Code quality is not just about individual functions and files. The way your system is structured -- how modules relate, how patterns are applied, how decisions are documented -- determines whether your codebase gets easier or harder to change over time.
The Architecture tab provides four capabilities: reviews, conventions, decision records, and living documentation.
***
## Architecture Reviews
On-demand analysis of your system architecture, scored across 4 dimensions:
| Dimension | Weight | What It Measures |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| **Modularity** | 1.5x | Are concerns properly separated? Are domain boundaries clear? Do modules have focused responsibilities? |
| **Coupling** | 1.5x | How interdependent are your modules? Are there circular dependencies? Can you change one module without breaking others? |
| **Scalability** | 1.0x | Can this system grow? Where are the performance bottlenecks? Are there architectural ceilings? |
| **Patterns** | 1.0x | Is there consistency in how design patterns are applied? Are similar problems solved in similar ways? |
### Why Modularity and Coupling Are Weighted Higher
Modularity and coupling problems are the hardest to fix later. A scalability issue in one endpoint is localized -- you can optimize it without restructuring your system. Tight coupling spreads through the entire codebase and gets worse over time. Every new feature added to a tightly coupled system makes the coupling harder to unwind.
Teams that defer modularity and coupling improvements eventually hit a point where adding simple features requires changes in dozens of files. Architecture reviews catch this trajectory early.
### Rating Scale
| Rating | Score Range |
| ------ | ----------- |
| A | 85 -- 100 |
| B | 70 -- 84 |
| C | 55 -- 69 |
| D | 40 -- 54 |
| F | Below 40 |
### What Each Review Includes
A high-level assessment of the current architecture, highlighting the most important strengths and concerns. Written for technical leads and engineering managers who need the picture without reading every detail.
What your architecture does well. Clear domain boundaries, consistent patterns, effective use of abstraction -- these are called out explicitly so teams know what to preserve as the system evolves.
Areas where the architecture falls short of its potential. Each weakness includes enough context to understand the problem and its scope.
Concrete risks with severity ratings and specific recommendations. A risk might be: "The payment module directly accesses the user database, bypassing the user service. If the user schema changes, the payment module will break silently." Each risk includes a recommendation for resolution.
Prioritized list of improvements with estimated effort (low, medium, high). Recommendations are ordered by impact-to-effort ratio, so teams can focus on the changes that deliver the most architectural improvement for the least disruption.
***
## Conventions
Corbulo detects patterns in your codebase and tracks them as conventions. Instead of relying on style guides that go stale, conventions are derived from what your code actually does.
### Convention Categories
| Category | What It Tracks |
| ------------------ | ------------------------------------------------------- |
| **Naming** | Variable, function, and class naming patterns |
| **Error Handling** | How errors are handled, propagated, and reported |
| **Structure** | File and folder organization patterns |
| **API Design** | Endpoint naming, request/response structure, versioning |
| **Documentation** | Comment style, doc coverage, documentation patterns |
| **Imports** | Import ordering, grouping, and organization |
### How It Works
Corbulo analyzes your codebase and identifies recurring patterns. When it finds a pattern followed consistently across your code, it registers it as a convention and begins tracking conformance.
For each convention, you see:
* **Pattern description** -- What the convention is and how it manifests
* **Conformance rate** -- What percentage of applicable code follows the pattern
* **Examples** -- Conforming and non-conforming instances from your actual code
* **Status** -- Whether the convention is detected, confirmed, or dismissed
### Conformance and Health Impact
When Corbulo detects that 90% of your functions use one naming convention but 10% use a different one, the 10% are flagged as consistency deviations. These deviations feed into the [Consistency category](/features/code-health#consistency) of your health score.
This is not about enforcing arbitrary rules. It is about identifying what your team has already chosen (by practice, not by decree) and surfacing the places where that choice is not being followed.
### Managing Conventions
Mark a detected convention as intentional. Confirming a convention signals that deviations from it should be treated as issues. Use this when Corbulo has correctly identified a pattern your team wants to enforce.
Mark a detected pattern as not a convention. Dismissing tells Corbulo that the variation is intentional and should not generate consistency issues. Use this when a detected pattern is coincidental rather than intentional.
***
## Architecture Decision Records (ADRs)
ADRs document the why behind architectural decisions. They answer the question every developer eventually asks: "Why is it built this way?"
### Lifecycle
A decision is identified and documented. This may happen when Corbulo detects a significant architectural change, or when a team member creates an ADR manually.
The team reviews and accepts the decision. The ADR becomes part of the project's architectural record.
When a decision is no longer relevant -- because the system has evolved or a better approach has been found -- the ADR is marked as deprecated or superseded by a newer decision.
### When ADRs Are Suggested
Corbulo identifies significant changes that warrant an architectural decision record:
* **Data schema changes** -- New tables, modified relationships, migration-heavy changes
* **API contract changes** -- Breaking changes to public interfaces, new versioning
* **Security-related changes** -- Authentication model changes, new access control patterns
* **Infrastructure changes** -- Changes with migration risk or backward compatibility concerns
When these changes are detected, Corbulo can draft an ADR capturing the context, rationale, and implications. The draft is a starting point -- your team refines and approves it.
### Why ADRs Matter
Architectural knowledge is the most perishable form of technical documentation. The person who made the decision leaves. The Slack thread where it was discussed is buried. The PR description said "refactor auth" but not why the old approach was abandoned.
ADRs prevent this by creating a durable, searchable record of decisions and their rationale. They are especially valuable for:
* New team members understanding why the system is shaped the way it is
* Future developers evaluating whether a past decision still applies
* Teams debating changes to established patterns
***
## Living Documentation
Corbulo generates documentation that stays in sync with your codebase. Unlike static docs that go stale the moment they are written, living documentation is regenerated as your code evolves.
### What Gets Documented
The purpose of the project, its primary use cases, and the problem it solves. Derived from the codebase structure, README content, and detected patterns.
Major components, their responsibilities, and how they relate to each other. Module boundaries, service layers, and integration points are documented based on actual code structure.
How data moves through the system -- from ingestion to processing to storage to output. Entry points, transformation steps, and persistence layers are traced from the code.
How to set up a development environment, run the project locally, and execute tests. Derived from configuration files, scripts, and project structure.
How the project is tested -- unit tests, integration tests, test utilities, and testing patterns. Based on test file analysis and test framework detection.
Third-party libraries and external services the project depends on, with their roles in the system.
The conventions Corbulo has detected (and your team has confirmed), formatted as a reference for developers and AI coding assistants.
Guidelines specifically formatted for AI coding tools. When developers use AI assistants with your codebase, these guidelines help the AI follow your team's established patterns and conventions.
### Keeping Documentation Current
Living documentation updates when your codebase changes. When a new module is added, when conventions shift, when the dependency graph evolves -- the documentation reflects the current state of the system, not a snapshot from the last time someone remembered to update the wiki.
Living documentation is generated from analysis of your codebase. It is a starting point that reflects what Corbulo can observe. Your team can supplement it with context that only humans know -- business rationale, historical decisions, and roadmap considerations.