common-architecture-audit

Audit structural debt, logic leakage, and monolithic components across Web, Mobile, and Backend codebases. Use when reviewing architecture, assessing tech debt, detecting logic in wrong layers, or identifying God classes. (triggers: package.json, pubspec.yaml, go.mod, pom.xml, nest-cli.json, architecture audit, code review, tech debt, logic leakage, refactor)

385 stars

Best use case

common-architecture-audit is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Audit structural debt, logic leakage, and monolithic components across Web, Mobile, and Backend codebases. Use when reviewing architecture, assessing tech debt, detecting logic in wrong layers, or identifying God classes. (triggers: package.json, pubspec.yaml, go.mod, pom.xml, nest-cli.json, architecture audit, code review, tech debt, logic leakage, refactor)

Teams using common-architecture-audit should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

  • You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

  • You only need a quick one-off answer and do not need a reusable workflow.
  • You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/common-architecture-audit/SKILL.md --create-dirs "https://raw.githubusercontent.com/HoangNguyen0403/agent-skills-standard/main/skills/common/common-architecture-audit/SKILL.md"

Manual Installation

  1. Download SKILL.md from GitHub
  2. Place it in .claude/skills/common-architecture-audit/SKILL.md inside your project
  3. Restart your AI agent — it will auto-discover the skill

How common-architecture-audit Compares

Feature / Agentcommon-architecture-auditStandard Approach
Platform SupportNot specifiedLimited / Varies
Context Awareness High Baseline
Installation ComplexityUnknownN/A

Frequently Asked Questions

What does this skill do?

Audit structural debt, logic leakage, and monolithic components across Web, Mobile, and Backend codebases. Use when reviewing architecture, assessing tech debt, detecting logic in wrong layers, or identifying God classes. (triggers: package.json, pubspec.yaml, go.mod, pom.xml, nest-cli.json, architecture audit, code review, tech debt, logic leakage, refactor)

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

Related Guides

SKILL.md Source

# Architecture Audit

## **Priority: P1 (STANDARD)**

## 1. Discover Structural Duplication

Identify split sources of truth by searching for redundant directory patterns.

- Compare `Service.ts` vs `ServiceNew.ts` vs `ServiceV2.ts`.
- Check for `/v1`, `/v2` or "Refactor" folders.

See [implementation examples](references/implementation.md) for detection scripts.

## 2. Detect Logic Leakage (by Ecosystem)

Find business logic trapped in the wrong layer.

- **Web (React/Next.js/Vue)**: `grep -rE "useEffect|useState|useMemo" components --include="*.tsx" | wc -l` — if `components/` hook count > 20x `hooks/` folder, architecture is monolithic.
- **Mobile (Flutter/React Native)**: `grep -rE "http\.|dio\.|socket\." lib/widgets --include="*.dart" | wc -l` — I/O or state mutation > 5 lines in `build()` is High Debt.
- **Backend (NestJS/Go/Spring)**: `grep -rE "Repository\.|Query\.|db\." src/controllers --include="*.ts" | wc -l` — Controllers must only handle request parsing and response formatting.

## 3. Identify Monoliths

Flag massive files violating Single Responsibility Principle.

- **UI**: > 500 lines (Medium), > 1,000 lines (Critical).
- **Backend Services**: > 1,500 lines indicates "God Class".

See [implementation examples](references/implementation.md) for monolith detection scripts.

## 4. Audit Resource Performance

Check for large metadata or constants impacting IDE performance and binary size.

- Resources > 1,000 lines require granulation.

See [implementation examples](references/implementation.md) for resource audit scripts.

## Scoring Impact

- **Layer Violation**: -15 per business logic instance in UI/Controller layer.
- **Structural Fragmentation**: -10 per duplicated legacy entity.
- **Monoliths**: -10 per unit > 1,000 lines.

## Anti-Patterns

- **No applying generic patterns over project-specific rules**: Respect existing architecture constraints.
- **No ignoring error handling or edge cases**: Audit must cover boundary conditions.

## References

- [Architecture Patterns & Remediation Protocols](references/PATTERNS.md)

Related Skills

spring-boot-architecture

385
from HoangNguyen0403/agent-skills-standard

Structure Spring Boot 3+ projects with feature packaging and clean layering. Use when structuring Spring Boot 3 projects, defining layers, or applying architecture patterns. (triggers: pom.xml, build.gradle, structure, layering, dto, controller, @RestController, @Service, @Repository, @Entity, @Bean, @Configuration)

