Assist_Design/CODEBASE_ANALYSIS.md

Codebase Analysis (October 2025)

✅ Recent Cleanup

• Checkout contracts unified: checkoutBuildCartRequestSchema and the wrapped response now live in @customer-portal/domain/orders. Both the NestJS controller and service import the shared types, eliminating local Zod definitions and ad-hoc request shapes.
• SIM configuration aligned: The catalog store and useSimConfigure hook persist state that maps directly to simConfigureFormSchema. Validation now delegates to the domain schema, and UI state uses the shared field names (selectedAddons, scheduledActivationDate, etc.).
• Dashboard metadata centralized: Invoice/service activity metadata schemas moved into @customer-portal/domain/dashboard, and the portal utilities reuse them rather than maintaining local copies.
• UI totals reuse domain types: EnhancedOrderSummary now aliases CheckoutTotals, keeping the presentation layer in lockstep with the API contract.
• Build artifacts removed: All 224 generated .js, .d.ts, and .js.map files in the packages/domain source tree have been deleted. These files are now built fresh on demand into dist/ via pnpm build, and .gitignore ensures they stay out of version control. The domain package now contains 100 clean TypeScript source files with all build outputs isolated to dist/.
• Schema organization improved: Extracted duplicated enum value arrays in packages/domain/orders/schema.ts to constants, eliminating repetition and improving maintainability. All enums (ACCESS_MODE, ACTIVATION_TYPE, SIM_TYPE) now follow consistent patterns.
• Internet Access Mode centralized: Added ACCESS_MODE constant and AccessModeValue type to packages/domain/orders/contract.ts. The catalog store now imports from domain instead of defining its own local type, ensuring single source of truth.
• Domain exports complete: All configuration constants (ORDER_TYPE, ACTIVATION_TYPE, SIM_TYPE, ACCESS_MODE) are now properly exported from packages/domain/orders/index.ts for consistent use across BFF and portal.

🔒 Security Fixes (Critical)

• Idempotency protection: SIM activation now uses Redis-backed idempotency keys to prevent race conditions and double-charging. Duplicate requests return cached results. Processing locks prevent concurrent execution.
• Stronger password hashing: Bcrypt rounds increased from 12 to 14 (minimum 12, default 14). Provides better security against brute-force attacks with acceptable performance impact.
• Typed exception framework: Created structured exception hierarchy with error codes and context. Replaces generic throw new Error() with domain-specific exceptions like SimActivationException, OrderValidationException, etc.
• CSRF token enforcement: Portal API client now fails fast when CSRF token is unavailable instead of silently proceeding. Mutation endpoints protected from CSRF bypass attempts.

🔍 Follow-Up Opportunities

• Complete typed exceptions: Remaining 31 files still use generic throw new Error(). See IMPLEMENTATION_PROGRESS.md for complete list and priority order.
• Catalog caching: Add Redis caching layer for catalog responses (5-minute TTL) to reduce Salesforce API load by ~50%.
• Rate limiting: Add throttle decorators to expensive endpoints (catalog, orders) to prevent DOS attacks.
• Console.log cleanup: Replace 40 instances of console.log in portal with proper logging infrastructure.
• Auth workflow audit: Re-run a focused review of the WHMCS link workflow and mapping services to confirm no lingering loose types (the earlier report flagged placeholder values—verify after the latest merges).
• Portal checkout transforms: Consider using simConfigureFormToRequest when serialising SIM selections into cart params so the client sends the same payload shape the BFF expects.
• End-to-end validation run: Execute pnpm lint && pnpm type-check once the workspace stabilises to catch any regressions introduced outside the touched files.

📋 Ongoing Work

See IMPLEMENTATION_PROGRESS.md for detailed status of the 26-issue remediation plan. Phase 1 (Critical Security) is 75% complete. Phases 2-4 are pending implementation.

🎯 Next Recommended Steps

1. Type-check sweep – run the workspace type checker and fix residual errors, paying special attention to auth and user modules.
2. Checkout flow trace – ensure the BFF and portal both serialise/deserialise SIM selections via the shared helpers (avoids stale query-param parsing edge cases).
3. Documentation refresh – propagate the new ownership model (domain-first schemas) into any onboarding or architecture docs so future engineers default to the shared packages.