ArchTrace reviews architecture proposals before implementation, combining deterministic checks, evidence traceability, and optional AI-assisted suggestions so every finding can be inspected and challenged.
Project Overview
ArchTrace is an evidence-traceable architecture review system designed for the early stages of software design.
It evaluates architecture inputs using an explicit deterministic review layer and produces findings that distinguish between what is directly detected and what requires engineering judgment. Each finding remains traceable to the evidence or design context that produced it.
An optional AI review layer can add structured suggestions, but it does not determine whether an architecture is correct. Deterministic findings remain the primary review layer, and AI output is isolated, validated, and clearly labeled as suggestion rather than fact.
The project is built around a simple principle:
Architecture review should explain not only what it found, but why the finding exists and what evidence supports it.
Problem Being Solved
Architecture reviews often happen through design documents, meetings, checklists, and reviewer experience.
That works, but important reasoning can become difficult to trace. A concern may be raised without a clear connection to the requirement that triggered it. Different reviewers may focus on different risks, and AI-assisted review can make the problem worse by producing plausible recommendations without showing whether they are actually grounded in the architecture being reviewed.
Traditional static checklists have the opposite limitation: they are predictable, but often provide little context around why a finding matters.
ArchTrace explores a middle ground.
It uses deterministic rules for repeatable architecture checks, preserves evidence behind each finding, and allows AI to contribute only through a bounded suggestion layer. This makes reviews easier to reproduce, inspect, discuss, and evolve before implementation begins.
How ArchTrace Works
- Deterministic review layer
Applies 21 explicit architecture-review rules to the supplied design context. Findings are classified asDETECTEDorREVIEW_REQUIRED, keeping observable conditions separate from issues that need engineering judgment. - Evidence traceability
Findings retain the context that caused them to be raised. A reviewer can inspect the connection between the architecture input, the rule, and the resulting finding instead of receiving an unexplained recommendation. - Optional AI review
A bounded subset of structured architecture context may be passed to an AI adapter. AI-generated observations are returned separately asAI_SUGGESTIONand never replace deterministic findings. - AI output validation and failure isolation
AI responses are validated before being accepted into the review output. Provider failures, malformed responses, or unavailable AI services do not prevent the deterministic review from completing. - Evaluation and reproducibility
The deterministic review path produces stable structured output and is covered by an evaluation harness and 109 automated tests. The AI evaluation focuses on contract and integration behavior rather than claiming that model suggestions represent architectural truth.
Technology Stack
| Area | Technology / Approach |
|---|---|
| Core | Python, deterministic architecture-review engine |
| Review Model | 21 explicit review rules with DETECTED and REVIEW_REQUIRED findings |
| AI Integration | Optional OpenAI-compatible adapter with bounded structured context |
| AI Output | Validated AI_SUGGESTION results with failure isolation |
| Offline Support | Mock AI adapter for deterministic development and testing |
| Interface | Command-line workflow with structured output |
| Evaluation | Deterministic evaluation harness and AI contract evaluation |
| Quality | 109 automated tests |
Design Principles
You can place this as a small visual/callout rather than another long section:
DETERMINISTIC REVIEW
↓
Primary findings
DETECTED / REVIEW_REQUIRED
+
OPTIONAL AI REVIEW
↓
AI_SUGGESTION
↓
Evidence-traceable
architecture reviewAnd underneath:
AI SUGGESTION
!=
ARCHITECTURE TRUTH
REVIEW REQUIRED
!=
ARCHITECTURE DEFECTThat is probably the strongest part of the project’s positioning.
Project Resources
| Resource | Link |
|---|---|
| GitHub | ArchTrace repository |
| Setup and demonstration path | README |
| Architecture | Architecture documentation |
| Evaluation | Evaluation / test documentation |