# Customer Portal Documentation This directory contains comprehensive system design documentation for the Customer Portal project. --- ## 👀 Portal Guides (How It Works) - [Overview](./portal-guides/system-overview.md) — systems, data ownership, and caching quick reference - [Accounts & Identity](./portal-guides/accounts-and-identity.md) — sign-up, WHMCS linking, and address/profile handling - [Catalog & Checkout](./portal-guides/catalog-and-checkout.md) — product source, eligibility, and checkout rules - [Orders & Provisioning](./portal-guides/orders-and-provisioning.md) — Salesforce orders and WHMCS fulfillment flow - [Billing & Payments](./portal-guides/billing-and-payments.md) — invoices, SSO pay links, and payment methods - [Subscriptions](./portal-guides/subscriptions.md) — how active services are read and refreshed - [Support Cases](./portal-guides/support-cases.md) — Salesforce case creation and visibility - [Complete Guide](./portal-guides/COMPLETE-GUIDE.md) — single, end-to-end explanation of how the portal works --- ## 📚 Core System Design Documents ### [System Architecture](./architecture/SYSTEM-ARCHITECTURE.md) **Comprehensive overview of the entire system** - System overview and high-level architecture - Architecture principles (Clean Architecture, DDD) - Monorepo structure and organization - Application layers (Portal, BFF, Domain) - Technology stack and infrastructure - Data flow and integration patterns - Deployment architecture **Start here** for a complete understanding of the system. --- ### [Integration & Data Flow](./architecture/INTEGRATION-DATAFLOW.md) **External system integration patterns and data transformation** - Integration architecture overview - Salesforce integration (REST API + Platform Events via gRPC Pub/Sub) - WHMCS integration (REST API + Webhooks) - Freebit SIM management integration - Domain mapper pattern (Map Once, Use Everywhere) - Data transformation flows - Error handling and retry strategies - Caching strategies (CDC-driven + TTL-based) **Read this** to understand how external systems are integrated. --- ### [Domain Layer Design](./architecture/DOMAIN-LAYER-DESIGN.md) **Framework-agnostic type system and business logic** - Domain-driven design principles - Provider pattern for multi-system abstraction - Type system architecture (unified domain package) - Schema-driven validation with Zod - Adding new domains step-by-step - Import patterns and best practices **Read this** to understand the domain layer and type system. --- ### [Authentication & Security](./architecture/AUTHENTICATION-SECURITY.md) **Security architecture and implementation** - Authentication flow (JWT access + refresh tokens) - Token management and rotation with Redis blacklist - Authorization and access control - Rate limiting strategies (auth endpoints + external APIs) - Password security (Bcrypt with configurable rounds) - CSRF protection - PII redaction and data protection - Audit logging **Read this** for security implementation details. --- ## 📖 Feature-Specific Documentation ### Portal (Frontend) - [Portal Architecture](./portal/PORTAL-ARCHITECTURE.md) - Frontend structure - [Performance Optimization](./portal/PERFORMANCE.md) - Performance best practices - [Portal Data Model](./portal/PORTAL-DATA-MODEL.md) - Data structures - [Portal Integration Overview](./portal/PORTAL-INTEGRATION-OVERVIEW.md) - API integration - [Portal Roadmap](./portal/PORTAL-ROADMAP.md) - Future plans - [Recommended Library Structure](./portal/RECOMMENDED-LIB-STRUCTURE.md) - Code organization ### Orders & Catalog - [Order Fulfillment Guide](./orders/ORDER-FULFILLMENT-COMPLETE-GUIDE.md) - Order processing flow - [Portal Ordering & Provisioning](./orders/PORTAL-ORDERING-PROVISIONING.md) - Order management - [Product Catalog Architecture](./architecture/PRODUCT-CATALOG-ARCHITECTURE.md) - Catalog design - [Add-on Installation Logic](./products/ADDON-INSTALLATION-LOGIC.md) - Add-on handling - [Bundle Analysis](./products/BUNDLE_ANALYSIS.md) - Product bundles ### Integration Guides **BFF Integration Layer:** - [BFF Integration Patterns (Architecture)](./bff/BFF-INTEGRATION-PATTERNS-ARCHITECTURE.md) - Integration architecture - [BFF Integration Patterns (Guide)](./bff/BFF-INTEGRATION-PATTERNS-GUIDE.md) - Implementation guide - [DB Mappers](./bff/DB-MAPPERS.md) - Database mapping patterns **Salesforce:** - [Salesforce Portal Simple Guide](./salesforce/SALESFORCE-PORTAL-SIMPLE-GUIDE.md) - Getting started - [Salesforce Order Communication](./salesforce/SALESFORCE-ORDER-COMMUNICATION.md) - Order integration - [Salesforce Portal Security Guide](./salesforce/SALESFORCE-PORTAL-SECURITY-GUIDE.md) - Security setup - [Salesforce Products](./salesforce/SALESFORCE-PRODUCTS.md) - Product catalog - [Salesforce-WHMCS Mapping Reference](./salesforce/SALESFORCE-WHMCS-MAPPING-REFERENCE.md) - Data mapping - [WHMCS Billing Issues Resolution](./salesforce/WHMCS_BILLING_ISSUES_RESOLUTION.md) - Troubleshooting **API Integration:** - [SIM Management API Data Flow](./api/SIM-MANAGEMENT-API-DATA-FLOW.md) - SIM API integration - [Freebit SIM Management](./api/FREEBIT-SIM-MANAGEMENT.md) - Freebit integration ### Domain & Architecture - [Domain Structure](./domain/DOMAIN-STRUCTURE.md) - Domain organization - [Package Organization](./domain/PACKAGE-ORGANIZATION.md) - Package structure - [Monorepo Architecture](./architecture/MONOREPO-ARCHITECTURE.md) - Monorepo setup - [Modular Provisioning Architecture](./architecture/MODULAR-PROVISIONING-ARCHITECTURE.md) - Provisioning design - [New Domain Architecture](./architecture/NEW-DOMAIN-ARCHITECTURE.md) - Domain layer design ### Validation & Data - [Validation Patterns](./validation/VALIDATION_PATTERNS.md) - Validation strategies - [Validation Cleanup Summary](./validation/VALIDATION_CLEANUP_SUMMARY.md) - Validation improvements - [BFF Validation Migration](./validation/bff-validation-migration.md) - Migration guide - [Signup Validation Rules](./validation/SIGNUP_VALIDATION_RULES.md) - Signup validation - [Unified Product Types](./types/UNIFIED-PRODUCT-TYPES.md) - Type unification - [Consolidated Type System](./types/CONSOLIDATED-TYPE-SYSTEM.md) - Type system design ### Operations & Deployment **Getting Started:** - [Getting Started](./guides/GETTING_STARTED.md) - Setup instructions - [Running the Application](./guides/RUN.md) - How to run - [Deployment Guide](./guides/DEPLOY.md) - Deployment instructions - [Project Structure](./guides/STRUCTURE.md) - Directory structure - [Address System](./guides/ADDRESS_SYSTEM.md) - Address handling **Provisioning:** - [Provisioning Runbook](./provisioning/RUNBOOK_PROVISIONING.md) - Provisioning procedures - [Subscription Service Management](./provisioning/SUBSCRIPTION-SERVICE-MANAGEMENT.md) - Service management - [Temporarily Disabled Modules](./provisioning/TEMPORARY-DISABLED-MODULES.md) - Disabled features **Logging:** - [Logging Guide](./logging/LOGGING.md) - Logging implementation - [Logging Levels](./logging/LOGGING_LEVELS.md) - Log level configuration ### Other Documentation - [Changelog](./CHANGELOG.md) - Project changelog - [Portal Non-Tech Presentation](./portal/PORTAL-NONTECH-PRESENTATION.md) - Non-technical overview --- ## 🗂️ Archived Documentation Status reports and temporary implementation documents have been moved to `_archive/`: - Migration progress reports - Refactoring completion documents - Cleanup and audit documents - Priority tracking documents These are kept for historical reference but are not part of the active system design. --- ## 🎯 Quick Start Guide ### For New Developers 1. **Start with Core Design Documents:** - [System Architecture](./architecture/SYSTEM-ARCHITECTURE.md) - Overall system (if available) - [Domain Layer Design](./architecture/DOMAIN-LAYER-DESIGN.md) - Type system (if available) - [Integration & Data Flow](./architecture/INTEGRATION-DATAFLOW.md) - External systems (if available) 2. **Set Up Your Environment:** - [Getting Started](./guides/GETTING_STARTED.md) - Setup - [Running the Application](./guides/RUN.md) - Local development 3. **Understand Key Features:** - [Order Fulfillment Guide](./orders/ORDER-FULFILLMENT-COMPLETE-GUIDE.md) - [Product Catalog Architecture](./architecture/PRODUCT-CATALOG-ARCHITECTURE.md) - [Portal Architecture](./portal/PORTAL-ARCHITECTURE.md) ### For Backend Developers 1. [System Architecture](./architecture/SYSTEM-ARCHITECTURE.md) - BFF architecture (if available) 2. [Integration & Data Flow](./architecture/INTEGRATION-DATAFLOW.md) - Integration patterns (if available) 3. [Authentication & Security](./architecture/AUTHENTICATION-SECURITY.md) - Auth implementation (if available) 4. [BFF Integration Patterns](./bff/BFF-INTEGRATION-PATTERNS-GUIDE.md) - Best practices ### For Frontend Developers 1. [Portal Architecture](./portal/PORTAL-ARCHITECTURE.md) - Frontend structure 2. [Domain Layer Design](./architecture/DOMAIN-LAYER-DESIGN.md) - Type system (if available) 3. [Portal Integration Overview](./portal/PORTAL-INTEGRATION-OVERVIEW.md) - API integration 4. [Performance Optimization](./portal/PERFORMANCE.md) - Performance tips ### For Integration Work 1. [Integration & Data Flow](./architecture/INTEGRATION-DATAFLOW.md) - Integration architecture (if available) 2. [Salesforce Portal Simple Guide](./salesforce/SALESFORCE-PORTAL-SIMPLE-GUIDE.md) 3. [Salesforce-WHMCS Mapping Reference](./salesforce/SALESFORCE-WHMCS-MAPPING-REFERENCE.md) 4. [SIM Management API Data Flow](./api/SIM-MANAGEMENT-API-DATA-FLOW.md) ### For DevOps/Deployment 1. [Deployment Guide](./guides/DEPLOY.md) 2. [Provisioning Runbook](./provisioning/RUNBOOK_PROVISIONING.md) 3. [Logging Guide](./logging/LOGGING.md) --- ## 📋 Documentation Standards ### When Adding New Documentation 1. **Place in appropriate category folder** 2. **Use clear, descriptive filenames** 3. **Update this README index** 4. **Follow markdown best practices** 5. **Include date and author information** 6. **Keep documentation synchronized with code** ### Documentation Types - **Design Documents**: Architecture, patterns, and design decisions - **Guides**: Step-by-step instructions and tutorials - **References**: API documentation, data mappings, configuration - **Status Reports**: Move to `_archive/` when outdated ### Naming Conventions - Use `UPPERCASE-WITH-DASHES.md` for design documents - Use descriptive names that indicate content - Avoid version numbers in filenames - Use consistent prefixes for related docs --- ## 🤝 Contributing When updating documentation: - Keep files organized in their respective categories - Update the changelog for significant changes - Ensure all links work correctly - Use relative links for internal documentation - Keep the README index updated - Archive outdated status reports --- ## 📞 Support For questions about the system: 1. Check the relevant design document 2. Review related guides and references 3. Check archived documents for historical context 4. Contact the development team ## 🏗️ Technology Stack ### Frontend - Next.js 15 (App Router) with React 19 - Tailwind CSS 4 with shadcn/ui components - TanStack Query for data fetching and caching - Zustand for client state management - React Hook Form + Zod for form validation ### Backend (BFF) - NestJS 11 with TypeScript - Prisma 6 ORM with PostgreSQL 17 - p-queue for request throttling - Redis 7 for caching and token blacklist - Pino for structured logging ### External Integrations - **WHMCS**: Custom API client for billing and subscriptions - **Salesforce**: jsforce for REST API + salesforce-pubsub-api-client for Platform Events - **Freebit**: Custom SIM management integration ### Infrastructure - Docker for local development - pnpm workspaces for monorepo management - TypeScript project references for build optimization --- **Last Updated**: November 2025 **Maintained By**: Development Team --- ## 📑 Complete File Index
View all documentation files ### Core Design - SYSTEM-ARCHITECTURE.md (check if exists in architecture/) - INTEGRATION-DATAFLOW.md (check if exists in architecture/) - DOMAIN-LAYER-DESIGN.md (check if exists in architecture/) - AUTHENTICATION-SECURITY.md (check if exists in architecture/) ### Architecture - architecture/MONOREPO-ARCHITECTURE.md - architecture/MODULAR-PROVISIONING-ARCHITECTURE.md - architecture/NEW-DOMAIN-ARCHITECTURE.md - architecture/ORDERS-ARCHITECTURE-REVIEW.md - architecture/PRODUCT-CATALOG-ARCHITECTURE.md ### API & Integration - api/FREEBIT-SIM-MANAGEMENT.md - api/SIM-MANAGEMENT-API-DATA-FLOW.md ### Authentication - auth/AUTH-MODULE-ARCHITECTURE.md - auth/AUTH-SCHEMA-IMPROVEMENTS.md - auth/DEVELOPMENT-AUTH-SETUP.md - auth/REDIS-TOKEN-FLOW-IMPLEMENTATION.md ### BFF - bff/BFF-INTEGRATION-PATTERNS-ARCHITECTURE.md - bff/BFF-INTEGRATION-PATTERNS-GUIDE.md - bff/DB-MAPPERS.md ### Domain - domain/DOMAIN-STRUCTURE.md - domain/PACKAGE-ORGANIZATION.md ### Guides - guides/ADDRESS_SYSTEM.md - guides/DEPLOY.md - guides/GETTING_STARTED.md - guides/RUN.md - guides/STRUCTURE.md ### Logging - logging/LOGGING.md - logging/LOGGING_LEVELS.md ### Orders - orders/ORDER-FULFILLMENT-COMPLETE-GUIDE.md - orders/PORTAL-ORDERING-PROVISIONING.md ### Portal - portal/PERFORMANCE.md - portal/PORTAL-ARCHITECTURE.md - portal/PORTAL-DATA-MODEL.md - portal/PORTAL-INTEGRATION-OVERVIEW.md - portal/PORTAL-NONTECH-PRESENTATION.md - portal/PORTAL-ROADMAP.md - portal/RECOMMENDED-LIB-STRUCTURE.md ### Products - products/ADDON-INSTALLATION-LOGIC.md - products/BUNDLE_ANALYSIS.md ### Provisioning - provisioning/RUNBOOK_PROVISIONING.md - provisioning/SUBSCRIPTION-SERVICE-MANAGEMENT.md - provisioning/TEMPORARY-DISABLED-MODULES.md ### Salesforce - salesforce/SALESFORCE-ORDER-COMMUNICATION.md - salesforce/SALESFORCE-PORTAL-SECURITY-GUIDE.md - salesforce/SALESFORCE-PORTAL-SIMPLE-GUIDE.md - salesforce/SALESFORCE-PRODUCTS.md - salesforce/SALESFORCE-WHMCS-MAPPING-REFERENCE.md - salesforce/WHMCS_BILLING_ISSUES_RESOLUTION.md ### Types - types/CONSOLIDATED-TYPE-SYSTEM.md - types/UNIFIED-PRODUCT-TYPES.md ### Validation - validation/SIGNUP_VALIDATION_RULES.md - validation/VALIDATION_CLEANUP_SUMMARY.md - validation/VALIDATION_PATTERNS.md - validation/bff-validation-migration.md