vault-architecture

name	vault-architecture
description	Enforce clean architecture patterns in any project. Activates when the user says "architecture review", "check my patterns", "enforce architecture", "review structure", "observer pattern", "repository pattern", "dependency injection", "DI pattern", "event-driven", "composition over inheritance", "code quality check", "pattern review", "architecture audit", "clean architecture", "SOLID principles", or invokes /vault-architecture. Reads project.config.json for project-specific enforcement. Ensures Observer, Repository, DI, and Composition patterns are followed consistently.
allowed-tools	["Read","Grep","Glob"]
user-invocable	true
argument-hint	[file-or-directory] [--fix]

// vault-architecture SKILL.md / Developer: Marcus Daley / 2026-02-27 // Architecture enforcement skill for Claude Code // Enforces Observer, Repository, DI, and Composition patterns across projects // Reads project.config.json for project-specific customization (95/5 rule)

Architecture Pattern Enforcement

Audit and enforce clean architecture patterns in any project. This skill reads project.config.json to customize enforcement per project while applying universal patterns across all codebases.

Quick Start

/vault-architecture                    # Audit entire project
/vault-architecture server/            # Audit server directory only
/vault-architecture server/routes.ts   # Audit a single file
/vault-architecture --fix              # Audit + suggest fixes

Step 1: Load Project Config

Read project.config.json from the project root. This file tells you:

• Which architecture patterns the project uses
• Which DI strategy (manual, container)
• Which database and ORM
• Which transport mode (SSE, WebSocket, IPC)

If project.config.json does not exist, apply all patterns universally and note that the project should create one.

Step 2: Pattern Audit

Check the codebase against these four core patterns. Every project must follow all four.

Pattern 1: Observer / Delegate (NEVER Poll)

// WHY: Polling wastes resources and creates race conditions. // The Observer pattern ensures consumers react to state changes immediately. // This matches UE5 DECLARE_DYNAMIC_MULTICAST_DELEGATE conventions.

Violations to detect:

Anti-Pattern	What To Flag
setInterval with fetch/query	Timer-based state polling
refetchInterval in React Query	Polling disguised as "smart" refetch
setTimeout + recursive fetch	Manual polling loop
Repeated GET requests on a timer	Network polling
Busy-wait loops	CPU-wasting state checks

Correct patterns:

Context	Pattern
Server → Client real-time	EventEmitter → SSE endpoint → EventSource
Cross-service communication	EventBus singleton with typed events
React state from server	SSE event → React Query cache invalidation
Component-to-component	React context, callback props, or custom hooks
UE5 equivalent	DECLARE_DYNAMIC_MULTICAST_DELEGATE

Audit checklist:

1. Search for setInterval, refetchInterval, setTimeout used for data fetching
2. Verify all real-time data flows through an event bus or equivalent
3. Confirm SSE/WebSocket consumers invalidate cache, not re-fetch on timer
4. Check that EventEmitter listeners are properly cleaned up (unsubscribe on disconnect)

Pattern 2: Repository (Centralized Data Access)

// WHY: Raw SQL or ORM calls scattered through route handlers create // maintenance nightmares and make it impossible to audit data access. // All database operations go through a single storage interface.

Violations to detect:

Anti-Pattern	What To Flag
db.select() in route handler	Direct ORM in business logic
db.insert() outside storage	Scattered write operations
Raw SQL strings in routes	SQL outside repository layer
Inline query construction	Missing abstraction

Correct pattern:

// All database access through a typed interface
// Route handlers call storage methods, never touch the database directly
interface IStorage {
  getDocuments(): Promise<Document[]>;
  createDocument(doc: InsertDocument): Promise<Document>;
  // ... all database operations centralized here
}

// Route handler (correct)
app.get("/api/documents", async (req, res) => {
  const docs = await storage.getDocuments();  // Repository call
  res.json(docs);
});

// Route handler (VIOLATION)
app.get("/api/documents", async (req, res) => {
  const docs = await db.select().from(documents);  // Direct ORM call
  res.json(docs);
});

Audit checklist:

1. Search route handlers for direct database/ORM calls
2. Verify a storage/repository interface exists
3. Check that all CRUD operations go through the repository
4. Confirm mutations are logged (audit trail)

Pattern 3: Dependency Injection (Explicit Wiring)

// WHY: Hidden dependencies (global imports, singletons without interfaces) // make code untestable and tightly coupled. DI makes dependencies visible. // Manual DI via constructor injection is preferred at small-to-medium scale.

