​

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:

​

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

​

What Each Review Includes

Executive Summary

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.

Strengths

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.

Weaknesses

Areas where the architecture falls short of its potential. Each weakness includes enough context to understand the problem and its scope.

Risks

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.

Recommendations

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

Octokraft 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

​

How It Works

Octokraft 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 Octokraft 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 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

---

​

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

​

When ADRs Are Suggested

Octokraft 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, Octokraft 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

Octokraft 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

Project Overview

The purpose of the project, its primary use cases, and the problem it solves. Derived from the codebase structure, README content, and detected patterns.

Architecture and Components

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.

Data Flow

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.

Setup and Development

How to set up a development environment, run the project locally, and execute tests. Derived from configuration files, scripts, and project structure.

Testing Approach

How the project is tested — unit tests, integration tests, test utilities, and testing patterns. Based on test file analysis and test framework detection.

Dependencies

Third-party libraries and external services the project depends on, with their roles in the system.

Coding Conventions

The conventions Octokraft has detected (and your team has confirmed), formatted as a reference for developers and AI coding assistants.

AI Assistant Guidelines

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.