90ab71b94d
- Added a new section for Release Procedures, detailing deployment and rollback processes. - Updated the System Operations section to include Monitoring Setup, Rate Limit Tuning, and Customer Data Management for improved operational guidance. - Reformatted the table structure for better readability and consistency across documentation.
219 lines
10 KiB
Markdown
219 lines
10 KiB
Markdown
# 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) | 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 |
|
|
| [Catalog & Checkout](./how-it-works/catalog-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
|