# Customer Portal Documentation Comprehensive documentation for the Customer Portal project. --- ## 📁 Documentation Structure ``` docs/ ├── getting-started/ # Setup and running the project ├── architecture/ # System design documents ├── how-it-works/ # Feature guides (how the portal works) ├── integrations/ # Salesforce, WHMCS, SIM integration docs ├── development/ # BFF, Portal, Domain, Auth code docs ├── operations/ # Logging, provisioning, monitoring └── _archive/ # Historical documents ``` --- ## 🚀 Getting Started | Document | Description | | ----------------------------------------------------- | ------------------------ | | [Setup Guide](./getting-started/setup.md) | Initial project setup | | [Running the App](./getting-started/running.md) | Local development | | [Deployment](./getting-started/deployment.md) | Deployment instructions | | [Docker & Prisma](./getting-started/docker-prisma.md) | Docker setup with Prisma | | [Address System](./getting-started/address-system.md) | Address handling | See also: [Project Structure](./STRUCTURE.md) --- ## 🏗️ Architecture Core system design documents: | Document | Description | | -------------------------------------------------------------- | ------------------------- | | [System Overview](./architecture/system-overview.md) | High-level architecture | | [Monorepo Structure](./architecture/monorepo.md) | Monorepo organization | | [Product Catalog](./architecture/product-catalog.md) | Product catalog design | | [Modular Provisioning](./architecture/modular-provisioning.md) | Provisioning architecture | | [Domain Layer](./architecture/domain-layer.md) | Domain-driven design | | [Orders Architecture](./architecture/orders.md) | Order system design | --- ## 📖 How It Works Feature guides explaining how the portal functions: | Guide | Description | | ------------------------------------------------------------------ | --------------------------- | | [System Overview](./how-it-works/system-overview.md) | Systems and data ownership | | [Accounts & Identity](./how-it-works/accounts-and-identity.md) | Sign-up and WHMCS linking | | [Services & Checkout](./how-it-works/services-and-checkout.md) | Products and checkout rules | | [Orders & Provisioning](./how-it-works/orders-and-provisioning.md) | Order fulfillment flow | | [Billing & Payments](./how-it-works/billing-and-payments.md) | Invoices and payments | | [Subscriptions](./how-it-works/subscriptions.md) | Active services | | [Support Cases](./how-it-works/support-cases.md) | Salesforce case creation | | [Order Fulfillment](./how-it-works/order-fulfillment.md) | Complete order flow | | [Add-on Installation](./how-it-works/addon-installation.md) | Add-on handling logic | | [Complete Guide](./how-it-works/COMPLETE-GUIDE.md) | End-to-end explanation | --- ## 🔌 Integrations ### Salesforce | Document | Description | | --------------------------------------------------------------------------- | ----------------------------- | | [Requirements](./integrations/salesforce/requirements.md) | Objects, fields, flows, setup | | [Overview](./integrations/salesforce/overview.md) | Getting started | | [Orders](./integrations/salesforce/orders.md) | Order communication | | [Products](./integrations/salesforce/products.md) | Product catalog | | [Security](./integrations/salesforce/security.md) | Security setup | | [Opportunity Lifecycle](./integrations/salesforce/opportunity-lifecycle.md) | Opportunity stages | | [WHMCS Mapping](./integrations/salesforce/whmcs-mapping.md) | SF-WHMCS data mapping | ### WHMCS | Document | Description | | ---------------------------------------------------------- | ------------------------- | | [Troubleshooting](./integrations/whmcs/troubleshooting.md) | Billing issues resolution | ### SIM Management | Document | Description | | ---------------------------------------------------- | ---------------------- | | [Freebit Integration](./integrations/sim/freebit.md) | Freebit SIM management | | [Data Flow](./integrations/sim/data-flow.md) | SIM API data flow | | [State Machine](./integrations/sim/state-machine.md) | SIM state transitions | --- ## 💻 Development ### BFF (Backend for Frontend) | Document | Description | | ----------------------------------------------------------------- | --------------------------- | | [Integration Patterns](./development/bff/integration-patterns.md) | Clean architecture patterns | | [DB Mappers](./development/bff/db-mappers.md) | Database mapping | | [Order Status Updates](./development/bff/order-status-updates.md) | Status update strategy | ### Portal (Frontend) | Document | Description | | -------------------------------------------------------------------- | ------------------------ | | [Architecture](./development/portal/architecture.md) | Frontend structure | | [Performance](./development/portal/performance.md) | Performance optimization | | [Data Model](./development/portal/data-model.md) | Data structures | | [Integration Overview](./development/portal/integration-overview.md) | API integration | | [Lib Structure](./development/portal/lib-structure.md) | Code organization | | [UI Design System](./development/portal/ui-design-system.md) | Design system | ### Domain Layer | Document | Description | | ---------------------------------------------- | ------------------- | | [Structure](./development/domain/structure.md) | Domain organization | | [Packages](./development/domain/packages.md) | Package structure | | [Types](./development/domain/types.md) | Unified type system | ### Authentication | Document | Description | | ------------------------------------------------------------ | ------------------------- | | [Module Architecture](./development/auth/module.md) | Auth module design | | [Development Setup](./development/auth/development-setup.md) | Auth setup for dev | | [Redis Tokens](./development/auth/redis-tokens.md) | Token flow implementation | --- ## 🛠️ Operations ### Runbooks | Document | Description | | -------------------------------------------------------------- | ----------------------------- | | [Incident Response](./operations/incident-response.md) | Emergency procedures | | [Provisioning Runbook](./operations/provisioning-runbook.md) | Order fulfillment procedures | | [Database Operations](./operations/database-operations.md) | Backup, recovery, maintenance | | [External Dependencies](./operations/external-dependencies.md) | Integration health checks | | [Queue Management](./operations/queue-management.md) | BullMQ job monitoring | | [External Processes](./operations/external-processes.md) | Team handoffs and workflows | | [Release Procedures](./operations/release-procedures.md) | Deployment and rollback | ### System Operations | Document | Description | | -------------------------------------------------------------------- | -------------------------- | | [Logging](./operations/logging.md) | Centralized logging system | | [Security Monitoring](./operations/security-monitoring.md) | Security monitoring setup | | [Subscription Management](./operations/subscription-management.md) | Service management | | [Monitoring Setup](./operations/monitoring-setup.md) | Metrics and dashboards | | [Rate Limit Tuning](./operations/rate-limit-tuning.md) | Rate limit configuration | | [Customer Data Management](./operations/customer-data-management.md) | GDPR and data procedures | --- ## 🗂️ Archive Historical documents kept for reference: - `_archive/planning/` — Development plans and task lists - `_archive/refactoring/` — Completed refactoring summaries - `_archive/reviews/` — Point-in-time code reviews --- ## 🎯 Quick Start by Role ### New Developer 1. [Setup Guide](./getting-started/setup.md) 2. [System Overview](./architecture/system-overview.md) 3. [Complete Guide](./how-it-works/COMPLETE-GUIDE.md) ### Backend Developer 1. [Integration Patterns](./development/bff/integration-patterns.md) 2. [Salesforce Requirements](./integrations/salesforce/requirements.md) 3. [Order Fulfillment](./how-it-works/order-fulfillment.md) ### Frontend Developer 1. [Portal Architecture](./development/portal/architecture.md) 2. [Domain Types](./development/domain/types.md) 3. [Performance](./development/portal/performance.md) ### DevOps / Operations 1. [Deployment](./getting-started/deployment.md) 2. [Release Procedures](./operations/release-procedures.md) 3. [Incident Response](./operations/incident-response.md) 4. [Monitoring Setup](./operations/monitoring-setup.md) 5. [Database Operations](./operations/database-operations.md) 6. [External Dependencies](./operations/external-dependencies.md) 7. [Rate Limit Tuning](./operations/rate-limit-tuning.md) --- ## 🏗️ Technology Stack **Frontend**: Next.js 15, React 19, Tailwind CSS 4, shadcn/ui, TanStack Query, Zustand **Backend**: NestJS 11, Prisma 6, PostgreSQL 17, Redis 7, Pino **Integrations**: Salesforce (jsforce + Pub/Sub API), WHMCS, Freebit --- **Last Updated**: December 2025