Architecture Pattern Enforcement

• 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:

Correct patterns:

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:

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:

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:

Correct patterns:

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

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