---

name: architecture-guidelines description: System architecture: modules, project structure, ADRs, and testing. Use when designing or reviewing systems.

Architecture Guidelines

Guidelines for system design, project structure, and architectural decisions.

Quick Start

Copy// Use ES Modules with explicit extensions
import * as path from "@std/path";
import { readFile } from "./utils.ts";

export function processFile() {}

Key Principles

• Use ES Modules (avoid CommonJS/AMD)
• Follow consistent directory structure with kebab-case directories
• Document architectural decisions with ADRs including trade-offs
• Write automated tests with CI (target 80%+ coverage for critical paths)
• Use naming conventions: PascalCase for components, camelCase for utilities
• Hexagonal architecture: domain + ports together, adapters separate
• Explicit composition only: import adapters directly, pass as parameters (no magic config strings, no convenience factories)

References

See rules.md for complete guidelines with examples.