AI Architecture Review¶

The AI Architecture Review is an automated architectural analysis engine that reads the Project Context Graph to detect anti-patterns, coupling risks, schema design issues, API design problems, migration risks, and performance concerns — then computes a health score and suggests improvements. It is read-only and never modifies your code or database.

Quick Start¶

from aksara.ai.architecture_review import run_architecture_review

report = run_architecture_review()
print(f"Score: {report.score} ({report.grade})")

for f in report.findings:
    print(f"  [{f.severity}] {f.title}")
for s in report.suggestions:
    print(f"  → {s.title}")

Architecture¶

The review runs a 9-step pipeline:

┌─────────────┐     ┌────────────┐     ┌──────────────┐
│ 1. Load      │────▶│ 2. Compute │────▶│ 3. Detect    │
│ Project Graph│     │ Metrics    │     │ Coupling     │
└──────────────┘     └────────────┘     └──────────────┘
        │                                      │
        ▼                                      ▼
┌──────────────┐     ┌────────────┐     ┌──────────────┐
│ 6. Migration │◀────│ 5. API     │◀────│ 4. Schema    │
│ Risks        │     │ Design     │     │ Design       │
└──────────────┘     └────────────┘     └──────────────┘
        │
        ▼
┌──────────────┐     ┌────────────┐     ┌──────────────┐
│ 7. Perf      │────▶│ 8. Score   │────▶│ 9. Generate  │
│ Risks        │     │ & Grade    │     │ Suggestions  │
└──────────────┘     └────────────┘     └──────────────┘

Load Project Graph — builds the full application graph.
Compute Metrics — calculates model/route/query counts, averages, and coupling score.
Detect Coupling — routes with too many models, queries, or hotspot models referenced by many routes.
Schema Design — large models (>20 fields), excessive relations (>8), missing indexes.
API Design — route explosion (>100 routes), deep nesting (>4 segments).
Migration Risks — high migration churn, recent schema changes.
Performance Risks — slow queries, N+1 warnings, security diagnostics.
Score & Grade — penalty-based scoring (A–F grading scale).
Generate Suggestions — category-specific, deduplicated, sorted by impact.

Data Models¶

ArchitectureMetrics¶

Field	Type	Description
`model_count`	`int`	Total registered models
`route_count`	`int`	Total registered routes
`query_count`	`int`	Total traced queries
`migration_count`	`int`	Total migrations
`diagnostic_count`	`int`	Total diagnostics
`avg_models_per_route`	`float`	Average models referenced per route
`avg_queries_per_route`	`float`	Average queries per route
`coupling_score`	`float`	Overall coupling score (0–1)

ArchitectureFinding¶

Field	Type	Description
`id`	`str`	Unique finding identifier
`severity`	`str`	`critical`, `error`, `warning`, `info`
`title`	`str`	Short finding title
`description`	`str`	Detailed explanation
`related_nodes`	`list[str]`	Related graph nodes
`category`	`str`	Finding category (see below)

Categories: coupling, complexity, performance, schema_design, api_design, migration_risk, security.

ArchitectureSuggestion¶

Field	Type	Description
`suggestion_id`	`str`	Unique suggestion identifier
`title`	`str`	Short suggestion title
`description`	`str`	Detailed improvement advice
`impact`	`str`	`high`, `medium`, `low`
`related_findings`	`list[str]`	Finding IDs this addresses

ArchitectureReport¶

Field	Type	Description
`ok`	`bool`	Whether the review ran
`score`	`int`	Health score (0–100)
`grade`	`str`	Letter grade (A–F)
`findings`	`list[ArchitectureFinding]`	Detected issues
`suggestions`	`list[ArchitectureSuggestion]`	Improvement suggestions
`metrics`	`ArchitectureMetrics`	Computed metrics
`finding_count`	`int`	Number of findings
`suggestion_count`	`int`	Number of suggestions
`elapsed_ms`	`float`	Pipeline duration in ms
`generated_at`	`str`	ISO 8601 timestamp

Scoring¶

The scoring engine starts at 100 and applies penalties per finding:

Finding Type	Penalty
High coupling	−10
Missing index	−10
Slow query	−15
Large model	−5
Route explosion	−10
Deep nesting	−5
Migration churn	−5
N+1 query	−15
Security issue	−10

Grading scale: A (90–100), B (80–89), C (70–79), D (60–69), F (<60).

Studio UI¶

The Architecture Review panel is available in the Aksara Studio at the Architecture tab. Click Run Review to trigger an analysis.

The panel shows: - Score card with letter grade and colour coding - Metrics grid with model/route/query counts - Findings tab with severity badges and category labels - Suggestions tab with impact indicators

CLI¶

# Run architecture review (text output)
aksara ai flows review

# JSON output
aksara ai flows review --json

# Summary only (compact)
aksara ai flows review --summary

# Show metrics
aksara ai flows review --metrics

# JSON summary
aksara ai flows review --json --summary

Console Integration¶

The Interactive AI Console recognises architecture review intents:

> review my architecture
> how healthy is my system
> architecture analysis
> check anti-patterns
> coupling analysis
> refactoring advice
> design review
> health check

API Endpoint¶

POST /studio/ai/architecture-review

Returns the full ArchitectureReport as JSON.