telecom-platform/docs/GETTING_STARTED.md

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:

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)

# 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:

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:

REDIS_URI=redis://127.0.0.1/
SERVER_PORT=8080
RUST_LOG=info

apps/web-dashboard/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000

Your First API Call

1. Authenticate

# 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

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:

{
  "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

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:

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

npm install @taas-platform/sdk

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

go get github.com/taas-platform/sdk-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:

{
  "event": "usage.threshold",
  "timestamp": "2026-04-01T12:00:00Z",
  "data": {
    "esim_id": "550e8400-...",
    "threshold": 75,
    "data_used": 805306368,
    "data_limit": 1073741824
  }
}

Development Workflow

Running Tests

# Run all tests
make test

# Run API server tests
cd apps/api-server && go test ./...

# Run integration tests
cd apps/api-server && go test ./internal/handlers -v

# Run service layer tests
cd apps/api-server && go test ./internal/services -v

# Run with coverage
cd apps/api-server && go test -cover ./...

# Run specific test
cd apps/api-server && go test ./internal/handlers -run TestAuthenticationEndpoints -v

Code Quality

# Format code
cd apps/api-server && go fmt ./...
cd apps/web-dashboard && pnpm format

# Lint code
cd apps/api-server && golangci-lint run
cd apps/web-dashboard && pnpm lint

# Run static analysis
cd apps/api-server && go vet ./...

Database Operations

# Run database migrations
make db-migrate

# Reset database (development only)
make db-reset

# Create test data
make db-seed

# View database logs
docker-compose logs mongodb
docker-compose logs postgres

Monitoring & Debugging

# View service logs
make logs
make logs-api-server
make logs-charging-engine

# Monitor metrics
curl http://localhost:8000/metrics
curl http://localhost:8080/metrics

# Check health endpoints
curl http://localhost:8000/health
curl http://localhost:8000/ready
curl http://localhost:8000/live

Common Commands

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
make test              # Run all tests
make logs              # View all service logs
make dev-ui            # Start web dashboard in dev mode
make dev-api           # Start API server in dev mode

Troubleshooting

Services won't start

docker-compose logs [service-name]
docker-compose restart [service-name]

Port conflicts

Ensure ports 3000, 8000, 8080, 27017, 6379 are free.

Permission issues

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

Recent Improvements

Enhanced Error Handling

The platform now includes comprehensive error handling with standardized error responses:

• Structured error codes for different error types
• Field-specific validation errors with detailed messages
• Consistent error response format across all endpoints
• Request correlation IDs for debugging

Example error response:

{
  "error": "Validation failed",
  "code": "VALIDATION_FAILED",
  "details": "Invalid input data",
  "errors": [
    {
      "field": "email",
      "message": "must be a valid email address",
      "value": "invalid-email"
    }
  ]
}

Comprehensive Testing

The platform now has extensive test coverage:

• Integration tests for all API endpoints
• Service layer tests for business logic
• Authentication and RBAC testing with mock users
• Error handling validation across all scenarios

Run tests with:

cd apps/api-server && go test ./internal/handlers -v
cd apps/api-server && go test ./internal/services -v

Role-Based Access Control (RBAC)

Enhanced RBAC implementation using Casbin:

• Policy-based permissions with fine-grained control
• Default roles: admin, operator, viewer
• Dynamic policy management via API
• Fallback role middleware for compatibility

Example policy check:

allowed, err := casbinSvc.CheckPermission(userID, "/v1/services", "GET")

Next Steps

• Architecture: See ARCHITECTURE.md for system design, RBAC, and security.
• Operations: See 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