Early Return Pattern: Always use early returns when possible over nested conditions.
Decompose Components: Break down components longer than 80 lines and split files larger than 200 lines.
Library-First Approach:
- ALWAYS search for existing solutions before writing custom code.
- Use libraries for common problems (retry logic, state management, validation).
Clean Architecture & DDD:
- Separate domain entities from infrastructure. Keep business logic independent of frameworks.
Naming & Bounded Contexts:
- AVOID generic names (utils, helpers, common, shared).
- USE domain-specific names (OrderCalculator, InvoiceGenerator).
Separation of Concerns:
- Do NOT mix business logic with UI components.
- Keep database queries out of controllers.
SOLID Principles:
- Single Responsibility: A class should have one reason to change. Decompose large monoliths.
- Open/Closed: Design for extension without modifying existing source code (e.g., plugins, inheritance).
- Liskov Substitution: Subclasses must be interchangeable with their base classes.
- Interface Segregation: Prefer many specific interfaces over one general-purpose interface.
- Dependency Inversion: Depend on abstractions (interfaces/abstract classes), not concrete implementations.

Anti-Patterns to Avoid

NIH (Not Invented Here) Syndrome: Don't build custom auth when Auth0 exists.
Dumping Grounds: Don't create utils.js or shared.js with lots of unrelated functions. Every module should have a single, clear purpose.

Architecture Decision Records (ADRs)

Document every architectural decision with trade-offs. If making a significant decision, use the following framework:

ADR Template

# ADR-[XXX]: [Decision Title]

## Status
Proposed | Accepted | Deprecated | Superseded by [ADR-YYY]

## Context
- **Problem**: [What problem are we solving?]
- **Constraints**: [Team size, scale, timeline, budget]

## Options Considered
| Option | Pros | Cons | Complexity |
|--------|------|------|------------|
| Opt A  | ...  | ...  | Low/High   |

## Decision
[What we chose - be specific]

## Rationale
[Why - tie to requirements and constraints]

## Consequences
- **Positive**: [Benefits we gain]
- **Negative**: [Costs/risks we accept]
- **Mitigation**: [How we'll address negatives]

## Revisit Trigger
- [When to reconsider this decision]

Storage

Store these records sequentially in docs/architecture/ (e.g., adr-001-use-nextjs.md).

software_architecture

Software Architecture

Core Rules & Principles