ankhbayar/Assist_Design
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity
Assist_Design/docs/development/domain/import-hygiene.md
barsa a3dbd07183 Enhance ESLint Rules and Refactor Domain Imports 
- Updated ESLint configuration to enforce stricter import rules for the @customer-portal/domain package, promoting better import hygiene and preventing deep imports.
- Refactored various files across the BFF and portal applications to comply with the new import rules, ensuring that only the appropriate modules are imported from the domain.
- Cleaned up unused imports and optimized code structure for improved maintainability and clarity.
- Updated documentation to reflect changes in import practices and domain structure.
2025-12-26 14:53:03 +09:00

2.2 KiB
Raw Blame History

Import Hygiene Guide (Domain)

Principles

  • No deep imports: internal file layout is not part of the contract.
  • Barrels define the public API: if it’s not exported from the entrypoint, it’s not public.
  • Providers are integration-only: Portal must never import provider adapters/types.

Allowed import levels

  • Default (Portal + BFF):
    • @customer-portal/domain/<module>
    • @customer-portal/domain/toolkit
  • BFF-only (integration/infrastructure):
    • @customer-portal/domain/<module>/providers

Never

  • @customer-portal/domain/<module>/** (anything deeper than the module entrypoint)
  • @customer-portal/domain/<module>/providers/** (anything deeper than /providers)
  • apps/portal/** importing any @customer-portal/domain/*/providers

Rule of thumb

Import from the highest stable entrypoint that contains what you need.

  • If it exists in @customer-portal/domain/<module>, don’t import a deeper file.
  • If it’s provider-specific, use @customer-portal/domain/<module>/providers (BFF-only).
  • If it’s cross-domain utility, use @customer-portal/domain/toolkit.

When to create a new explicit entrypoint (instead of deep-importing)

Create/adjust exports when:

  • The symbol is used in 2+ apps (Portal + BFF), or many call sites.
  • The symbol is part of a workflow that should remain stable (pagination, formatting, shared validation helpers).

Where to export it:

  • Module root (@customer-portal/domain/<module>): normalized domain types/models, schemas, provider-agnostic helpers.
  • Providers entrypoint (.../<module>/providers): provider adapters, mapper/query builder logic, raw provider shapes (if truly needed).
  • Toolkit (@customer-portal/domain/toolkit): shared utilities (Formatting, Validation, Typing namespaces).

Naming conventions

  • Module root: Invoice, invoiceSchema, validateOrderBusinessRules
  • Providers: Whmcs, Salesforce, Freebit namespaces; raw shapes should be obviously integration-only.

PR checklist

  • No @customer-portal/domain/*/* imports (except exact .../<module>/providers in BFF).
  • Portal has zero .../providers imports.
  • No wildcard subpath exports added to packages/domain/package.json#exports.