# 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.