Arcovia: A Rule-Based Architecture Intelligence Tool for React Apps

The Challenge That Sparked This Project

During a recent OpenAI Build Week Hackathon, a team set out with a straightforward objective: create something a developer would genuinely want to use day to day.

By the end of the first evening, the concept was clear. Within two more days, that concept turned into a working open source project named Arcovia.

This wasn't meant to be a one-off AI demo. It aimed to address a recurring frustration that developers run into when maintaining large React codebases over long periods.

The Gap in Existing Tooling

Plenty of solid tools already exist for keeping code clean.

• ESLint flags problematic patterns.
• Prettier handles formatting.
• SonarQube surfaces quality issues.
• AI-based reviewers suggest line-level improvements.

Yet none of these tools can answer more structural questions such as:

• Is the overall architecture in good shape?
• Which modules are turning into chokepoints?
• Where is technical debt piling up?
• Which files deserve refactoring attention first?
• What actually led to a given project score?

Architectural problems tend to surface only in code review discussions, or worse, once the codebase has already become painful to work with. What was missing was a way to gauge the health of an architecture before it turned into a real liability.

Meet Arcovia

Arcovia is described as an Architecture Intelligence tool built for React and Next.js codebases.

Rather than flooding you with a long list of disconnected warnings, it evaluates the project holistically and outputs an interactive HTML report.

That report includes:

• An Architecture Health Score
• A Dependency Graph
• Architecture Hotspots
• A breakdown explaining how the score was derived
• Rule-based findings
• A Maintenance Burden indicator
• Actionable recommendations

Arcovia isn't trying to replace linters. Its purpose is to give developers visibility into the bigger structural picture that individual lint rules can't capture.

Under the Hood

The tool runs a fully deterministic analysis pipeline internally.

Project
   │
   ▼
Scanner
   │
   ▼
AST Parser
   │
   ▼
Project Model
   │
   ▼
Dependency Graph
   │
   ▼
Rule Engine
   │
   ▼
Score Engine
   │
   ▼
Interactive HTML Report

The analyzer is currently able to flag a range of structural issues. Among them:

• overly central "God Modules" that too much of the app depends on
• components or files with High Fan-In
• components or files with High Fan-Out
• Orphan Modules that nothing else references
• Large Components that have grown too big
• Deep JSX Nesting
• Oversized Modules
• Duplicate Imports scattered across files
• Unused Exports left behind in the codebase

Rather than listing these findings in isolation, Arcovia aggregates them into a single, explainable architecture score.

Rules Come First, AI Comes Second

One choice the creators feel strongly good about is leaving AI out of the core analysis logic.

The architecture score itself is never produced by a language model.

Instead, Arcovia works by:

• parsing the codebase through its AST
• constructing dependency graphs
• running the results through deterministic architectural rules
• calculating scores per category
• computing a maintenance burden metric
• assembling all of that into a final architecture score

Because of this design, results stay consistent and reproducible.

The broader plan is for AI to augment the experience rather than take over the scoring itself. Planned uses include:

• explaining individual findings in plain language
• proposing refactoring approaches
• pointing to relevant learning resources
• answering follow-up questions about the report

The deterministic analysis stays the single source of truth, with AI layered on top as an interpreter.

Working With GPT-5.6 and Codex

This hackathon also marked the first time the team leaned on AI as a genuine collaborator throughout a build, rather than treating it as a glorified autocomplete.

Over the course of the weekend, GPT-5.6 and Codex were used to:

• brainstorm which architectural rules made sense to include
• refine how the scoring model weighs different signals
• implement individual features
• polish the report's visual design
• simplify convoluted logic
• sanity-check implementation decisions

ChatGPT Images was also used to design Arcovia's branding, including its owl mascot, logo, and other launch materials.

The overall workflow felt more natural than expected. Instead of handing off entire features to be generated end to end, the greatest benefit came from quick back-and-forth iteration, similar to having a second engineer on hand to talk through design options and weigh trade-offs.

Takeaways From the Weekend

Compressing this build into a single weekend surfaced several useful lessons.

Architecture resists simple metrics

Assessing code quality in isolation is fairly mechanical.

Assessing architecture is much harder, since it depends on context, competing trade-offs, and carefully tuned weighting across many different rules.

Striking the right balance between genuinely useful signals and noisy false positives remains an open, ongoing effort.

A score without context isn't helpful

Handing someone a number on its own doesn't tell them much.

Developers need to see:

• why the score came out the way it did
• which factors contributed most
• which issues carry the most weight
• what to tackle first

That's the reasoning behind designing the report around explaining the score, instead of treating it as an opaque output.

AI speeds things up, but not the way you'd expect

GPT-5.6 and Codex clearly sped up the build.

Still, the biggest gain in productivity wasn't from generating code faster.

It came from using AI as a thinking partner: working through design choices, questioning assumptions, and quickly testing different ideas.

What Comes Next

This release is just a starting point.

Features under consideration for future versions include:

• A GitHub Action integration
• Report history tracking
• Architecture trend analysis over time
• A VS Code extension
• Side-by-side project comparison
• Team-wide dashboards
• AI-driven architecture coaching

The longer-term goal is helping engineering teams continuously monitor, measure, and improve the architecture of their software over time.

Feedback Is Welcome

Arcovia is fully open source, and feedback from developers actively building React or Next.js applications would be especially valuable.

A few questions worth exploring:

• Does the architecture score feel like it captures something meaningful?
• What other architectural problems should be detected?
• What would make a report like this genuinely useful in your day-to-day workflow?

The project's source code lives in its repository at github.com/gkhan205/arcovia, the package can be installed straight from npmjs.com/package/arcovia, and full docs are hosted at arcovia.ghazikhan.in.

Ideas, feedback, and even pushback are all genuinely welcome, since real-world usage is the most effective way to make Arcovia better over time.