andwati/telecom-platform
1
0
Fork 0
mirror of https://github.com/andwati/telecom-platform.git synced 2026-10-18 02:52:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Restructure documentation with comprehensive architecture guide and new API reference

Browse Source 
- 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
This commit is contained in:
nutcas3
2026-04-19 04:35:53 +03:00
parent 8e30626252
commit 4e313a4298
6 changed files with 923 additions and 1099 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
-237
View File
@@ -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
docs/ARCHITECTURE.md
+199 -287
View File
@@ -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
docs/DEPLOYMENT.md
-454
View File
@@ -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
docs/GETTING_STARTED.md
+299
View File
@@ -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": "[email protected]",
"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":"[email protected]","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
docs/OPERATIONS.md
+425
View File
@@ -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
docs/QUICK_START.md
-121
View File
@@ -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