Assist_Design/docs/README.md

Customer Portal Documentation

This directory contains comprehensive system design documentation for the Customer Portal project.

---

👀 Portal Guides (How It Works)

• Overview — systems, data ownership, and caching quick reference
• Accounts & Identity — sign-up, WHMCS linking, and address/profile handling
• Catalog & Checkout — product source, eligibility, and checkout rules
• Orders & Provisioning — Salesforce orders and WHMCS fulfillment flow
• Billing & Payments — invoices, SSO pay links, and payment methods
• Subscriptions — how active services are read and refreshed
• Support Cases — Salesforce case creation and visibility
• Complete Guide — single, end-to-end explanation of how the portal works

---

📚 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

1. 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)

2. Set Up Your Environment:

   • Getting Started - Setup
   • Running the Application - Local development

3. Understand Key Features:

   • Order Fulfillment Guide
   • Product Catalog Architecture
   • Portal Architecture

For Backend Developers

1. System Architecture - BFF architecture (if available)
2. Integration & Data Flow - Integration patterns (if available)
3. Authentication & Security - Auth implementation (if available)
4. BFF Integration Patterns - Best practices

For Frontend Developers

1. Portal Architecture - Frontend structure
2. Domain Layer Design - Type system (if available)
3. Portal Integration Overview - API integration
4. Performance Optimization - Performance tips

For Integration Work

1. Integration & Data Flow - Integration architecture (if available)
2. Salesforce Portal Simple Guide
3. Salesforce-WHMCS Mapping Reference
4. SIM Management API Data Flow

For DevOps/Deployment

1. Deployment Guide
2. Provisioning Runbook
3. Logging Guide

---

📋 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