From 4e313a42980b72a714c4d8007196679083b28066 Mon Sep 17 00:00:00 2001
From: nutcas3 <mauricee423@gmail.com>
Date: Sun, 19 Apr 2026 04:35:53 +0300
Subject: [PATCH] docs: Restructure documentation with comprehensive
 architecture guide and new API reference

- Remove docs/API.md (237 lines) with TaaS-specific REST endpoints and SDK examples
- Expand docs/ARCHITECTURE.md with detailed system overview, component architecture, data flow diagrams, scaling strategies, and RBAC security model
- Add Table of Contents with 6 main sections: System Overview, Component Details, Data Flow, Scaling, Security & RBAC, Future Enhancements
- Add detailed component descriptions
---
 docs/API.md             | 237 --------------------
 docs/ARCHITECTURE.md    | 486 ++++++++++++++++------------------------
 docs/DEPLOYMENT.md      | 454 -------------------------------------
 docs/GETTING_STARTED.md | 299 ++++++++++++++++++++++++
 docs/OPERATIONS.md      | 425 +++++++++++++++++++++++++++++++++++
 docs/QUICK_START.md     | 121 ----------
 6 files changed, 923 insertions(+), 1099 deletions(-)
 delete mode 100644 docs/API.md
 delete mode 100644 docs/DEPLOYMENT.md
 create mode 100644 docs/GETTING_STARTED.md
 create mode 100644 docs/OPERATIONS.md
 delete mode 100644 docs/QUICK_START.md