Violations to detect:

Anti-Pattern	What To Flag
import { db } from "../db" in 10 files	Hardcoded singleton dependency
new Service() inside another service	Hidden construction
Global mutable state	Shared state without injection
Circular imports for shared state	Dependency cycle smell

Correct pattern (manual DI):

// Dependencies injected through constructor or factory function
class ExtractionManager {
  constructor(
    private storage: IStorage,
    private eventBus: ExtractionEventBus,
    private downloadQueue: DownloadQueue
  ) {}
}

// Wiring happens at composition root (server/index.ts)
const storage = new DatabaseStorage(db);
const eventBus = ExtractionEventBus.getInstance();
const queue = new DownloadQueue();
const manager = new ExtractionManager(storage, eventBus, queue);

Audit checklist:

1. Check for classes that construct their own dependencies internally
2. Verify composition root exists (where all services are wired together)
3. Look for circular import chains
4. Confirm services depend on interfaces, not concrete implementations (where practical)

Pattern 4: Composition Over Inheritance

// WHY: Deep inheritance hierarchies create brittle, hard-to-modify code. // Prefer composing behaviors via interfaces, mixins, or strategy pattern. // Exception: React components extending base is fine (framework convention).

Violations to detect:

Anti-Pattern	What To Flag
class A extends B extends C	Deep inheritance chain
super.method() called 3+ levels deep	Fragile base class
Abstract class with 10+ methods	God class via inheritance
instanceof checks for branching	Type-switch smell

Correct patterns:

Instead Of	Use
Deep class hierarchy	Interface + composition
Abstract base with many methods	Small focused interfaces
instanceof branching	Strategy pattern or polymorphism
Mixins via extends	Functional composition

Audit checklist:

1. Search for extends and check inheritance depth
2. Look for super. calls — more than 2 levels is a smell
3. Check for instanceof used for control flow
4. Verify interfaces are small and focused (Interface Segregation)

Step 3: Project-Specific Checks

Based on project.config.json, apply additional checks:

If architecture.patterns includes "sse-push":

• Verify SSE endpoint exists and follows the EventBus → SSE → Client flow
• Check for proper SSE headers (Content-Type, Cache-Control, Connection)
• Confirm heartbeat interval matches transport.heartbeatInterval config
• Verify client uses native EventSource (not a polling library)

If architecture.patterns includes "event-bus":

• Verify EventBus is a singleton
• Check that all event types are typed (not any)
• Confirm listener cleanup on disconnect
• Verify max listener count is set appropriately

If architecture.database is "sqlite":

• Check that WAL mode is enabled for concurrent reads
• Verify no raw SQL outside the repository layer
• Confirm Drizzle ORM is used (if architecture.orm is "drizzle")

If security.localFirst is true:

• Flag any outbound HTTP calls that are not to allowed destinations
• Verify no analytics, telemetry, or tracking code
• Confirm CSP headers are set if security.csp is true

Step 4: Report

Generate a structured report:

## Architecture Audit Report

### Summary
- Files scanned: N
- Violations found: N
- Patterns checked: Observer, Repository, DI, Composition

### Violations

#### [PATTERN] Violation in file:line
**What**: Description of the violation
**Why it matters**: Impact on maintainability/security/performance
**Fix**: Specific code change to resolve

### Passing Checks
- [x] Observer pattern — no polling detected
- [x] Repository pattern — all DB access through storage
- [ ] DI pattern — 2 violations found
- [x] Composition — no deep inheritance

### Recommendations
1. Priority fixes (violations)
2. Improvement suggestions (not violations, but could be better)

Coding Standards Enforcement

In addition to architecture patterns, enforce these coding standards:

// Marcus Daley's coding standards — applies to ALL projects

Rule	Check
Line comments only	Flag any /* */ or /** */ block comments
File headers	Every source file needs: // FileName / Developer: Marcus Daley / Date / Description
Function documentation	Every function needs // comment block: purpose, params, returns, usage
WHY not WHAT	Comments should explain design decisions, not restate code
No hardcoded gameplay types	Flag hardcoded enums that should be config-driven (UE5 rule, applies broadly)

Reference Documents

For detailed pattern guides:

• Observer pattern: references/observer-pattern.md
• Repository pattern: references/repository-pattern.md
• DI patterns: references/di-patterns.md
• Project config spec: references/project-config-spec.md