Over the weekend, I participated in the OpenAI Build Week Hackathon with a simple goal:
Build something I would actually use as a developer.
By Friday evening, I had an idea.
By Sunday, that idea became an open source project called Arcovia.
It wasn't just another AI coding experiment. I wanted to solve a problem I've faced while working on large React applications for years.
The Problem
We have excellent tools for code quality.
- ESLint catches code smells.
- Prettier formats code.
- SonarQube reports issues.
- AI reviews code and suggests improvements.
But none of them answer questions like:
- Is my architecture healthy?
- Which modules are becoming bottlenecks?
- Where is technical debt accumulating?
- Which files should I refactor first?
- Why did my project receive this score?
Architecture is often something we discuss during code reviews or realize too late when the codebase becomes difficult to maintain.
I wanted a tool that could measure architecture health before it became a problem.
Introducing Arcovia
Arcovia is an Architecture Intelligence tool for React and Next.js projects.
Instead of generating hundreds of isolated warnings, it analyzes the project as a whole and produces an interactive HTML report.
It includes:
- 📊 Architecture Health Score
- 🕸️ Dependency Graph
- 🎯 Architecture Hotspots
- 📈 Explainable Score Breakdown
- 🛠️ Rule-based Findings
- 📉 Maintenance Burden
- ✅ Actionable Recommendations
The goal isn't to replace linting.
The goal is to help developers understand the bigger picture.
How It Works
Internally, Arcovia follows a deterministic analysis pipeline.
Project
│
▼
Scanner
│
▼
AST Parser
│
▼
Project Model
│
▼
Dependency Graph
│
▼
Rule Engine
│
▼
Score Engine
│
▼
Interactive HTML Report
The analyzer currently detects things like:
- God Modules
- High Fan-In
- High Fan-Out
- Orphan Modules
- Large Components
- Deep JSX Nesting
- Oversized Modules
- Duplicate Imports
- Unused Exports
Instead of simply reporting findings, Arcovia combines them into an explainable architecture score.
Deterministic First. AI Second.
One design decision I'm particularly happy with is keeping AI out of the analysis itself.
The architecture score is not generated by an LLM.
Instead, Arcovia:
- parses the project using the AST
- builds dependency graphs
- evaluates deterministic architecture rules
- calculates category scores
- computes maintenance burden
- generates the final architecture score
This means the results are:
- reproducible
- explainable
- deterministic
My long-term vision is for AI to enhance the experience, not replace the analysis.
For example:
- explaining findings
- suggesting refactoring strategies
- recommending learning resources
- answering questions about the report
The analysis remains the source of truth.
Building with GPT-5.6 and Codex
This project was also my first serious experience treating AI as an engineering collaborator rather than just an autocomplete tool.
Throughout the weekend, GPT-5.6 and Codex helped me:
- brainstorm architecture rules
- refine the scoring model
- implement features
- improve the report design
- simplify complex logic
- review implementation ideas
I also used ChatGPT Images to create the Arcovia branding, owl mascot, logo, and launch assets.
Working this way felt surprisingly natural.
Instead of asking AI to build everything, I found the biggest value came from rapid iteration. It was like having another engineer available to discuss implementation ideas and explore different approaches.
What I Learned
Building Arcovia over a single weekend taught me a few valuable lessons.
Architecture is difficult to measure
Measuring code quality is relatively straightforward.
Measuring architecture requires context, trade-offs, and careful weighting of different rules.
Finding the right balance between useful insights and false positives is an ongoing challenge.
Explainability matters
A score by itself isn't useful.
Developers need to understand:
- why they received it
- what contributed to it
- which issues matter most
- what to fix first
That's why the report focuses on explaining the score rather than presenting it as a black box.
AI accelerates development
GPT-5.6 and Codex helped me move much faster.
But the biggest productivity boost wasn't writing code.
It was helping me think through design decisions, challenge assumptions, and iterate on ideas.
What's Next
This is only the beginning.
Some of the features I'm planning next include:
- GitHub Action
- Report History
- Architecture Trends
- VS Code Extension
- Project Comparison
- Team Dashboards
- AI-powered architecture coaching
The long-term vision is to help engineering teams continuously understand, measure, and improve their software architecture.
I'd Love Your Feedback
Arcovia is completely open source, and I'd love feedback from developers working on React or Next.js applications.
Some questions I'm particularly interested in:
- Does the architecture score feel meaningful?
- Which architectural issues would you want detected?
- What would make a report like this more useful in your workflow?
If you'd like to try it:
npx arcovia analyze .
GitHub: https://github.com/gkhan205/arcovia
npm: https://www.npmjs.com/package/arcovia
If you have ideas, feedback, or even criticism, I'd genuinely love to hear it. Real-world projects are the best way to make Arcovia better.
Thanks for reading, and thanks to the OpenAI Build Week Hackathon for the motivation to finally build an idea that had been sitting in my notebook for a long time. 🚀
Top comments (0)