react-native-architecture

385
from HoangNguyen0403/agent-skills-standard

Structure React Native projects with feature-first organization and separation of concerns. Use when structuring a React Native project or applying clean architecture patterns. (triggers: src/**/*.tsx, src/**/*.ts, app.json, feature, module, directory structure, separation of concerns, Expo, React Navigation, StyleSheet.create, react-native, mobile architecture)

nextjs-architecture

385
from HoangNguyen0403/agent-skills-standard

Structure Next.js projects with Feature-Sliced Design layers, domain-grouped slices, and strict import hierarchy. Use when organizing features into FSD layers, enforcing slice boundaries, or keeping page.tsx thin. (triggers: src/features/**, src/entities/**, src/widgets/**, FSD, Feature Sliced Design, slices, segments)

nestjs-architecture

385
from HoangNguyen0403/agent-skills-standard

Design decoupled, testable NestJS module boundaries with feature, core, and shared modules. Use when structuring module imports, creating feature modules, or enforcing separation of concerns in NestJS. (triggers: **/*.module.ts, main.ts, NestFactory, Module, Controller, Injectable)

laravel-clean-architecture

385
from HoangNguyen0403/agent-skills-standard

Implement Domain-Driven Design with typed DTOs, repository interfaces, and single-responsibility Action classes in Laravel. Use when creating domain folders, binding repository contracts in providers, or passing DTOs between layers. (triggers: app/Domains/**/*.php, app/Providers/*.php, domain, dto, repository, contract, adapter)

laravel-architecture

385
from HoangNguyen0403/agent-skills-standard

Enforce core architectural standards for scalable Laravel applications. Use when structuring controllers, service layers, action classes, Form Requests, or Service Container bindings in Laravel projects. (triggers: app/Http/Controllers/**/*.php, routes/*.php, controller, service, action, request, container)

ios-architecture

385
from HoangNguyen0403/agent-skills-standard

Apply MVVM, Coordinators, and Clean Architecture (VIP/VIPER) in iOS apps. Use when applying MVVM, Coordinators, or VIP/VIPER architecture in iOS apps. (triggers: **/*ViewModel.swift, **/*Coordinator.swift, **/*ViewController.swift, MVVM, Coordinator, ViewState, Output, Input)

golang-architecture

385
from HoangNguyen0403/agent-skills-standard

Structure Go projects with Clean Architecture and standard layout conventions. Use when structuring Go projects or applying Clean Architecture in Go. (triggers: go.mod, internal/**, architecture, structure, folder layout, clean arch, dependency injection)

flutter-layer-based-clean-architecture

385
from HoangNguyen0403/agent-skills-standard

Enforce inward dependency flow, pure domain layers, and DTO-to-entity mapping in Flutter DDD architecture. Use when structuring lib/domain/, lib/infrastructure/, lib/application/, or lib/presentation/ layers, defining repository interfaces, or wiring BLoCs with get_it. (triggers: lib/domain/**, lib/infrastructure/**, lib/application/**, dto, mapper, Either, Failure)

flutter-feature-based-clean-architecture

385
from HoangNguyen0403/agent-skills-standard

Organize Flutter apps with modular feature-based clean architecture. Use when creating or modifying any file under lib/features/ including domain entities, repositories, data sources, or screens. (triggers: lib/features/**, feature, domain, infrastructure, application, presentation)

common-observability

385
from HoangNguyen0403/agent-skills-standard

Enforce structured JSON logging, OpenTelemetry distributed tracing, and RED metrics across backend services. Use when adding request correlation, setting up tracing spans, defining SLO burn-rate alerts, or instrumenting middleware. (triggers: **/*.service.ts, **/*.handler.ts, **/*.middleware.ts, **/*.interceptor.ts, **/*.go, **/*.java, **/*.kt, **/*.py, logging, tracing, metrics, opentelemetry, observability, slo)

common-mobile-ux-core

385
from HoangNguyen0403/agent-skills-standard

Enforce universal mobile UX principles for touch-first interfaces including touch targets, safe areas, and mobile-specific interaction patterns. Use when building mobile screens, handling touch interactions, or validating safe area compliance. (triggers: **/*_page.dart, **/*_screen.dart, **/*_view.dart, **/*.swift, **/*Activity.kt, **/*Screen.tsx, mobile, responsive, SafeArea, touch, gesture, viewport)