diff --git a/docs/API.md b/docs/API.md
deleted file mode 100644
index 4e3e1b2..0000000
--- a/docs/API.md
+++ /dev/null
@@ -1,237 +0,0 @@
-# TaaS Platform API Documentation
-
-## Overview
-
-The TaaS Platform provides a RESTful API for managing cellular connectivity programmatically. All API endpoints are available at `https://api.taas-platform.com/v1` (production) or `http://localhost:8000/v1` (development).
-
-## Authentication
-
-All API requests require authentication using Bearer tokens:
-
-```bash
-curl -H "Authorization: Bearer YOUR_API_KEY" \
-  https://api.taas-platform.com/v1/esims
-```
-
-Get your API key from the [Developer Dashboard](http://localhost:3000).
-
-## Endpoints
-
-### Health Check
-
-**GET** `/health`
-
-Check API server status.
-
-**Response:**
-```json
-{
-  "status": "healthy",
-  "service": "api-server",
-  "timestamp": 1711929600
-}
-```
-
-### Create eSIM
-
-**POST** `/v1/esims`
-
-Provision a new eSIM with cellular connectivity.
-
-**Request:**
-```json
-{
-  "data_plan": "1GB",
-  "country_code": "US",
-  "carrier": "optional-carrier-name"
-}
-```
-
-**Response:**
-```json
-{
-  "esim_id": "550e8400-e29b-41d4-a716-446655440000",
-  "imsi": "208930000000001",
-  "iccid": "8933123456789012345",
-  "activation_code": "LPA:1$smdp.example.com$MATCHING_ID",
-  "status": "provisioned",
-  "data_plan": "1GB",
-  "country_code": "US",
-  "created_at": "2026-04-01T12:00:00Z"
-}
-```
-
-### Get eSIM Details
-
-**GET** `/v1/esims/:id`
-
-Retrieve information about a specific eSIM.
-
-**Response:**
-```json
-{
-  "esim_id": "550e8400-e29b-41d4-a716-446655440000",
-  "imsi": "208930000000001",
-  "iccid": "8933123456789012345",
-  "status": "active",
-  "data_plan": "1GB",
-  "created_at": "2026-04-01T12:00:00Z"
-}
-```
-
-### Get eSIM Usage
-
-**GET** `/v1/esims/:id/usage`
-
-Get data usage statistics for an eSIM.
-
-**Response:**
-```json
-{
-  "esim_id": "550e8400-e29b-41d4-a716-446655440000",
-  "data_used": 262144000,
-  "data_limit": 1073741824,
-  "sessions": [
-    {
-      "started_at": "2026-04-01T10:00:00Z",
-      "ended_at": "2026-04-01T11:00:00Z",
-      "bytes_up": 10485760,
-      "bytes_down": 52428800
-    }
-  ],
-  "updated_at": "2026-04-01T12:00:00Z"
-}
-```
-
-### Terminate eSIM
-
-**DELETE** `/v1/esims/:id`
-
-Permanently terminate an eSIM.
-
-**Response:**
-```json
-{
-  "message": "eSIM terminated successfully",
-  "esim_id": "550e8400-e29b-41d4-a716-446655440000"
-}
-```
-
-## Status Codes
-
-- `200 OK` - Request successful
-- `201 Created` - Resource created
-- `400 Bad Request` - Invalid request parameters
-- `401 Unauthorized` - Missing or invalid authentication
-- `404 Not Found` - Resource not found
-- `500 Internal Server Error` - Server error
-
-## Rate Limits
-
-- **Free Tier**: 100 requests/hour
-- **Pro Tier**: 10,000 requests/hour
-- **Enterprise**: Unlimited
-
-Rate limit headers are included in all responses:
-```
-X-RateLimit-Limit: 100
-X-RateLimit-Remaining: 99
-X-RateLimit-Reset: 1711933200
-```
-
-## SDKs
-
-### TypeScript/JavaScript
-
-```bash
-npm install @taas-platform/sdk
-```
-
-```typescript
-import { TaasClient } from '@taas-platform/sdk';
-
-const client = new TaasClient({ apiKey: 'YOUR_API_KEY' });
-
-// Create eSIM
-const esim = await client.esims.create({
-  dataPlan: '1GB',
-  countryCode: 'US'
-});
-
-// Get usage
-const usage = await client.esims.getUsage(esim.esimId);
-```
-
-### Go
-
-```bash
-go get github.com/taas-platform/sdk-go
-```
-
-```go
-import "github.com/taas-platform/sdk-go"
-
-client := taas.NewClient("YOUR_API_KEY")
-
-// Create eSIM
-esim, err := client.ESims.Create(&taas.CreateESIMRequest{
-    DataPlan:    "1GB",
-    CountryCode: "US",
-})
-```
-
-## Webhooks
-
-Configure webhooks to receive real-time notifications:
-
-### Events
-
-- `esim.created` - New eSIM provisioned
-- `esim.activated` - eSIM activated on device
-- `usage.threshold` - Data usage threshold reached (50%, 75%, 90%)
-- `usage.depleted` - Data plan exhausted
-- `esim.terminated` - eSIM terminated
-
-### Webhook Payload
-
-```json
-{
-  "event": "usage.threshold",
-  "timestamp": "2026-04-01T12:00:00Z",
-  "data": {
-    "esim_id": "550e8400-e29b-41d4-a716-446655440000",
-    "threshold": 75,
-    "data_used": 805306368,
-    "data_limit": 1073741824
-  }
-}
-```
-
-## Examples
-
-### Create and Activate eSIM
-
-```bash
-# 1. Create eSIM
-curl -X POST https://api.taas-platform.com/v1/esims \
-  -H "Authorization: Bearer YOUR_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "data_plan": "1GB",
-    "country_code": "US"
-  }'
-
-# 2. Show QR code to user (activation_code)
-# User scans QR code on their device
-
-# 3. Monitor usage
-curl https://api.taas-platform.com/v1/esims/ESIM_ID/usage \
-  -H "Authorization: Bearer YOUR_API_KEY"
-```
-
-## Support
-
-- **Documentation**: https://docs.taas-platform.com
-- **API Status**: https://status.taas-platform.com
-- **Support Email**: support@taas-platform.com
-- **GitHub Issues**: https://github.com/nutcas3/telecom-platform/issues
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index b1b809d..01d0554 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,10 +1,21 @@
-# TaaS Platform Architecture
+# Architecture
+
+Comprehensive overview of the TaaS Platform system design, components, data flow, security, and RBAC.
+
+## Table of Contents
+
+1. [System Overview](#system-overview)
+2. [Component Details](#component-details)
+3. [Data Flow](#data-flow)
+4. [Scaling](#scaling)
+5. [Security & RBAC](#security--rbac)
+6. [Future Enhancements](#future-enhancements)
 
 ## System Overview
 
-The TaaS Platform is a multi-layer telecom infrastructure that provides cellular connectivity as a service. It implements 3GPP standards while exposing a modern, developer-friendly API.
+The TaaS Platform is a multi-layer telecom infrastructure that provides cellular connectivity as a service, implementing 3GPP standards while exposing a modern, developer-friendly API.
 
-## Architecture Layers
+### Architecture Layers
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -46,363 +57,264 @@ The TaaS Platform is a multi-layer telecom infrastructure that provides cellular
 
 ### 1. API Server (Go 1.26)
 
-**Purpose**: Developer-facing RESTful API and business logic
+**Purpose**: Developer-facing RESTful API and business logic.
 
-**Technology**:
-- Language: Go 1.26 (Green Tea GC, new(expr) syntax)
-- Framework: Gin
-- Database: MongoDB (subscriber data)
-- Cache: Redis (session management)
+**Stack**:
+- Gin framework
+- GORM with PostgreSQL (primary) / MongoDB (free5GC subscriber data)
+- Redis (session/cache)
+- Casbin for RBAC
+- WebSocket for real-time updates
 
 **Responsibilities**:
-- eSIM creation and management
-- Authentication and authorization
-- Rate limiting and quotas
+- eSIM lifecycle management
+- Authentication (JWT) and authorization (Casbin)
+- Rate limiting, quotas, and performance monitoring
 - Webhook delivery
-- API documentation
+- Health checks and alerting
 
-**Endpoints**:
-- `POST /v1/esims` - Create eSIM
-- `GET /v1/esims/:id` - Get eSIM details
-- `GET /v1/esims/:id/usage` - Get usage stats
-- `DELETE /v1/esims/:id` - Terminate eSIM
+**Key Endpoints**:
+- `/v1/auth/*` — authentication
+- `/v1/esims/*` — eSIM management
+- `/v1/services/*` — service operations
+- `/v1/monitoring/*` — metrics & alerts
+- `/v1/billing/*` — invoicing
+- `/ws` — WebSocket stream
+- `/health`, `/ready`, `/live` — probes
 
 ### 2. Carrier Connector (Go 1.26)
 
-**Purpose**: Integration with GSMA SM-DP+ servers for eSIM provisioning
-
-**Technology**:
-- Language: Go 1.26
-- Protocol: HTTPS (ES2+ API)
-- Vendor: Thales, G+D, or Idemia
-
-**Responsibilities**:
-- Profile ordering via ES2+ protocol
-- Activation code generation (LPA strings)
-- Profile status tracking
-- Vendor-specific adaptations
+**Purpose**: Integration with GSMA SM-DP+ servers for eSIM provisioning.
 
 **Flow**:
 1. Receive eSIM order from API Server
-2. Call SM-DP+ vendor API with IMSI, K, OPc keys
+2. Call SM-DP+ vendor API with IMSI, K, OPc keys (ES2+ over HTTPS)
 3. Receive activation code (LPA:1$...)
-4. Return to API Server for user display
+4. Return to API Server
+
+Supports multiple vendors: Thales, G+D, Idemia.
 
 ### 3. Charging Engine (Rust 1.94)
 
-**Purpose**: Real-time credit control and billing
+**Purpose**: Real-time credit control and billing.
 
-**Technology**:
-- Language: Rust 1.94 (array_windows, async Tokio)
-- Framework: Axum
-- Database: Redis (in-memory credit balances)
+**Stack**:
+- Axum (async web framework)
+- Redis for in-memory credit balances
+- Atomic INCR/DECR operations
 
-**Responsibilities**:
-- Credit balance management
-- Real-time authorization checks
-- Usage deduction (atomic operations)
-- Credit top-up processing
+**Endpoints**:
+- `POST /v1/credit/:ip/check` — authorization
+- `POST /v1/credit/:ip/deduct` — usage deduction
+- `POST /v1/credit/:ip/add` — top-up
+- `GET /v1/credit/:ip/balance` — balance query
 
-**API**:
-- `POST /v1/credit/:ip/check` - Check if user has credit
-- `POST /v1/credit/:ip/deduct` - Deduct bytes used
-- `POST /v1/credit/:ip/add` - Add credit
-- `GET /v1/credit/:ip/balance` - Get balance
-
-**Performance**:
-- Sub-millisecond response times
-- Atomic Redis operations (INCR, DECR)
-- Horizontal scaling via Redis Cluster
+**Performance**: Sub-millisecond p99, horizontally scalable via Redis Cluster.
 
 ### 4. Packet Gateway (Rust 1.94 + eBPF)
 
-**Purpose**: High-performance packet processing and traffic control
+**Purpose**: High-performance packet processing at line rate.
 
-**Technology**:
-- Language: Rust 1.94
-- Framework: Aya (pure Rust eBPF)
-- Attach Point: XDP (eXpress Data Path)
-- Protocol: GTP-U decapsulation (UDP port 2152)
-
-**Responsibilities**:
-- Parse GTP-U tunneled packets
-- Extract user IP addresses
-- Count bytes per subscriber
-- Block traffic for users without credit
-- Sync stats to Redis
+**Stack**:
+- Aya (pure Rust eBPF)
+- XDP (eXpress Data Path) hook
+- GTP-U decapsulation (UDP 2152)
 
 **Architecture**:
 ```
-┌─────────────────────────────────────────────┐
-│           Network Interface (eth0)          │
-└─────────────────────────────────────────────┘
-                    │
-          ┌─────────▼─────────┐
-          │   XDP Hook        │ ← eBPF program runs here
-          │   (Kernel)        │
-          └─────────┬─────────┘
-                    │
-          ┌─────────▼─────────┐
-          │   eBPF Maps       │
-          │  - Packet Stats   │
-          │  - Credit Status  │
-          └─────────┬─────────┘
-                    │
-          ┌─────────▼─────────┐
-          │  Userspace Daemon │ ← Rust application
-          │  (Reads maps,     │
-          │   syncs to Redis) │
-          └───────────────────┘
+NIC → XDP Hook (kernel eBPF) → eBPF Maps → Userspace Daemon → Redis
 ```
 
-**Packet Processing**:
+**Packet flow**:
 1. Packet arrives at NIC
-2. XDP hook inspects Ethernet → IP → UDP → GTP-U headers
-3. Extract inner IP packet (actual user data)
-4. Look up credit status in eBPF map
-5. If credit > 0: `XDP_PASS`, else: `XDP_DROP`
-6. Update packet statistics in eBPF map
-7. Userspace daemon reads stats, syncs to Redis
+2. XDP inspects Ethernet → IP → UDP → GTP-U headers
+3. Extract inner IP (user data), look up credit in eBPF map
+4. If credit > 0: `XDP_PASS`; else: `XDP_DROP`
+5. Userspace daemon syncs byte counters to Redis every 1s
 
-### 5. 5G Core Network (free5GC)
+### 5. 5G Core Network (free5GC v4.2.1)
 
-**Purpose**: 3GPP-compliant 5G standalone core
+3GPP-compliant 5G standalone core with all network functions (AMF, SMF, UPF, PCF, UDM, UDR, AUSF, NRF).
 
-**Technology**:
-- Project: free5GC v4.2.1
-- Language: Go
-- Database: MongoDB
-- Deployment: Kubernetes or bare metal
-
-**Network Functions**:
-- **AMF** (Access and Mobility Management)
-- **SMF** (Session Management)
-- **UPF** (User Plane Function)
-- **PCF** (Policy Control)
-- **UDM** (Unified Data Management)
-- **UDR** (Unified Data Repository)
-- **AUSF** (Authentication Server)
-- **NRF** (NF Repository)
-
-**Integration Points**:
+**Integration**:
 - API Server writes subscriber data to MongoDB
-- UPF forwards GTP-U traffic to Packet Gateway
-- AMF handles UE authentication using stored keys (K, OPc)
+- UPF forwards GTP-U to Packet Gateway
+- AMF authenticates using stored K/OPc keys
 
 ### 6. Web Dashboard (Next.js 15)
 
-**Purpose**: Developer portal and management interface
+- App Router, TypeScript, Tailwind CSS
+- TanStack Query for data fetching
+- Real-time updates via WebSocket
+- Error boundaries and loading states
 
-**Technology**:
-- Framework: Next.js 15 (App Router)
-- Language: TypeScript
-- Styling: Tailwind CSS
-- Data Fetching: TanStack Query
-
-**Features**:
-- eSIM creation and management
-- Real-time usage charts (Recharts)
-- API key management
-- Webhook configuration
-- Billing and invoices
+**Pages**: eSIM management, services, monitoring, billing, config, chaos engineering, plugins, automation.
 
 ## Data Flow
 
-### eSIM Creation Flow
+### eSIM Creation
 
 ```
-1. Developer → API Server
-   POST /v1/esims { data_plan: "1GB" }
-
-2. API Server → IMSI Allocator
-   Generate unique 15-digit IMSI
-
-3. API Server → Key Generator
-   Generate K (subscriber key)
-   Generate OPc (operator key)
-
-4. API Server → MongoDB (free5GC)
-   Insert subscriber data:
-   - subscriptionData.authenticationData (K, OPc)
-   - subscriptionData.provisionedData (IMSI, AMBR)
-
-5. API Server → Carrier Connector
-   Order eSIM profile via ES2+
-
-6. Carrier Connector → SM-DP+ Vendor
-   HTTPS POST with IMSI, K, OPc
-
-7. SM-DP+ → Carrier Connector
-   Return activation code (LPA string)
-
-8. API Server → Developer
-   Return eSIM details + activation code
-
-9. Developer → End User
-   Display QR code with LPA string
-
-10. End User's Device → SM-DP+
-    Scan QR, download eSIM profile
-
-11. Device → free5GC AMF
-    Registration procedure (5G AKA)
-
-12. free5GC → Packet Gateway
-    Establish GTP-U tunnel for data
+1. Developer → API Server: POST /v1/esims { data_plan: "1GB" }
+2. API Server → IMSI Allocator: generate 15-digit IMSI
+3. API Server → Key Generator: K + OPc
+4. API Server → MongoDB: insert subscriptionData
+5. API Server → Carrier Connector: order via ES2+
+6. Carrier Connector → SM-DP+: HTTPS POST (IMSI, K, OPc)
+7. SM-DP+ → Carrier Connector: activation code (LPA:1$...)
+8. API Server → Developer: eSIM + activation code
+9. End User scans QR → SM-DP+: profile download
+10. Device → free5GC AMF: 5G AKA registration
+11. free5GC → Packet Gateway: GTP-U tunnel established
 ```
 
-### Real-Time Usage Flow
+### Real-Time Usage
 
 ```
-1. User Device sends data
-   ↓
+1. User device sends data
 2. free5GC UPF encapsulates in GTP-U
-   ↓
-3. Packet Gateway (eBPF XDP)
-   - Decapsulate GTP-U
-   - Extract user IP
-   - Check credit status in eBPF map
-   ↓
-4. If credit > 0:
-   - Pass packet (XDP_PASS)
-   - Increment byte counter in eBPF map
-   ↓
-5. Userspace daemon (Rust)
-   - Reads eBPF maps every 1 second
-   - Writes stats to Redis
-   ↓
-6. Charging Engine
-   - Reads usage from Redis
-   - Deducts from credit balance
-   - Updates credit status
-   ↓
-7. Packet Gateway
-   - Reads new credit status from Redis
-   - Updates eBPF map
-   ↓
-8. If credit reaches 0:
-   - eBPF drops packets (XDP_DROP)
-   - User's internet stops
+3. Packet Gateway (eBPF XDP):
+   - Decapsulate, extract user IP
+   - Check credit in eBPF map
+4. If credit > 0: XDP_PASS + increment byte counter
+5. Userspace daemon: read eBPF maps → Redis (1s interval)
+6. Charging Engine: deduct from credit balance
+7. Packet Gateway: reload credit status from Redis → eBPF map
+8. If credit = 0: XDP_DROP (user traffic stops)
 ```
 
-## Scaling Architecture
+## Scaling
 
-### Horizontal Scaling
+### Horizontal (Stateless)
 
-**Stateless Components** (can be replicated):
 - API Server: 3+ replicas behind load balancer
 - Carrier Connector: 2+ replicas
 - Charging Engine: 2+ replicas
 - Web Dashboard: CDN + multiple origins
 
-**Stateful Components** (require special handling):
-- MongoDB: Replica set (1 primary, 2 secondaries)
-- Redis: Cluster mode or Sentinel
-- Packet Gateway: One instance per physical server (eBPF)
-- free5GC: Kubernetes deployment with dedicated UPF nodes
+### Stateful
 
-### Performance Metrics
+- MongoDB: replica set (1 primary, 2 secondaries)
+- PostgreSQL: primary + streaming replicas
+- Redis: Cluster or Sentinel
+- Packet Gateway: one per physical server (eBPF kernel binding)
+- free5GC: K8s deployment with dedicated UPF nodes
 
-**Throughput**:
-- API Server: 10,000 requests/second
-- Charging Engine: 50,000 credit checks/second
-- Packet Gateway: 10 Gbps+ per server (eBPF)
-- free5GC UPF: 5 Gbps per instance
+### Performance Targets
 
-**Latency**:
-- API Server: <50ms p99
-- Charging Engine: <1ms p99 (Redis)
-- Packet Gateway: <1µs (eBPF in kernel)
-- eSIM Provisioning: <2 seconds end-to-end
+| Component | Throughput | Latency (p99) |
+|-----------|-----------|----------------|
+| API Server | 10,000 req/s | <100ms |
+| Charging Engine | 50,000 checks/s | <1ms |
+| Packet Gateway | 10+ Gbps/server | <1µs (kernel) |
+| free5GC UPF | 5 Gbps/instance | — |
+| eSIM provisioning | — | <2s end-to-end |
 
-## Security
+## Security & RBAC
 
-### Authentication & Authorization
-- API keys with HMAC signatures
-- JWT tokens for web dashboard
-- OAuth 2.0 for third-party integrations
-- Rate limiting per API key
+### Authentication
+
+- **JWT** tokens for web dashboard and API
+- **API keys** with HMAC signatures for programmatic access
+- **OAuth 2.0** for third-party integrations
+- **Refresh tokens** for long-lived sessions
+
+JWT middleware (`@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/middleware/auth.go`) validates tokens on all protected routes.
+
+### RBAC with Casbin
+
+Sophisticated policy-based access control using Casbin with a GORM adapter for persistent policies.
+
+**Request flow**:
+```
+Request → AuthMiddleware (JWT) → CasbinRBAC (policy check) → Handler
+```
+
+**Model** (in `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/rbac/casbin.go`):
+
+```
+[request_definition]
+r = sub, obj, act
+
+[policy_definition]
+p = sub, obj, act
+
+[role_definition]
+g = _, _
+
+[policy_effect]
+e = some(where (p.eft == allow))
+
+[matchers]
+m = g(r.sub, p.sub) && keyMatch(r.obj, p.obj) && (r.act == p.act || p.act == "*")
+```
+
+**Default policies**:
+
+| Role | Permissions |
+|------|-------------|
+| `admin` | All resources, all actions |
+| `operator` | Services, monitoring, deployments (GET/POST) |
+| `viewer` | Read-only on all resources |
+
+**Usage in routes**:
+```go
+users := protected.Group("/users")
+if casbinSvc != nil {
+    users.Use(middleware.RequireCasbinPermission(casbinSvc, "/v1/users", "GET"))
+} else {
+    users.Use(middleware.RequireRole("admin")) // fallback
+}
+```
+
+**Policy management**:
+```go
+casbinSvc.AddPolicy("operator", "/v1/services/*", "GET")
+casbinSvc.AddRoleForUser("user123", "operator")
+allowed, err := casbinSvc.CheckPermission(userID, "/v1/services", "GET")
+```
 
 ### Data Encryption
-- TLS 1.3 for all API endpoints
-- MongoDB encryption at rest
-- Redis TLS connections
-- eBPF packet inspection (no decryption)
 
-### Secrets Management
-- Kubernetes Secrets for production
-- HashiCorp Vault for sensitive keys
-- Environment variables for local dev
+- TLS 1.3 for all API endpoints
+- MongoDB/PostgreSQL encryption at rest
+- Redis TLS connections
+- Secrets via Kubernetes Secrets or HashiCorp Vault
 - No hardcoded credentials
 
-## Deployment
+### Security Headers
 
-### Development
-```bash
-make all           # Build all components
-make db-setup      # Set up MongoDB + Redis
-make dev           # Start all services
+Applied globally via middleware:
+
+```
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+X-XSS-Protection: 1; mode=block
+Strict-Transport-Security: max-age=31536000; includeSubDomains
 ```
 
-### Docker Compose
-```bash
-docker-compose up -d
-```
+Plus request size limit (10MB), request timeout (30s), and CORS configuration.
 
-### Kubernetes
-```bash
-kubectl apply -f deployments/kubernetes/
-```
+### Rate Limiting
 
-### Production Checklist
-- [ ] MongoDB replica set configured
-- [ ] Redis Cluster or Sentinel enabled
-- [ ] TLS certificates installed
-- [ ] Monitoring (Prometheus, Grafana)
-- [ ] Logging (ELK Stack or Loki)
-- [ ] Backup strategy implemented
-- [ ] Disaster recovery plan documented
-- [ ] Load testing completed (10x expected traffic)
+Tiered limits protect against abuse (see `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/middleware/ratelimit.go`):
 
-## Monitoring
-
-### Metrics (Prometheus)
-- `api_requests_total` - Total API requests
-- `esim_creations_total` - eSIMs created
-- `data_usage_bytes_total` - Total data usage
-- `charging_checks_duration_seconds` - Credit check latency
-- `packet_gateway_packets_total` - Packets processed
-
-### Alerts
-- High error rate (>1%)
-- Low credit balances (<10% of users)
-- MongoDB replica lag (>10 seconds)
-- Redis memory usage (>90%)
-- Packet gateway packet loss (>0.1%)
+| Tier | Limit/min | Burst |
+|------|-----------|-------|
+| Auth | 10 | 5 |
+| Read | 200 | 50 |
+| Admin | 50 | 10 |
+| Default | 100 | 20 |
 
 ## Future Enhancements
 
-1. **Multi-Region Deployment**
-   - Deploy in multiple AWS regions
-   - Global load balancing with Route 53
-   - Data residency compliance
+1. **Multi-region deployment** — AWS multi-region with Route 53 global LB and data residency compliance.
+2. **Advanced analytics** — predictive usage forecasting, anomaly detection.
+3. **Additional carriers** — multi-vendor SM-DP+ with fallback.
+4. **IoT optimization** — SGP.32 (IoT eSIM), NB-IoT/LTE-M, power-saving features.
+5. **Developer tools** — expanded CLI, Terraform provider, GitHub Actions integration.
 
-2. **Advanced Analytics**
-   - Real-time dashboards with WebSockets
-   - Predictive usage forecasting
-   - Anomaly detection (unusual data patterns)
+## Related Docs
 
-3. **Additional Carriers**
-   - Support for multiple SM-DP+ vendors
-   - Dynamic carrier selection based on region
-   - Fallback mechanisms
-
-4. **IoT Optimization**
-   - SGP.32 support (IoT eSIM standard)
-   - LPWAN protocol support (NB-IoT, LTE-M)
-   - Power-saving features
-
-5. **Developer Tools**
-   - CLI tool for API interaction
-   - Terraform provider
-   - GitHub Actions integration
+- [`GETTING_STARTED.md`](./GETTING_STARTED.md) — Setup, API reference, SDKs
+- [`OPERATIONS.md`](./OPERATIONS.md) — Deployment, monitoring, performance tuning
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
deleted file mode 100644
index 66c1d11..0000000
--- a/docs/DEPLOYMENT.md
+++ /dev/null
@@ -1,454 +0,0 @@
-# Deployment Guide
-
-This guide covers deploying the TaaS Platform in different environments.
-
-## Table of Contents
-
-1. [Local Development](#local-development)
-2. [Docker Deployment](#docker-deployment)
-3. [Kubernetes Deployment](#kubernetes-deployment)
-4. [Production Considerations](#production-considerations)
-
----
-
-## Local Development
-
-### Prerequisites
-
-- Go 1.26+
-- Rust 1.94+
-- Node.js 22+
-- MongoDB 7.0+
-- Redis 7+
-- pnpm
-
-### Quick Start
-
-```bash
-# 1. Clone repository
-git clone https://github.com/nutcas3/telecom-platform.git
-cd telecom-platform
-
-# 2. Run setup script
-chmod +x scripts/dev-setup.sh
-./scripts/dev-setup.sh
-
-# 3. Set up databases
-make db-setup
-
-# 4. Build all components
-make all
-
-# 5. Start services (in separate terminals)
-# Terminal 1: API Server
-./dist/api-server
-
-# Terminal 2: Carrier Connector
-./dist/carrier-connector
-
-# Terminal 3: Charging Engine
-./target/release/charging-engine
-
-# Terminal 4: Web Dashboard
-cd apps/web-dashboard && pnpm dev
-```
-
-### Environment Variables
-
-Create `.env` files in each service directory:
-
-**apps/api-server/.env:**
-```env
-MONGODB_URI=mongodb://localhost:27017/free5gc
-REDIS_URI=redis://localhost:6379
-API_PORT=8000
-GIN_MODE=debug
-```
-
-**apps/charging-engine/.env:**
-```env
-REDIS_URI=redis://127.0.0.1/
-SERVER_PORT=8080
-RUST_LOG=info
-```
-
-**apps/web-dashboard/.env.local:**
-```env
-NEXT_PUBLIC_API_URL=http://localhost:8000
-```
-
----
-
-## Docker Deployment
-
-### Build Images
-
-```bash
-# Build all Docker images
-make docker-build
-
-# Or build individually
-docker build -f deployments/docker/api-server.Dockerfile -t taas-api-server .
-docker build -f deployments/docker/charging-engine.Dockerfile -t taas-charging-engine .
-docker build -f deployments/docker/web-dashboard.Dockerfile -t taas-web-dashboard .
-```
-
-### Run with Docker Compose
-
-```bash
-# Start all services
-docker-compose up -d
-
-# View logs
-docker-compose logs -f
-
-# Stop all services
-docker-compose down
-
-# Stop and remove volumes
-docker-compose down -v
-```
-
-### Service URLs
-
-After starting with docker-compose:
-
-- **API Server**: http://localhost:8000
-- **Charging Engine**: http://localhost:8080
-- **Web Dashboard**: http://localhost:3000
-- **MongoDB**: mongodb://localhost:27017
-- **Redis**: redis://localhost:6379
-
-### Troubleshooting
-
-**MongoDB connection issues:**
-```bash
-# Check if MongoDB is running
-docker-compose ps mongodb
-
-# View MongoDB logs
-docker-compose logs mongodb
-
-# Connect to MongoDB shell
-docker exec -it taas-mongodb mongosh
-```
-
-**Redis connection issues:**
-```bash
-# Test Redis connection
-docker exec -it taas-redis redis-cli ping
-```
-
----
-
-## Kubernetes Deployment
-
-### Prerequisites
-
-- Kubernetes cluster (v1.28+)
-- kubectl configured
-- Persistent storage provisioner
-- LoadBalancer service support (or Ingress controller)
-
-### Deploy to Kubernetes
-
-```bash
-# 1. Create namespace
-kubectl create namespace taas-platform
-
-# 2. Deploy all manifests
-kubectl apply -f deployments/kubernetes/
-
-# 3. Verify deployments
-kubectl get pods -n taas-platform
-
-# Expected output:
-# NAME                              READY   STATUS    RESTARTS   AGE
-# mongodb-xxx                       1/1     Running   0          2m
-# redis-xxx                         1/1     Running   0          2m
-# api-server-xxx                    1/1     Running   0          1m
-# charging-engine-xxx               1/1     Running   0          1m
-```
-
-### Access Services
-
-```bash
-# Get API Server external IP
-kubectl get svc api-server -n taas-platform
-
-# Port forward for local access
-kubectl port-forward -n taas-platform svc/api-server 8000:8000
-kubectl port-forward -n taas-platform svc/charging-engine 8080:8080
-```
-
-### Scaling
-
-```bash
-# Scale API Server
-kubectl scale deployment api-server -n taas-platform --replicas=5
-
-# Scale Charging Engine
-kubectl scale deployment charging-engine -n taas-platform --replicas=3
-
-# Enable autoscaling
-kubectl autoscale deployment api-server -n taas-platform \
-  --min=3 --max=10 --cpu-percent=70
-```
-
-### Monitoring
-
-```bash
-# View logs
-kubectl logs -f deployment/api-server -n taas-platform
-
-# Describe pod for issues
-kubectl describe pod <pod-name> -n taas-platform
-
-# Get events
-kubectl get events -n taas-platform --sort-by='.lastTimestamp'
-```
-
-### Update Deployment
-
-```bash
-# Update image
-kubectl set image deployment/api-server \
-  api-server=taas-api-server:v2.0.0 \
-  -n taas-platform
-
-# Check rollout status
-kubectl rollout status deployment/api-server -n taas-platform
-
-# Rollback if needed
-kubectl rollout undo deployment/api-server -n taas-platform
-```
-
----
-
-## Production Considerations
-
-### High Availability
-
-**MongoDB Replica Set:**
-```yaml
-# Use MongoDB Operator or StatefulSet
-apiVersion: apps/v1
-kind: StatefulSet
-metadata:
-  name: mongodb
-spec:
-  replicas: 3
-  serviceName: mongodb
-  # ... (see MongoDB Operator docs)
-```
-
-**Redis Cluster:**
-```bash
-# Deploy Redis in cluster mode
-helm install redis bitnami/redis-cluster \
-  --namespace taas-platform \
-  --set cluster.nodes=6 \
-  --set cluster.replicas=1
-```
-
-### Security
-
-**Secrets Management:**
-```bash
-# Create Kubernetes secrets
-kubectl create secret generic mongodb-secret \
-  --from-literal=username=admin \
-  --from-literal=password='STRONG_PASSWORD' \
-  -n taas-platform
-
-kubectl create secret generic api-keys \
-  --from-literal=jwt-secret='JWT_SECRET' \
-  -n taas-platform
-```
-
-**Network Policies:**
-```yaml
-apiVersion: networking.k8s.io/v1
-kind: NetworkPolicy
-metadata:
-  name: api-server-policy
-  namespace: taas-platform
-spec:
-  podSelector:
-    matchLabels:
-      app: api-server
-  policyTypes:
-  - Ingress
-  - Egress
-  ingress:
-  - from:
-    - podSelector:
-        matchLabels:
-          app: web-dashboard
-    ports:
-    - protocol: TCP
-      port: 8000
-  egress:
-  - to:
-    - podSelector:
-        matchLabels:
-          app: mongodb
-    ports:
-    - protocol: TCP
-      port: 27017
-```
-
-### Monitoring Stack
-
-**Prometheus & Grafana:**
-```bash
-# Install using Helm
-helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
-helm install prometheus prometheus-community/kube-prometheus-stack \
-  -n monitoring --create-namespace
-```
-
-**Application Metrics:**
-- Add `/metrics` endpoint to each service
-- Use Prometheus client libraries
-- Create Grafana dashboards
-
-### Backup Strategy
-
-**MongoDB Backups:**
-```bash
-# Daily backups with mongodump
-kubectl create cronjob mongodb-backup \
-  --image=mongo:7.0 \
-  --schedule="0 2 * * *" \
-  -- mongodump --uri=$MONGODB_URI --out=/backup
-```
-
-**Redis Persistence:**
-```bash
-# Enable AOF in Redis config
-kubectl edit configmap redis-config -n taas-platform
-# Set: appendonly yes
-```
-
-### Resource Limits
-
-**Recommended limits per service:**
-
-| Service | CPU Request | CPU Limit | Memory Request | Memory Limit |
-|---------|-------------|-----------|----------------|--------------|
-| API Server | 100m | 500m | 128Mi | 512Mi |
-| Charging Engine | 100m | 1000m | 128Mi | 512Mi |
-| Packet Gateway | 250m | 2000m | 256Mi | 1Gi |
-| MongoDB | 250m | 1000m | 512Mi | 2Gi |
-| Redis | 100m | 500m | 256Mi | 2Gi |
-
-### Load Testing
-
-```bash
-# Install k6
-brew install k6  # macOS
-# or: sudo apt-get install k6
-
-# Run load test
-k6 run scripts/loadtest.js
-```
-
-**Sample load test script:**
-```javascript
-import http from 'k6/http';
-import { check, sleep } from 'k6';
-
-export const options = {
-  stages: [
-    { duration: '2m', target: 100 },  // Ramp up
-    { duration: '5m', target: 100 },  // Stay at 100 users
-    { duration: '2m', target: 200 },  // Ramp to 200
-    { duration: '5m', target: 200 },  // Stay at 200
-    { duration: '2m', target: 0 },    // Ramp down
-  ],
-};
-
-export default function () {
-  const res = http.get('http://api-server:8000/health');
-  check(res, { 'status is 200': (r) => r.status === 200 });
-  sleep(1);
-}
-```
-
-### Disaster Recovery
-
-**Backup Locations:**
-- MongoDB backups: S3 bucket (cross-region replication)
-- Redis RDB snapshots: S3 bucket
-- Configuration: Git repository
-- Secrets: HashiCorp Vault or AWS Secrets Manager
-
-**Recovery Time Objective (RTO):** <1 hour
-**Recovery Point Objective (RPO):** <15 minutes
-
-**Recovery Procedure:**
-1. Spin up new Kubernetes cluster
-2. Restore MongoDB from latest backup
-3. Restore Redis from snapshot
-4. Deploy all services from Git
-5. Update DNS to point to new cluster
-6. Verify functionality
-
-### CI/CD Pipeline
-
-**GitHub Actions example:**
-```yaml
-name: Deploy
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  build-and-deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      
-      - name: Build Docker images
-        run: make docker-build
-      
-      - name: Push to registry
-        run: |
-          docker tag taas-api-server registry.example.com/taas-api-server:${{ github.sha }}
-          docker push registry.example.com/taas-api-server:${{ github.sha }}
-      
-      - name: Deploy to Kubernetes
-        run: |
-          kubectl set image deployment/api-server \
-            api-server=registry.example.com/taas-api-server:${{ github.sha }} \
-            -n taas-platform
-```
-
-### Cost Optimization
-
-**Cloud Provider Recommendations:**
-- Use spot/preemptible instances for non-critical services
-- Enable autoscaling to match load
-- Use reserved instances for predictable workloads
-- Store backups in cheaper storage classes (S3 Glacier)
-
-**Estimated Monthly Costs (AWS):**
-- 3x t3.medium (API Server): $90
-- 2x t3.medium (Charging Engine): $60
-- 1x t3.large (MongoDB): $75
-- 1x t3.small (Redis): $19
-- Load Balancer: $25
-- Data transfer: Variable
-- **Total**: ~$270/month (base infrastructure)
-
----
-
-## Support
-
-For deployment issues:
-- Check logs: `kubectl logs -f <pod-name>`
-- Review events: `kubectl get events`
-- Join community: [Discussions](https://github.com/taas-platform/discussions)
-- Email: devops@taas-platform.com
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
new file mode 100644
index 0000000..7922785
--- /dev/null
+++ b/docs/GETTING_STARTED.md
@@ -0,0 +1,299 @@
+# Getting Started
+
+This guide helps you get the Telecom-as-a-Service (TaaS) platform running locally and make your first API call.
+
+## Prerequisites
+
+- Docker & Docker Compose
+- Go 1.26+
+- Rust 1.94+
+- Node.js 22+
+- MongoDB 7.0+ / PostgreSQL 15+
+- Redis 7+
+- pnpm
+- Make
+
+## Quick Start (Docker Compose)
+
+The fastest path to a running platform:
+
+```bash
+git clone https://github.com/nutcas3/telecom-platform.git
+cd telecom-platform
+
+# Install deps and start core services
+make install-deps
+docker-compose up -d mongodb redis
+make free5gc-start
+docker-compose up -d api-server charging-engine carrier-connector
+
+# Start the dashboard
+make dev-ui
+
+# Verify everything is running
+make verify
+```
+
+### Service URLs
+
+| Service | URL |
+|---------|-----|
+| Web Dashboard | http://localhost:3000 |
+| API Server | http://localhost:8000 |
+| Charging Engine | http://localhost:8080 |
+| MongoDB | mongodb://localhost:27017 |
+| Redis | redis://localhost:6379 |
+
+## Local Development (Without Docker)
+
+```bash
+# 1. Setup
+chmod +x scripts/dev-setup.sh
+./scripts/dev-setup.sh
+make db-setup
+make all
+
+# 2. Start services (separate terminals)
+./dist/api-server
+./dist/carrier-connector
+./target/release/charging-engine
+cd apps/web-dashboard && pnpm dev
+```
+
+### Environment Variables
+
+**`apps/api-server/.env`:**
+```env
+MONGODB_URI=mongodb://localhost:27017/free5gc
+REDIS_URI=redis://localhost:6379
+API_PORT=8000
+GIN_MODE=debug
+JWT_SECRET=your-dev-secret
+```
+
+**`apps/charging-engine/.env`:**
+```env
+REDIS_URI=redis://127.0.0.1/
+SERVER_PORT=8080
+RUST_LOG=info
+```
+
+**`apps/web-dashboard/.env.local`:**
+```env
+NEXT_PUBLIC_API_URL=http://localhost:8000
+```
+
+## Your First API Call
+
+### 1. Authenticate
+
+```bash
+# Register
+curl -X POST http://localhost:8000/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "admin",
+    "email": "admin@example.com",
+    "password": "password123",
+    "first_name": "Admin",
+    "last_name": "User"
+  }'
+
+# Login
+TOKEN=$(curl -s -X POST http://localhost:8000/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"admin@example.com","password":"password123"}' \
+  | jq -r .token)
+```
+
+### 2. Create an eSIM
+
+```bash
+curl -X POST http://localhost:8000/v1/esims \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data_plan": "1GB",
+    "country_code": "US"
+  }'
+```
+
+Response:
+```json
+{
+  "esim_id": "550e8400-e29b-41d4-a716-446655440000",
+  "imsi": "208930000000001",
+  "iccid": "8933123456789012345",
+  "activation_code": "LPA:1$smdp.example.com$MATCHING_ID",
+  "status": "provisioned"
+}
+```
+
+### 3. Check Usage
+
+```bash
+curl http://localhost:8000/v1/esims/$ESIM_ID/usage \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+## API Reference
+
+### Base URL
+
+- Production: `https://api.taas-platform.com/v1`
+- Development: `http://localhost:8000/v1`
+
+### Authentication
+
+All protected endpoints require a Bearer token:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" ...
+```
+
+### Core Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/health` | System health |
+| GET | `/ready` | Readiness probe |
+| GET | `/live` | Liveness probe |
+| POST | `/v1/auth/register` | Create user |
+| POST | `/v1/auth/login` | Obtain tokens |
+| POST | `/v1/auth/refresh` | Refresh access token |
+| POST | `/v1/esims` | Create eSIM |
+| GET | `/v1/esims/:id` | Get eSIM |
+| GET | `/v1/esims/:id/usage` | Get usage |
+| DELETE | `/v1/esims/:id` | Terminate eSIM |
+| GET | `/v1/services` | List services |
+| GET | `/v1/monitoring/metrics` | System metrics |
+| GET | `/v1/monitoring/alerts` | Active alerts |
+| GET | `/v1/billing/invoices` | List invoices |
+| GET | `/v1/config` | Get config |
+| GET | `/metrics/performance` | Performance stats |
+| GET | `/ws` | WebSocket real-time updates |
+
+### Status Codes
+
+| Code | Meaning |
+|------|---------|
+| 200 | Success |
+| 201 | Created |
+| 400 | Bad request |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not found |
+| 429 | Rate limited |
+| 500 | Server error |
+| 503 | Service unavailable |
+
+### Rate Limits
+
+| Tier | Limit | Burst |
+|------|-------|-------|
+| Auth endpoints | 10/min | 5 |
+| Read endpoints | 200/min | 50 |
+| Admin endpoints | 50/min | 10 |
+| Default | 100/min | 20 |
+
+Response headers include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
+
+## SDKs
+
+### TypeScript
+
+```bash
+npm install @taas-platform/sdk
+```
+
+```typescript
+import { TaasClient } from '@taas-platform/sdk';
+
+const client = new TaasClient({ apiKey: process.env.TAAS_API_KEY });
+const esim = await client.esims.create({ dataPlan: '1GB', countryCode: 'US' });
+const usage = await client.esims.getUsage(esim.esimId);
+```
+
+### Go
+
+```bash
+go get github.com/taas-platform/sdk-go
+```
+
+```go
+import "github.com/taas-platform/sdk-go"
+
+client := taas.NewClient(os.Getenv("TAAS_API_KEY"))
+esim, err := client.ESims.Create(&taas.CreateESIMRequest{
+    DataPlan:    "1GB",
+    CountryCode: "US",
+})
+```
+
+## Webhooks
+
+Configure webhooks to receive real-time events:
+
+| Event | Trigger |
+|-------|---------|
+| `esim.created` | New eSIM provisioned |
+| `esim.activated` | eSIM activated on device |
+| `usage.threshold` | 50%/75%/90% of data used |
+| `usage.depleted` | Data plan exhausted |
+| `esim.terminated` | eSIM terminated |
+
+**Payload example:**
+```json
+{
+  "event": "usage.threshold",
+  "timestamp": "2026-04-01T12:00:00Z",
+  "data": {
+    "esim_id": "550e8400-...",
+    "threshold": 75,
+    "data_used": 805306368,
+    "data_limit": 1073741824
+  }
+}
+```
+
+## Common Commands
+
+```bash
+make help              # List all targets
+make all               # Build everything
+make verify            # Check services
+make free5gc-logs      # View free5GC logs
+make docker-build      # Build Docker images
+make clean             # Remove build artifacts
+```
+
+## Troubleshooting
+
+### Services won't start
+```bash
+docker-compose logs [service-name]
+docker-compose restart [service-name]
+```
+
+### Port conflicts
+Ensure ports 3000, 8000, 8080, 27017, 6379 are free.
+
+### Permission issues
+```bash
+chmod +x scripts/*.sh
+```
+
+### Database connection errors
+- Verify MongoDB/PostgreSQL is running: `docker-compose ps`
+- Check connection strings in `.env`
+- For PostgreSQL: confirm `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` are set
+
+## Next Steps
+
+- **Architecture**: See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for system design, RBAC, and security.
+- **Operations**: See [`OPERATIONS.md`](./OPERATIONS.md) for deployment, monitoring, and performance tuning.
+
+## Support
+
+- Issues: https://github.com/nutcas3/telecom-platform/issues
+- Discussions: https://github.com/nutcas3/telecom-platform/discussions
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
new file mode 100644
index 0000000..d17c91f
--- /dev/null
+++ b/docs/OPERATIONS.md
@@ -0,0 +1,425 @@
+# Operations
+
+Deployment, monitoring, performance tuning, and production operations for the TaaS Platform.
+
+## Table of Contents
+
+1. [Docker Deployment](#docker-deployment)
+2. [Kubernetes Deployment](#kubernetes-deployment)
+3. [Production Considerations](#production-considerations)
+4. [Performance & Optimization](#performance--optimization)
+5. [Monitoring & Alerting](#monitoring--alerting)
+6. [CI/CD](#cicd)
+7. [Backup & Disaster Recovery](#backup--disaster-recovery)
+
+## Docker Deployment
+
+### Build
+
+```bash
+make docker-build
+# Or individually
+docker build -f deployments/docker/api-server.Dockerfile -t taas-api-server .
+docker build -f deployments/docker/charging-engine.Dockerfile -t taas-charging-engine .
+docker build -f deployments/docker/web-dashboard.Dockerfile -t taas-web-dashboard .
+```
+
+### Run
+
+```bash
+docker-compose up -d
+docker-compose logs -f
+docker-compose down          # Stop
+docker-compose down -v       # Stop + remove volumes
+```
+
+### Troubleshooting
+
+```bash
+# MongoDB
+docker-compose ps mongodb
+docker-compose logs mongodb
+docker exec -it taas-mongodb mongosh
+
+# Redis
+docker exec -it taas-redis redis-cli ping
+```
+
+## Kubernetes Deployment
+
+### Prerequisites
+
+- Kubernetes v1.28+
+- `kubectl` configured
+- Persistent storage provisioner
+- LoadBalancer or Ingress controller
+
+### Deploy
+
+```bash
+kubectl create namespace taas-platform
+kubectl apply -f deployments/kubernetes/
+kubectl get pods -n taas-platform
+```
+
+### Access
+
+```bash
+kubectl get svc api-server -n taas-platform
+kubectl port-forward -n taas-platform svc/api-server 8000:8000
+```
+
+### Scale
+
+```bash
+kubectl scale deployment api-server -n taas-platform --replicas=5
+kubectl autoscale deployment api-server -n taas-platform \
+  --min=3 --max=10 --cpu-percent=70
+```
+
+### Rolling Updates
+
+```bash
+kubectl set image deployment/api-server \
+  api-server=ghcr.io/nutcas3/telecom-platform/api-server:v2.0.0 \
+  -n taas-platform
+kubectl rollout status deployment/api-server -n taas-platform
+kubectl rollout undo deployment/api-server -n taas-platform   # rollback
+```
+
+### Logs & Events
+
+```bash
+kubectl logs -f deployment/api-server -n taas-platform
+kubectl describe pod <pod-name> -n taas-platform
+kubectl get events -n taas-platform --sort-by='.lastTimestamp'
+```
+
+## Production Considerations
+
+### High Availability
+
+**PostgreSQL / MongoDB replica sets**:
+```yaml
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: mongodb
+spec:
+  replicas: 3
+  serviceName: mongodb
+  # See MongoDB Operator docs for full config
+```
+
+**Redis Cluster**:
+```bash
+helm install redis bitnami/redis-cluster \
+  --namespace taas-platform \
+  --set cluster.nodes=6 \
+  --set cluster.replicas=1
+```
+
+### Secrets Management
+
+```bash
+kubectl create secret generic db-secret \
+  --from-literal=username=admin \
+  --from-literal=password='STRONG_PASSWORD' \
+  -n taas-platform
+
+kubectl create secret generic api-keys \
+  --from-literal=jwt-secret="$(openssl rand -base64 32)" \
+  -n taas-platform
+```
+
+For production, prefer HashiCorp Vault or AWS Secrets Manager over raw K8s secrets.
+
+### Network Policies
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: api-server-policy
+  namespace: taas-platform
+spec:
+  podSelector:
+    matchLabels:
+      app: api-server
+  policyTypes: [Ingress, Egress]
+  ingress:
+    - from:
+        - podSelector:
+            matchLabels:
+              app: web-dashboard
+      ports:
+        - protocol: TCP
+          port: 8000
+  egress:
+    - to:
+        - podSelector:
+            matchLabels:
+              app: mongodb
+      ports:
+        - protocol: TCP
+          port: 27017
+```
+
+### Resource Limits
+
+| Service | CPU Request | CPU Limit | Mem Request | Mem Limit |
+|---------|------------:|----------:|------------:|----------:|
+| API Server | 100m | 500m | 128Mi | 512Mi |
+| Charging Engine | 100m | 1000m | 128Mi | 512Mi |
+| Packet Gateway | 250m | 2000m | 256Mi | 1Gi |
+| MongoDB | 250m | 1000m | 512Mi | 2Gi |
+| PostgreSQL | 250m | 1000m | 512Mi | 2Gi |
+| Redis | 100m | 500m | 256Mi | 2Gi |
+
+## Performance & Optimization
+
+### Rate Limiting
+
+In-memory sliding window with per-IP tracking. Configured via `middleware.RateLimitByEndpoint()` in `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/middleware/ratelimit.go`.
+
+| Tier | Limit/min | Burst | Applies To |
+|------|-----------|-------|------------|
+| Auth | 10 | 5 | `/v1/auth/login`, `/v1/auth/register` |
+| Read | 200 | 50 | `/v1/services`, `/v1/monitoring/metrics` |
+| Admin | 50 | 10 | `/v1/users`, `/v1/config` |
+| Default | 100 | 20 | Everything else |
+
+### Caching
+
+Layered in-memory LRU cache with TTL (`@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/cache/cache.go`):
+
+| Namespace | TTL | Max Items | Use |
+|-----------|-----|-----------|-----|
+| `default` | 5 min | 1000 | General purpose |
+| `users` | 10 min | 500 | User data |
+| `services` | 2 min | 200 | Service info |
+| `metrics` | 1 min | 1000 | Monitoring data |
+
+```go
+cache := cache.GetDefaultCache()
+cache.Set("key", value, 5*time.Minute)
+value, found := cache.Get("key")
+```
+
+The cached database wrapper (`@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/database/cached.go`) provides `CachedFind`, `CachedFirst`, `InvalidateCache`.
+
+### Connection Pooling
+
+Tuned in `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/database/database.go:50-54`:
+
+```go
+sqlDB.SetMaxIdleConns(25)                   // minimum idle
+sqlDB.SetMaxOpenConns(100)                  // maximum open
+sqlDB.SetConnMaxLifetime(time.Hour)
+sqlDB.SetConnMaxIdleTime(30 * time.Minute)
+```
+
+`db.PoolStats()` exposes live pool metrics for dashboards and alerts.
+
+### Performance Middleware
+
+Tracks response times, error rates, and slow requests (>100ms threshold). Adds:
+
+- `X-Response-Time` header
+- `X-Request-ID` correlation ID
+- Security headers (CSP, HSTS, X-Frame-Options)
+- Request size limit (10MB) and timeout (30s)
+
+**Metrics endpoint**: `GET /metrics/performance`
+
+### Performance Targets
+
+| Metric | Target |
+|--------|--------|
+| API response time (p50) | <50ms |
+| API response time (p99) | <100ms |
+| Uptime | 99.9% |
+| Error rate | <1% |
+| Test coverage | >80% |
+
+### Load Testing
+
+```bash
+brew install k6
+k6 run scripts/loadtest.js
+```
+
+Sample script:
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '2m', target: 100 },
+    { duration: '5m', target: 100 },
+    { duration: '2m', target: 200 },
+    { duration: '5m', target: 200 },
+    { duration: '2m', target: 0 },
+  ],
+};
+
+export default function () {
+  const res = http.get('http://api-server:8000/health');
+  check(res, { 'status is 200': (r) => r.status === 200 });
+  sleep(1);
+}
+```
+
+## Monitoring & Alerting
+
+### Health Checks
+
+Three probe endpoints (`@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/monitoring/health.go`):
+
+| Endpoint | Purpose |
+|----------|---------|
+| `/health` | Aggregated component health |
+| `/ready` | Kubernetes readiness probe |
+| `/live` | Kubernetes liveness probe |
+
+Monitored components: **database**, **Prometheus**, **Kubernetes**, **system** (memory, goroutines, GC).
+
+### Alert Rules
+
+Default rules in `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/monitoring/alerting.go`:
+
+| Rule | Threshold | Severity |
+|------|-----------|----------|
+| System Health | Degraded/Unhealthy | Warning |
+| High Memory | >80% | Warning |
+| High Goroutines | >1000 | Warning |
+| DB Connection Utilization | >80% | Warning |
+
+### Alert Notifiers
+
+- **WebSocket** — real-time dashboard
+- **Log** — structured logs
+- **Composite** — multiple channels simultaneously
+
+### Prometheus Metrics
+
+Key exported metrics:
+- `api_requests_total` — total request count
+- `esim_creations_total` — eSIMs created
+- `data_usage_bytes_total` — cumulative data usage
+- `charging_checks_duration_seconds` — credit check latency histogram
+- `packet_gateway_packets_total` — packets processed
+
+### Prometheus + Grafana Install
+
+```bash
+helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
+helm install prometheus prometheus-community/kube-prometheus-stack \
+  -n monitoring --create-namespace
+```
+
+### WebSocket Real-Time Events
+
+`GET /ws` streams:
+- Service status updates
+- System metrics
+- Alert notifications
+
+## CI/CD
+
+### GitHub Actions
+
+Two workflows in `.github/workflows/`:
+
+**`ci.yml`** — runs on every push/PR:
+- Go tests with PostgreSQL service container
+- `go vet` and `golangci-lint`
+- Web dashboard lint + typecheck + build
+- Docker image builds (on main)
+- Trivy security scan
+
+**`deploy.yml`** — runs on main pushes and version tags:
+- Build + push images to GHCR
+- Deploy to staging (main branch)
+- Deploy to production (version tags)
+
+Manual trigger via `workflow_dispatch` with environment input.
+
+### Local Testing
+
+```bash
+# Go tests with coverage
+cd apps/api-server
+go test ./... -v -race -coverprofile=coverage.out
+go tool cover -html=coverage.out
+
+# Benchmarks
+go test -bench=. ./internal/middleware/
+go test -bench=. ./internal/monitoring/
+
+# Linting
+golangci-lint run --timeout 5m
+go vet ./...
+go fix ./...
+```
+
+## Backup & Disaster Recovery
+
+### MongoDB Backup (CronJob)
+
+```bash
+kubectl create cronjob mongodb-backup \
+  --image=mongo:7.0 \
+  --schedule="0 2 * * *" \
+  -- mongodump --uri=$MONGODB_URI --out=/backup
+```
+
+### Redis Persistence
+
+Enable AOF for durability:
+```bash
+kubectl edit configmap redis-config -n taas-platform
+# Set: appendonly yes
+```
+
+### Recovery Objectives
+
+- **RTO** (Recovery Time Objective): <1 hour
+- **RPO** (Recovery Point Objective): <15 minutes
+
+### Recovery Procedure
+
+1. Spin up new Kubernetes cluster
+2. Restore database from latest backup (cross-region replicated)
+3. Restore Redis from RDB snapshot or rebuild from DB
+4. Deploy all services from Git (`kubectl apply -f deployments/kubernetes/`)
+5. Update DNS to new cluster
+6. Run `make verify` to confirm functionality
+
+### Backup Locations
+
+- **MongoDB/PostgreSQL**: S3 bucket with cross-region replication
+- **Redis**: S3 RDB snapshots
+- **Configuration**: Git repository
+- **Secrets**: HashiCorp Vault / AWS Secrets Manager
+
+## Cost Optimization
+
+- Use spot/preemptible instances for non-critical services
+- Enable autoscaling to match load
+- Reserved instances for predictable workloads
+- Store old backups in S3 Glacier
+
+**Sample monthly costs (AWS, base infrastructure)**:
+- 3× t3.medium (API Server): $90
+- 2× t3.medium (Charging Engine): $60
+- 1× t3.large (MongoDB): $75
+- 1× t3.small (Redis): $19
+- Load Balancer: $25
+- **Total**: ~$270/month + data transfer
+
+## Related Docs
+
+- [`GETTING_STARTED.md`](./GETTING_STARTED.md) — Setup and API reference
+- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — System design, RBAC, security
diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md
deleted file mode 100644
index b8d4dfd..0000000
--- a/docs/QUICK_START.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# Quick Start Guide
-
-## Overview
-
-This guide will help you get the Telecom-as-a-Service platform running in minutes.
-
-## Prerequisites
-
-- Docker & Docker Compose
-- Make command
-- Terminal access
-
-## 1. Initial Setup
-
-```bash
-# Clone the repository (if not already done)
-git clone https://github.com/nutcas3/telecom-platform.git
-cd telecom-platform
-
-# Install dependencies
-make install-deps
-```
-
-## 2. Start Core Services
-
-```bash
-# Start databases and core services
-docker-compose up -d mongodb redis
-
-# Start free5GC core network
-make free5gc-start
-
-# Start application services
-docker-compose up -d api-server charging-engine carrier-connector
-```
-
-## 3. Start Development Server
-
-```bash
-# Start web dashboard
-make dev-ui
-```
-
-## 4. Verify Deployment
-
-```bash
-# Check all services status
-make verify
-
-# Test free5GC configuration
-make free5gc-test
-```
-
-## 5. Access Services
-
-- **Web Dashboard**: http://localhost:3000
-- **API Server**: http://localhost:8000
-- **Charging Engine**: http://localhost:8080
-
-## 6. Common Commands
-
-```bash
-# View free5GC logs
-make free5gc-logs
-
-# Stop all services
-docker-compose down
-
-# Rebuild services
-make docker-build
-
-# Clean everything
-make clean
-```
-
-## Service Architecture
-
-```
-Internet
-    |
-[Web Dashboard] - [API Server] - [Carrier Connector]
-    |               |               |
-    |           [Charging Engine]  |
-    |               |               |
-    +-----------[free5GC Core]-----+
-                    |
-                [MongoDB] [Redis]
-```
-
-## Troubleshooting
-
-### Services Not Starting
-```bash
-# Check logs
-docker-compose logs [service-name]
-
-# Restart specific service
-docker-compose restart [service-name]
-```
-
-### Port Conflicts
-Ensure ports 3000, 8000, 8080, 27017, 6379 are available.
-
-### Permission Issues
-```bash
-# Fix script permissions
-chmod +x scripts/*.sh
-```
-
-## Next Steps
-
-1. Explore the API documentation at `/docs/API.md`
-2. Configure your first subscriber in the web dashboard
-3. Test the charging engine with sample data
-4. Deploy to Kubernetes using the provided manifests
-
-## Support
-
-- Check `make help` for all available commands
-- Review `docs/DEPLOYMENT.md` for production deployment
-- Check `todos.md` for development roadmap