Version: 1.0.0
Last Updated: 2026-01-15
Compatible with: Saberloop v2.0.0+
Architecture Compliance
**Version:** 1.0.0
Architecture Compliance by diegosouzapw · 28c0354
npx get-skill add diegosouzapw/architecture-compliance File contents
---name: architecture-compliancedescription: Ensure code follows strict layer boundaries and dependency rulesversion: 1.0.0author: Saberloop Projectusage: | Use this skill for architecture-related tasks: - Validating new module placement against layer boundaries - Checking dependency rule compliance - Generating dependency graphs for visualization - Identifying and fixing circular dependencies - Architectural refactoring to improve layer separation Examples: "Validate new service architecture using the architecture-compliance skill" "Check dependency rules for new component using the architecture-compliance skill" "Fix architecture violations using the architecture-compliance skill"# Architecture Compliance Validation Skill## OverviewThis skill ensures code follows Saberloop's strict layer boundaries and dependency rules as enforced by dependency-cruiser, maintaining clean architecture and preventing technical debt accumulation.## Architecture Layers### Layer Definitions| Layer | Directory | Purpose | Allowed Dependencies ||--------|------------|---------|-------------------|| Views | `src/views/` | UI components, Services, Core utilities, State || Components | `src/components/` | Core utilities, State || Services | `src/services/` | API layer, Database, Core utilities || API | `src/api/` | Core utilities || Core | `src/core/` | External libraries only |### Dependency Flow```┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐│ Views │───▶│ Components │───▶│ Services │└─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ API │ │ ▼ └─────────────────┘ │ ┌─────────────────┐ │ │ │ Services │◀───────────────┤ ▼ └─────────────────┘ │┌─────────────────┐ │ ││ Core │◀───────────────────────┤ ▼└─────────────────┘ │ ┌─────────────────┐ │ │ Core Utils │ │ └─────────────────┘ ▼ ┌─────────────────┐ │ External Libs │ └─────────────────┘```## When to Use This SkillUse this skill when ANY of these are true:- [ ] Adding new modules or files- [ ] Refactoring existing code- [ ] Moving code between layers- [ ] Adding new dependencies- [ ] Architecture violations detected- [ ] Planning major refactoring## Architecture Rules### Enforced Rules (from `.dependency-cruiser.cjs`)#### Immediate Enforcement (Errors)| Rule | Description | Violation Example ||-------|-------------|------------------|| `no-view-to-view` | Views should not import other views (except BaseView) | `import HomeView from './HomeView.js'` || `views-should-not-import-db` | Views must use services layer instead of direct db access | `import { saveTopic } from '@/core/db.js'` || `components-should-not-import-api` | Components should be presentational, receive callbacks as props | `import { apiCall } from '@/api/'` || `api-should-not-import-db` | API layer should receive credentials as parameters | `import { getDb } from '@/core/db.js'` |### Additional Best Practices#### Import Patterns**Correct:**```javascript// Views using servicesimport { quizService } from '@/services/quiz-service.js';// Services using APIimport { generateQuiz } from '@/api/api.real.js';// Core utilities only using external libsimport { openDB } from 'idb';```**Incorrect:**```javascript// Views importing API (skip service layer)import { generateQuiz } from '@/api/api.real.js';// Services importing other services directlyimport { otherService } from '@/services/other-service.js';// API accessing database directlyimport { saveQuiz } from '@/core/db.js';```#### Layer Boundary Patterns| Layer | Should Import | Should Not Import ||-------|----------------|-------------------|| Views | Services, Components, Core, State | API, Database, Other Views || Components | Core, State | Services, API, Database || Services | API, Core, Database | Views, Other Services || API | Core | Database, Services, Views || Core | External libraries only | Internal layers |## Compliance Validation Process### Step 1: Current State Analysis```bash# Run architecture validationnpm run arch:test# Generate dependency graphnpm run arch:graph# Check for circular dependenciesnpm run arch:test | grep -i circular# Analyze specific filenpx depcruise src/views/QuizView.js --output-type dot```### Step 2: Identify Violations#### Common Violation Patterns1. **View Importing API Directly**```javascript// VIOLATIONimport { generateQuiz } from '@/api/api.real.js';export default class QuizView extends BaseView { async createQuiz() { const quiz = await generateQuiz(topic); // Direct API access }}```2. **Component Making API Calls**```javascript// VIOLATIONimport { fetchQuiz } from '@/api/api.real.js';export function QuizComponent() { const [quiz, setQuiz] = useState(null); useEffect(() => { fetchQuiz().then(setQuiz); // API call in component }, []);}```3. **API Accessing Database**```javascript// VIOLATIONimport { saveQuiz } from '@/core/db.js';export async function generateQuiz(topic) { const quiz = createQuizData(topic); await saveQuiz(quiz); // Direct DB access return quiz;}```### Step 3: Fix Architecture Violations#### Fix Pattern 1: Views → Services → API```javascript// BEFORE (Violation)import { generateQuiz } from '@/api/api.real.js';export default class QuizView extends BaseView { async createQuiz() { const quiz = await generateQuiz(topic); }}// AFTER (Compliant)import { quizService } from '@/services/quiz-service.js';export default class QuizView extends BaseView { async createQuiz() { const quiz = await quizService.generateQuiz(topic); }}// In quiz-service.jsimport { generateQuiz } from '@/api/api.real.js';export const quizService = { async generateQuiz(topic) { return await generateQuiz(topic); }};```#### Fix Pattern 2: Components → Props/Callbacks```javascript// BEFORE (Violation)import { fetchQuiz } from '@/api/api.real.js';export function QuizComponent({ topic }) { const [quiz, setQuiz] = useState(null); useEffect(() => { fetchQuiz(topic).then(setQuiz); }, [topic]);}// AFTER (Compliant)export function QuizComponent({ topic, onQuizGenerated }) { const [quiz, setQuiz] = useState(null); useEffect(() => { onQuizGenerated(topic).then(setQuiz); }, [topic, onQuizGenerated]);}// Parent provides API accessimport { fetchQuiz } from '@/services/quiz-service.js';export function ParentComponent() { const handleQuizGenerated = async (topic) => { return await fetchQuiz(topic); }; return <QuizComponent topic="science" onQuizGenerated={handleQuizGenerated} />;}```#### Fix Pattern 3: API → Parameter Passing```javascript// BEFORE (Violation)import { saveQuiz } from '@/core/db.js';export async function generateQuiz(topic) { const quiz = createQuizData(topic); await saveQuiz(quiz); // Direct DB access return quiz;}// AFTER (Compliant)export async function generateQuiz(topic, dbConnection = null) { const quiz = createQuizData(topic); // Accept DB connection as parameter if (dbConnection) { await dbConnection.save(quiz); } return quiz;}// Service layer provides DB connectionimport { getDatabase } from '@/core/db.js';export const quizService = { async generateQuiz(topic) { const db = await getDatabase(); return await generateQuiz(topic, db); }};```### Step 4: Validation and Testing```bash# Re-run architecture validationnpm run arch:test# Should show no violations# ✅ No dependency rule violations found# Check specific patternsnpx depcruise src/ --config .dependency-cruiser.cjs --output-type err# Generate updated graphnpm run arch:graphdot -Tpng dependency-graph.dot -o architecture-fixed.png```## Advanced Architecture Patterns### Service Layer Design#### Proper Service Structure```javascript// src/services/quiz-service.jsimport { generateQuiz } from '@/api/api.real.js';import { saveQuiz, loadQuiz } from '@/core/db.js';import { logger } from '@/utils/logger.js';export const quizService = { // High-level operations async createQuiz(topic, options = {}) { logger.info('Creating quiz', { topic, options }); try { const quiz = await generateQuiz(topic, options); await saveQuiz(quiz); return quiz; } catch (error) { logger.error('Quiz creation failed', { topic, error }); throw error; } }, async loadQuiz(id) { const quiz = await loadQuiz(id); logger.debug('Quiz loaded', { id, questions: quiz?.questions?.length }); return quiz; }, // Business logic validation validateQuiz(quiz) { if (!quiz.questions || quiz.questions.length === 0) { throw new Error('Quiz must have at least one question'); } if (quiz.questions.length > 20) { throw new Error('Quiz cannot have more than 20 questions'); } return true; }};```#### Dependency Injection Pattern```javascript// Allow services to receive dependenciesexport class QuizService { constructor(apiClient, database, logger) { this.api = apiClient; this.db = database; this.logger = logger; } async createQuiz(topic) { this.logger.info('Creating quiz', { topic }); const quiz = await this.api.generateQuiz(topic); await this.db.saveQuiz(quiz); return quiz; }}// Factory for creating servicesexport function createQuizService() { return new QuizService( apiReal, getDatabase(), logger );}```### Component Design Patterns#### Presentational Components```javascript// Only handle UI, receive data via propsexport function QuizCard({ quiz, onQuizStart, onQuizShare, isDisabled = false }) { return ( <div className="quiz-card" data-testid="quiz-card"> <h3>{quiz.title}</h3> <p>{quiz.description}</p> <div className="quiz-actions"> <button onClick={() => onQuizStart(quiz.id)} disabled={isDisabled} data-testid="start-quiz-btn" > Start Quiz </button> <button onClick={() => onQuizShare(quiz.id)} data-testid="share-quiz-btn" > Share </button> </div> </div> );}// Container component handles logicimport { quizService } from '@/services/quiz-service.js';export function QuizContainer({ quizId }) { const [quiz, setQuiz] = useState(null); useEffect(() => { quizService.loadQuiz(quizId).then(setQuiz); }, [quizId]); const handleStart = () => { // Navigate to quiz }; const handleShare = () => { // Share quiz }; return quiz ? ( <QuizCard quiz={quiz} onQuizStart={handleStart} onQuizShare={handleShare} /> ) : null;}```## Dependency Analysis Tools### Using Dependency Cruiser```bash# Full analysisnpx depcruise src/ --config .dependency-cruiser.cjs --output-type html# Specific directorynpx depcruise src/views/ --config .dependency-cruiser.cjs# Specific file with detailsnpx depcruise src/views/QuizView.js --config .dependency-cruiser.cjs --output-type err# Custom focusnpx depcruise src/ --config .dependency-cruiser.cjs --focus "src/views"```### Visualizing Architecture```bash# Generate DOT graphnpm run arch:graph# Convert to PNG (requires graphviz)dot -Tpng dependency-graph.dot -o architecture.png# Convert to SVG for webdot -Tsvg dependency-graph.dot -o architecture.svg# Focus on specific modulenpx depcruise src/ --config .dependency-cruiser.cjs --output-type dot | dot -Tpng -o focused-architecture.png```### Circular Dependency Detection```bash# Find circular dependenciesnpm run arch:test | grep -A5 -B5 "circular"# Visualize cyclesnpx depcruise src/ --config .dependency-cruiser.cjs --output-type dot | dot -Tpng -o cycles.png# Fix by extracting common interface// Create shared interface// src/core/interfaces.jsexport const EventEmitter = { on(event, handler) { /* ... */ }, emit(event, data) { /* ... */ }};```## Migration Strategies### Legacy Code Migration#### Step 1: Identify Violations```bash# Find all files with violationsnpx depcruise src/ --config .dependency-cruiser.cjs --output-type json > violations.json# Analyze patternsjq '.violations[].rule' violations.json | sort | uniq -c```#### Step 2: Plan Refactoring```markdown## Migration Plan: [Module Name]### Current Issues- [ ] View importing API directly: [files]- [ ] Component making service calls: [files]- [ ] Service coupling: [files]### Refactoring Steps1. Extract business logic to services2. Create service interfaces3. Update views to use services4. Update components to be presentational5. Add dependency injection where needed```#### Step 3: Incremental Migration```javascript// Phase 1: Add service layer (keep old code)import { legacyAPICall } from './legacy.js';import { newService } from '@/services/new-service.js';export default class QuizView extends BaseView { async createQuiz() { // Use new service for new features if (this.isNewFlow) { return await newService.createQuiz(this.topic); } // Keep legacy for old flow return await legacyAPICall(this.topic); }}// Phase 2: Migrate all callers// Phase 3: Remove legacy code```## Quality Metrics### Architecture Health Indicators| Metric | Target | How to Measure ||--------|--------|-----------------|| Dependency rule violations | 0 | `npm run arch:test` || Circular dependencies | 0 | Dependency cruiser output || Layer coupling | Low | Dependency graph analysis || Service layer coverage | 100% | All API calls through services || Component purity | High | No API calls in components |### Automated Checks```javascript// In CI/CD pipeline"arch:test": "depcruise src/ --config .dependency-cruiser.cjs --output-type err --max-depth 10","arch:validate": "npm run arch:test && echo '✅ Architecture compliance passed' || echo '❌ Architecture violations found'",```## Integration with Other SkillsThis skill integrates with:- **epic-hygiene-process** - For architecture compliance fixes during hygiene- **testing-suite-management** - For testing architecture fixes- **pwa-feature-development** - For validating new feature architecture- **feature-flag-management** - For architectural impact of flag changesmetadata: source: https://skillmd.com/skills/diegosouzapw/architecture-compliance---**Version:** 1.0.0 **Last Updated:** 2026-01-15 **Compatible with:** Saberloop v2.0.0+
diegosouzapw/awesome-omni-skill commit 28c0354768
Frequently asked questions
Run npx get-skill add diegosouzapw/architecture-compliance in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
**Version:** 1.0.0 It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
diegosouzapw (@diegosouzapw) published this skill. Their other Agent Skills are listed on their SkillMD profile.