modular-architecture

name	modular-architecture
description	Enforces modular domain architecture and clean code standards. Use when creating or refactoring packages, domains, components, services, models, and tests in packages/*.

Modular Domain Architecture Standards

This skill defines enforceable architecture and coding rules for Angular libraries to keep the codebase maintainable, scalable, and predictable.

1. Scope

Apply this skill to changes in:

• packages/*/src/lib/**
• Domain-level TypeScript implementation and tests (*.ts)
• Architecture decisions about component/service/model boundaries

Do not apply this skill to generated artifacts, coverage output, or unrelated tooling files.

2. Rule Priority and Conflict Resolution

When rules conflict, apply this order:

1. Correctness and build/test stability
2. Public API compatibility (unless migration is explicitly requested)
3. Architecture boundaries (layer responsibilities and dependency direction)
4. Naming and folder conventions
5. Style preferences

If a lower-priority rule conflicts with a higher-priority rule, follow the higher-priority rule and note the exception in your response.

3. Mandatory Rules

3.1 Layer Responsibilities

• Components: UI rendering and interaction orchestration only.
• Services: business logic, data access orchestration, domain operations.
• Models/Interfaces: domain contracts and typed data shapes.
• Utilities: pure reusable helpers with no UI coupling.

Components must not contain complex business logic if that logic can live in a service.

3.2 Dependency Direction

• UI layer can depend on services and models.
• Services can depend on models and utilities.
• Services must not depend on component classes.
• Avoid circular dependencies across domains.

3.3 Type Safety

• Explicitly type function inputs and outputs for exported APIs.
• Do not introduce any in new code. If unavoidable for external APIs, use unknown and narrow.
• Use readonly for immutable class members and object properties when mutation is not needed.

3.4 Naming and Searchability

Use singular domain-prefixed filenames:

• [domain].service.ts
• [domain].component.ts
• [domain].model.ts or [domain].interface.ts
• [domain].spec.ts or [domain].service.spec.ts

Keep names intent-revealing and consistent with existing package terminology.

4. Preferred Patterns

• Prefer standalone components/directives/pipes for new UI features.
• Use NgModule only for legacy integration points or third-party requirements.
• Keep components thin by delegating non-UI logic to services.
• Prefer composition and dependency injection over inheritance-heavy designs.

5. Decision Rules (If-Then)

1. If creating a new UI feature in a domain, use a standalone component by default.
2. If feature logic spans multiple components, create or extend a domain service.
3. If shared logic is domain-agnostic and pure, move it to a utility in a shared package.
4. If an interface exceeds one responsibility, split it into smaller focused interfaces.
5. If a change risks breaking public exports, preserve the existing API or provide a migration path.

6. Exceptions Policy

Allowed exceptions:

• Legacy module-based areas that are already module-centric.
• Third-party integration constraints requiring module registration.
• Transitional refactors where a follow-up task is required.

For every exception, document briefly:

1. Which rule was bypassed
2. Why it was necessary
3. Recommended follow-up action

7. Anti-Patterns to Avoid

• Fat components containing domain/business logic.
• Services returning untyped any payloads without narrowing.
• Domain code coupled to UI framework details when a service abstraction is possible.
• New files that ignore the domain-prefix naming convention.
• Copy-paste logic that should be extracted to common or utils packages.

8. Minimal Domain Layout

packages/[package]/
  src/
    lib/
      [domain]/
        [domain].component.ts
        [domain].service.ts
        [domain].model.ts
        [domain].interface.ts
        [domain].spec.ts

Adjust file set per feature needs, but preserve domain-prefix naming and layer boundaries.

9. Pre-Response Self-Checklist

Before finalizing a change, verify:

1. Are responsibilities split correctly between component/service/model?
2. Are dependency directions valid and non-circular?
3. Was any avoided in new code?
4. Do new files follow domain-prefix naming?
5. Is duplicated logic extracted where practical?
6. Are tests added or updated for behavior changes?
7. Were exceptions documented when standards could not be followed?