Angular Clean Architecture

Angular Clean Architecture — Module System

When To Activate

• Creating a module under src/app/modules/
• Adding a use case, facade, store, port, or adapter to an existing module
• Wiring lazy routes + cached state
• Replacing session proxies with self-contained module adapters
• Creating standalone components that consume store state via facades
• Refactoring a legacy/mixed module (NgModule/NgRx) toward Clean Architecture
• Moving business logic out of components into facades/use-cases
• Adding or updating cross-module communication via the context registry

Relationship to Other Skills

Architecture Anchors (Verify Before Coding)

If anchors are missing: do NOT invent imports. Continue best-effort, report mismatch.

Architecture Overview

src/app/modules/{moduleName}/
├── presentation/            # list/ details/ create/ edit/ container pages, forms/, components/
├── application/
│   ├── facades/{moduleName}.facade.ts
│   ├── use-cases/{verb-noun}.use-case.ts
│   └── store/{moduleName}.store.ts      # flurryx Store.for<Config>().build()
├── core/                    # domain hexagon — ZERO infra/framework imports
│   ├── models/  ports/  rules/  mappers/  events/
├── infrastructure/
│   ├── adapters/{verb-noun}.adapter.ts
│   └── api/{endpoints/, request/, response/}
├── routes.ts                # lazy loadComponent + route-level providers
├── routes.constants.ts
├── {moduleName}-service.providers.ts    # SELF-REGISTRATION entrypoint
├── public-api.ts            # SYNC contract — composition root imports only, never module→module
└── integration-api.ts       # REACTIVE contract — composition root imports only, never module→module

Full layout with worked example: module-template.md.

Dependency Rules (CRITICAL)

Component --> Facade --> UseCase --> [Port] <-- Adapter --> Endpoint --> HttpClient
    |            |           |          ^           |
Presentation  Application  Application   Core     Infrastructure

• Core has ZERO infrastructure or framework dependencies — no Angular, no HttpClient, no flurryx. Only models (types), ports (abstract classes), rules (pure functions), mappers.
• Application depends on Core only — facades orchestrate use cases + store; use cases call ports.
• Infrastructure depends on Core only — adapters implement ports using HTTP clients.
• Components NEVER inject use cases or stores directly — always inject facades.
• Modules NEVER import modules — a file under src/app/modules/<A>/** never imports from src/app/modules/<B>/**, not even public-api.ts/integration-api.ts. Capabilities go through context-registry ports in core/; types are local ACL copies. Only the composition root (core/**, app.config.ts, app.routes.ts, layout shell) imports module contracts. See cross-domain.md.

Root Store vs Route Providers (Caching Mechanism)

• Store is providedIn: 'root' (flurryx default) → survives navigation = the cache.
• Facades, use cases, adapters are route-scoped → disposed on leave.
• @SkipIfCached prevents re-fetch when returning to a cached route.
• Optional sessionStorage/localStorage channels for reload/tab survival.
• clearAllStores() on logout/tenant switch.

Store System

flurryx provides event-sourced, replayable signal state. This skill does NOT restate its API.

• API reference (Store builder, syncToStore, decorators, channels, history): [[flurryx]]
• Wiring cheat-sheet (how stores plug into modules): store-system.md
• Conceptual ES/CQRS → Angular mapping: [[angular-ddd]] event-sourcing-mapping

Session-Proxy Replacement

Legacy *Proxy classes + shared god-stores are replaced by self-contained module adapters with @SkipIfCached(CACHE_NO_TIMEOUT) + optional session-storage channel, consumed by PORT via context registry.

Full before/after migration: session-proxy-migration.md.

Hard Rules

• Never use any — use unknown if the type is truly unknown
• Never inject UseCase classes directly into components — always go through a Facade
• Never inject stores directly into components — facades expose store signals
• Never import flurryx, Angular, or HttpClient in core/
• Never deep-climb relative imports (../../...) — use the @/ path alias (see Import Conventions)
• Never import from another module — a file under src/app/modules/<A>/** never imports from src/app/modules/<B>/**, not even public-api.ts/integration-api.ts. Capabilities via context-registry ports, types via local ACL copies (see cross-domain.md)
• Never re-fetch reference data without @SkipIfCached
• Never inject a concrete adapter/proxy across modules — inject the port
• Components must depend on facades for ALL domain interactions
• Use inject() for all dependencies, never constructor params
• Domain modeling patterns (entity, VO, aggregate) → [[angular-ddd]], not here

Layer Implementation Templates

For full templates with code: See layer-templates.md.

Cross-Module Communication

Modules never import modules — not even another module's public-api.ts/integration-api.ts. Capabilities: port contract in core/ + provider adapter + context-registry binding. Types: local ACL copies, never shared. For full patterns: See cross-domain.md.

Testing Patterns

For full testing patterns by layer: See testing-patterns.md.

Target 80%+ coverage.