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
  }
}

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

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

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