Assist_Design/docs/README.md

# Customer Portal Documentation

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

---

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

<details>
<summary>View all documentation files</summary>

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

</details>