Assist_Design/docs

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	Initial project setup
Running the App	Local development
Deployment	Deployment instructions
Docker & Prisma	Docker setup with Prisma
Address System	Address handling

See also: Project Structure

---

🏗️ Architecture

Core system design documents:

Document	Description
System Overview	High-level architecture
Monorepo Structure	Monorepo organization
Product Catalog	Product catalog design
Modular Provisioning	Provisioning architecture
Domain Layer	Domain-driven design
Orders Architecture	Order system design

---

📖 How It Works

Feature guides explaining how the portal functions:

Guide	Description
System Overview	Systems and data ownership
Accounts & Identity	Sign-up and WHMCS linking
Services & Checkout	Products and checkout rules
Orders & Provisioning	Order fulfillment flow
Billing & Payments	Invoices and payments
Subscriptions	Active services
Support Cases	Salesforce case creation
Order Fulfillment	Complete order flow
Add-on Installation	Add-on handling logic
Complete Guide	End-to-end explanation

---

🔌 Integrations

Salesforce

Document	Description
Requirements	Objects, fields, flows, setup
Overview	Getting started
Orders	Order communication
Products	Product catalog
Security	Security setup
Opportunity Lifecycle	Opportunity stages
WHMCS Mapping	SF-WHMCS data mapping

WHMCS

Document	Description
Troubleshooting	Billing issues resolution

SIM Management

Document	Description
Freebit Integration	Freebit SIM management
Data Flow	SIM API data flow
State Machine	SIM state transitions

---

💻 Development

BFF (Backend for Frontend)

Document	Description
Integration Patterns	Clean architecture patterns
DB Mappers	Database mapping
Order Status Updates	Status update strategy

Portal (Frontend)

Document	Description
Architecture	Frontend structure
Performance	Performance optimization
Data Model	Data structures
Integration Overview	API integration
Lib Structure	Code organization
UI Design System	Design system

Domain Layer

Document	Description
Structure	Domain organization
Packages	Package structure
Types	Unified type system

Authentication

Document	Description
Module Architecture	Auth module design
Development Setup	Auth setup for dev
Redis Tokens	Token flow implementation

---

🛠️ Operations

Runbooks

Document	Description
Incident Response	Emergency procedures
Provisioning Runbook	Order fulfillment procedures
Database Operations	Backup, recovery, maintenance
External Dependencies	Integration health checks
Queue Management	BullMQ job monitoring
External Processes	Team handoffs and workflows
Release Procedures	Deployment and rollback

System Operations

Document	Description
Logging	Centralized logging system
Security Monitoring	Security monitoring setup
Subscription Management	Service management
Monitoring Setup	Metrics and dashboards
Rate Limit Tuning	Rate limit configuration
Customer Data Management	GDPR and data procedures

---

📐 Architecture Decisions

Key architectural decisions and their rationale:

Decision	Summary
Platform Events over Webhooks	Why we use SF Platform Events for provisioning
Zod-First Validation	Why Zod schemas are the source of truth
Map Once, Use Everywhere	Why single transformation in domain mappers
Domain Provider Isolation	Why provider code is isolated in domain/providers/
Feature Module Pattern	Why Portal uses feature modules
Thin Controllers	Why controllers handle HTTP only

See all decisions for the complete index and ADR template.

---

🗂️ 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
2. System Overview
3. Complete Guide

Backend Developer

1. Integration Patterns
2. Salesforce Requirements
3. Order Fulfillment

Frontend Developer

1. Portal Architecture
2. Domain Types
3. Performance

DevOps / Operations

1. Deployment
2. Release Procedures
3. Incident Response
4. Monitoring Setup
5. Database Operations
6. External Dependencies
7. Rate Limit Tuning

---

🏗️ Technology Stack

Frontend: Next.js 16, 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, Japan Post

---

Last Updated: January 2026