Facade Layer Skill

Purpose

This skill enforces the project facade layer coding conventions automatically during business logic development. It ensures consistent patterns for transaction handling, error management, cache integration, query coordination, and cross-service orchestration with Sentry monitoring.

Activation

This skill activates when:

• Creating new facade files in

  src/lib/facades/

• Modifying existing facade files (

  .facade.ts

  )
• Implementing business logic that coordinates multiple queries
• Working with database transactions
• Coordinating between multiple services or facades

Workflow

1. Detect facade work (file path contains

   facades/

   or class name ends with

   Facade

   )
2. Load

   references/Facade-Layer-Conventions.md

3. Generate/modify code following all conventions
4. Scan for violations of facade patterns
5. Auto-fix all violations (no permission needed)
6. Report fixes applied

Key Patterns (REQUIRED)

Naming Conventions (Strict)

• ALL async methods MUST use

  Async

  suffix (e.g.,

  createAsync

  ,

  updateAsync

  ,

  deleteAsync

  ,

  getByIdAsync

  )
• No exceptions - this ensures consistent API across all facades

Structure Requirements

• Use static class methods (no instantiation needed)
• Define

  const facadeName = '{Domain}Facade'

  at file top for error context
• Accept optional

  DatabaseExecutor

  (

  dbInstance?: DatabaseExecutor

  ) as last parameter
• Create appropriate query context (

  createProtectedQueryContext

  ,

  createUserQueryContext

  ,

  createPublicQueryContext

  ,

  createAdminQueryContext

  )

QueryContext and Automatic Filtering (IMPORTANT)

• Context drives filtering: Query methods automatically apply permission and soft-delete filters based on context flags
• Trust query methods: Don't manually add filters that queries handle via

  buildBaseFilters()

• Context factories set flags:

  createPublicQueryContext()

  sets

  isPublic: true

  , etc.
• Override when needed: Pass

  shouldIncludeDeleted: true

  for admin restore features

Transaction Requirements (MANDATORY for mutations)

• ALL multi-step mutations MUST use transactions:

  (dbInstance ?? db).transaction(async (tx) => { ... })

• Pass transaction executor (

  tx

  ) to all nested query calls
• Single-step reads do NOT need transactions

Caching Requirements (MANDATORY)

• ALL read operations MUST use domain-specific CacheService (

  CacheService.bobbleheads.byId()

  , etc.)
• ALL write operations MUST invalidate cache via

  CacheRevalidationService

• Never use generic

  CacheService.cached()

  when domain helper exists

Error Handling (MANDATORY)

• ALL methods MUST wrap in try-catch with

  createFacadeError(errorContext, error)

• Use consistent return patterns (see Return Type Decision Matrix in conventions)

Sentry Monitoring (MANDATORY)

• Use

  withFacadeBreadcrumbs()

  wrapper to add automatic entry/success/error breadcrumbs (recommended)
• Alternatively, use

  trackFacadeEntry()

  and

  trackFacadeSuccess()

  for manual control
• Use

  trackFacadeWarning()

  for non-critical failures that shouldn't fail the operation
• Use

  captureFacadeWarning()

  to capture non-critical exceptions with proper tags and warning level
• Never fail main operations due to monitoring failures

Documentation Requirements (MANDATORY)

• ALL public methods MUST have JSDoc with:
  • Description of what the method does

  • @param

    for each parameter

  • @returns

    describing the return value
  • Cache behavior notes (TTL, invalidation triggers)

Method Complexity Limits

• Methods should not exceed 50-60 lines
• Extract helpers for complex transformations
• Use

  Promise.all

  for parallel independent data fetching

Anti-Patterns to Detect and Fix

1. Missing

   Async

   suffix on async methods
2. Missing transactions on multi-step mutations
3. Missing cache invalidation after write operations
4. Missing Sentry breadcrumbs in facade methods
5. Missing JSDoc documentation on public methods
6. Stub/incomplete methods that return hardcoded values
7. Duplicate methods with different naming (e.g.,

   getX

   and

   getXAsync

   )
8. Silent failures that log errors but don't handle them properly
9. Raw SQL/Drizzle queries in facades - delegate to query classes that handle soft-delete
10. Wrong operation constants - use semantically correct operations (add new ones if needed)
11. Hardcoded cache keys - use

    CACHE_KEYS.*

    constants
12. Mixed executor/context usage - use single shared context for parallel queries
13. Breadcrumbs only inside cache callbacks - add pre-operation breadcrumb outside for visibility

References

• references/Facade-Layer-Conventions.md

  - Complete facade layer conventions