Assist_Design/docs/README.md

# 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