718dbfcf1b
- Updated SHA256 checksums for the latest backend and frontend tarballs. - Modified the Dockerfile for the BFF application to regenerate the Prisma client in the production layout, ensuring the embedded schema path is correct. - Adjusted package scripts to use `pnpm` consistently for build and analysis commands, improving clarity and consistency across the project.
Customer Portal Documentation
This directory contains comprehensive system design documentation for the Customer Portal project.
📚 Core System Design Documents
System Architecture
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
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
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
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 - Frontend structure
- Performance Optimization - Performance best practices
- Portal Data Model - Data structures
- Portal Integration Overview - API integration
- Portal Roadmap - Future plans
- Recommended Library Structure - Code organization
Orders & Catalog
- Order Fulfillment Guide - Order processing flow
- Portal Ordering & Provisioning - Order management
- Product Catalog Architecture - Catalog design
- Add-on Installation Logic - Add-on handling
- Bundle Analysis - Product bundles
Integration Guides
BFF Integration Layer:
- BFF Integration Patterns (Architecture) - Integration architecture
- BFF Integration Patterns (Guide) - Implementation guide
- DB Mappers - Database mapping patterns
Salesforce:
- Salesforce Portal Simple Guide - Getting started
- Salesforce Order Communication - Order integration
- Salesforce Portal Security Guide - Security setup
- Salesforce Products - Product catalog
- Salesforce-WHMCS Mapping Reference - Data mapping
- WHMCS Billing Issues Resolution - Troubleshooting
API Integration:
- SIM Management API Data Flow - SIM API integration
- Freebit SIM Management - Freebit integration
Domain & Architecture
- Domain Structure - Domain organization
- Package Organization - Package structure
- Monorepo Architecture - Monorepo setup
- Modular Provisioning Architecture - Provisioning design
- New Domain Architecture - Domain layer design
Validation & Data
- Validation Patterns - Validation strategies
- Validation Cleanup Summary - Validation improvements
- BFF Validation Migration - Migration guide
- Signup Validation Rules - Signup validation
- Unified Product Types - Type unification
- Consolidated Type System - Type system design
Operations & Deployment
Getting Started:
- Getting Started - Setup instructions
- Running the Application - How to run
- Deployment Guide - Deployment instructions
- Project Structure - Directory structure
- Address System - Address handling
Provisioning:
- Provisioning Runbook - Provisioning procedures
- Subscription Service Management - Service management
- Temporarily Disabled Modules - Disabled features
Logging:
- Logging Guide - Logging implementation
- Logging Levels - Log level configuration
Other Documentation
- Changelog - Project changelog
- Portal Non-Tech Presentation - 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
-
Start with Core Design Documents:
- System Architecture - Overall system (if available)
- Domain Layer Design - Type system (if available)
- Integration & Data Flow - External systems (if available)
-
Set Up Your Environment:
- Getting Started - Setup
- Running the Application - Local development
-
Understand Key Features:
For Backend Developers
- System Architecture - BFF architecture (if available)
- Integration & Data Flow - Integration patterns (if available)
- Authentication & Security - Auth implementation (if available)
- BFF Integration Patterns - Best practices
For Frontend Developers
- Portal Architecture - Frontend structure
- Domain Layer Design - Type system (if available)
- Portal Integration Overview - API integration
- Performance Optimization - Performance tips
For Integration Work
- Integration & Data Flow - Integration architecture (if available)
- Salesforce Portal Simple Guide
- Salesforce-WHMCS Mapping Reference
- SIM Management API Data Flow
For DevOps/Deployment
📋 Documentation Standards
When Adding New Documentation
- Place in appropriate category folder
- Use clear, descriptive filenames
- Update this README index
- Follow markdown best practices
- Include date and author information
- 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.mdfor 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:
- Check the relevant design document
- Review related guides and references
- Check archived documents for historical context
- 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