Arcovia

• 

  arcovia banner

• 

  arcovia architecture

• 

  CLI Output

• 

  overview of the project architecture

• 

  project report trend and signal maps

• 

  why the score and how it is calculated

• 

  refactoring roadmap

• 

  priority actions

• 

  findings

• 

  dependency graph

Inspiration

After spending more than a decade building large React applications, I noticed that frontend teams have excellent tools for measuring code quality, testing, bundle size, and performance, but almost no objective way to evaluate the architecture of a codebase.

Questions like:

• Is our architecture getting healthier over time?
• Which modules contribute most to architectural debt?
• Where should we start refactoring?

are usually answered through code reviews or experience rather than measurable data.

I wanted to build a tool that could answer these questions objectively using deterministic static analysis instead of subjective opinions or AI-generated guesses.

That idea became Arcovia.

What it does

Arcovia is an architecture intelligence CLI for React and Next.js applications.

It scans a project, builds a complete dependency model, evaluates deterministic architecture rules, calculates an explainable architecture score, and generates an interactive offline HTML report.

The report helps developers understand:

• overall architecture health
• dependency relationships
• architectural hotspots
• code organization
• score calculation
• prioritized refactoring opportunities

Everything in the report is backed by deterministic static analysis and evidence extracted directly from the codebase.

How we built it

Arcovia is built as a modular analysis pipeline.

Filesystem
    ↓
Scanner
    ↓
AST Parser
    ↓
Dependency Graph
    ↓
Rule Engine
    ↓
Architecture Scoring
    ↓
Analysis Report
    ↓
Offline HTML Report

The project uses:

• TypeScript
• Node.js
• ts-morph
• React
• Vite
• Tailwind CSS

One of the primary goals was to make every architectural finding traceable and explainable rather than relying on opaque heuristics.

Throughout development, I used Codex with GPT-5.6 as my primary engineering partner. It assisted in designing the architecture, implementing features, refactoring complex modules, generating tests, improving documentation, and iterating on the report design. Rather than generating the application in one shot, Codex was used continuously throughout the development process to accelerate implementation and evaluate different architectural approaches.

Challenges we ran into

The biggest challenge was building an architecture scoring system that developers could trust.

Simply counting findings produced misleading scores, while ignoring technical debt made unhealthy projects appear perfect.

I redesigned the scoring engine several times before arriving at a weighted model based on architectural categories, maintenance burden, and bounded critical-risk adjustments. The final score is transparent, explainable, and accompanied by evidence rather than acting as a black box.

Another challenge was reducing false positives in modern React and Next.js applications. Arcovia includes framework-aware behavior for common Next.js patterns such as route handlers, metadata exports, and framework-specific conventions.

Accomplishments that we're proud of

Building Arcovia wasn't just about creating another developer tool it was about building one that developers can trust.

Some accomplishments I'm particularly proud of include:

• Built a complete deterministic architecture analysis engine instead of relying on AI-generated code reviews. Every finding is backed by evidence extracted directly from the source code.
• Designed an explainable architecture scoring system where every point in the final score can be traced back to measurable architectural characteristics rather than opaque heuristics.
• Implemented a full analysis pipeline consisting of file discovery, AST parsing, dependency graph construction, rule evaluation, architecture scoring, and report generation.
• Created a self-contained interactive HTML report that works entirely offline with no server, account, or internet connection required.
• Reduced false positives for React and Next.js applications by making the analyzer framework-aware, supporting route handlers, metadata exports, and other Next.js conventions.
• Designed the project with extensibility in mind, allowing new architecture rules, reports, and scoring strategies to be added without changing the core pipeline.
• Used Codex with GPT-5.6 throughout the development process as an engineering collaborator to accelerate implementation, iterate on architectural decisions, refactor complex components, improve documentation, and refine the overall developer experience while keeping the analysis engine itself deterministic.

Perhaps the accomplishment I'm most proud of is maintaining a clear product vision throughout development. Instead of trying to build "another AI coding tool," Arcovia focuses on solving a specific engineering problem: giving frontend teams an objective way to understand and improve the architecture of their React and Next.js applications.

What we learned

Building Arcovia reinforced that developer tools succeed because developers trust them.

That trust comes from deterministic analysis, transparent scoring, and actionable recommendations - not just sophisticated algorithms.

Working with Codex also changed the way I build software. Instead of using AI as a code generator, I treated it as an engineering collaborator for exploring designs, reviewing implementations, refactoring modules, and iterating quickly while keeping full control over the final architecture.

What's next for Arcovia

Arcovia is currently focused on deterministic architecture intelligence.

The next phase of the project includes:

• GitHub Action integration
• VS Code extension
• CI architecture quality gates
• Historical architecture trends
• Team dashboards
• Optional AI-powered explanations and architectural coaching built on top of deterministic analysis

The long-term vision is to help engineering teams continuously understand, measure, and improve the architecture of their frontend applications.

Built With

• ast
• cli
• codex
• css
• developer-tool
• github
• gpt-5.6
• html
• javascript
• next.js
• node.js
• npm
• openai
• opensource
• pnpm
• react
• software-architecture
• static-analysis
• tailwind
• ts-morph
• typescript
• vite