Architectural Smells Detection
A VS Code–native architecture analysis tool that detects structural and layering violations in codebases using deterministic rules, with optional AI-assisted summarization. The project focuses on correctness, reproducibility, and privacy, rather than heuristic or black-box analysis.
Role
Software Engineer (Architecture & Developer Tooling)
End-to-end ownership of system design, implementation, testing, and documentation.
Team
Individual project
Designed and built independently, following production-level engineering standards.
Duration
Several weeks of iterative development across multiple phases.
Brief
This project addresses a common problem in growing codebases: architectural rules such as layering and dependency direction are difficult to enforce consistently and early.
The system integrates directly into VS Code and surfaces architectural violations as native diagnostics. A deterministic analysis engine ensures reproducible results, while an optional AI layer provides human-readable summaries without influencing the underlying findings.
My Contribution
I designed and implemented the full system, including the VS Code extension, a local companion service, the deterministic rule engine, and an optional AI summarization layer.
Beyond implementation, I focused on architectural decisions, privacy guarantees, testability, and long-term extensibility—treating the project as a production system rather than a prototype.
Problem
Architectural constraints are typically enforced through conventions and code reviews, which do not scale well as teams and codebases grow.
Many existing tools rely on heavyweight static analysis or AI-driven heuristics, leading to non-deterministic results, limited trust, and unclear privacy implications. Developers lack a lightweight, reliable way to detect architectural violations directly in their daily workflow.
Goal
The goal was to build a tool that:
- Detects architectural violations deterministically
- Integrates seamlessly into existing IDE workflows
- Works fully offline by default
- Enforces privacy guarantees by design
- Treats AI as optional and non-authoritative
Success was measured by clarity of results, reproducibility, and ease of adoption—not by feature breadth.
Target Users
Target User 1
“I want to make sure my code follows clear architectural rules as it grows.”
Target User 2
“I want to keep our codebase clean and maintainable, even with multiple contributors.”
Target User 3
“I want to ensure our architecture analysis is private and does not leak code.”
Target User 4
“I want to catch architectural problems early without slowing down development.”
Research
I reviewed existing architecture analysis tools and developer workflows to understand why many solutions fail to gain adoption. The analysis focused on trust, developer experience, and operational constraints.
Key Insights
- Deterministic results significantly increase trust and adoption
- Native IDE integration reduces friction compared to external tools
- Privacy must be enforced technically, not just documented
Designing the Product
The system was designed with a clear separation of concerns: the VS Code extension handles user interaction, while all analysis logic runs in a local companion service.
This architecture improves testability, isolates complexity, and allows the analysis engine to evolve independently of the IDE integration.
Core Requirements
- Deterministic, versioned analysis results
- Direct mapping from findings to source locations
- Zero cloud dependency by default
- Optional AI support without affecting core behavior
Finding a Project — Browse
Rather than introducing a new navigation paradigm, findings appear directly in the VS Code Problems Panel. This aligns with existing developer expectations and makes issues immediately actionable. A report view provides additional context when needed.
Decision 1
Deterministic Analysis First
I chose a deterministic, regex-based rule engine as the foundation of the system.
While this approach trades some precision for simplicity, it guarantees reproducible results, enables reliable regression testing, and avoids non-deterministic behavior common in AI-driven analysis.
Decision 2
Separate Companion Service
All analysis logic runs in a local companion service instead of inside the extension.
This introduces some operational overhead but provides clear benefits: better isolation, explicit versioning, easier testing, and a clean boundary for future extensions such as additional languages or analysis strategies.
Past Iterations
Earlier iterations experimented with tighter coupling and more complex heuristics. These approaches were intentionally simplified in favor of a more robust and maintainable architecture.
Known Limitations
- Regex-based rules cannot fully match AST-level precision
- Initial language coverage is intentionally limited
- Companion setup requires explicit documentation
Next Steps
Increasing Precision and Coverage
Future work includes AST-backed rules, expanded language support, and improved onboarding for the companion service. The architecture is designed to support these extensions incrementally.
Takeaways
Designing for Trust Scales Better Than Designing for Features
This project reinforced that developer tools succeed when they are predictable, transparent, and respectful of real-world constraints such as privacy and testability. Clear architecture and explicit trade-offs often matter more than advanced or opaque features.