diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6b65a46
--- /dev/null
+++ b/README.md
@@ -0,0 +1,213 @@
+# Telecom-as-a-Service (TaaS) Platform
+
+> **Sovereign, Full-Stack Cellular Connectivity Platform**  
+> Built with Go 1.26, Rust 1.94, TypeScript, eBPF, and 5G Core Network Technologies
+
+## Overview
+
+This is a production-ready Telecom-as-a-Service platform that enables developers to programmatically provision and manage cellular connectivity through a clean API. The platform implements 3GPP standards using modern open-source technologies.
+
+**Technology Stack:**
+- **Go 1.26**: Core network integration, BSS API, carrier connector
+- **Rust 1.94**: eBPF packet gateway, real-time charging engine
+- **TypeScript/Next.js**: Developer dashboard and SDK
+- **free5GC**: Open-source 5G core network
+- **MongoDB**: Subscriber data and authentication
+- **Redis**: Real-time credit control
+- **eBPF/Aya**: High-performance packet processing
+
+## Quick Start
+
+### Prerequisites
+
+- **Go 1.26+**: [Download](https://go.dev/dl/)
+- **Rust 1.94+**: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+- **Node.js 22+**: [Download](https://nodejs.org/)
+- **pnpm**: `npm install -g pnpm`
+- **Docker**: [Install](https://docs.docker.com/get-docker/)
+- **MongoDB 7.0+**: [Install](https://www.mongodb.com/docs/manual/installation/)
+- **Redis**: `sudo apt-get install redis-server`
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/nutcas3/telecom-platform.git
+cd telecom-platform
+
+# Build all components
+make all
+
+# Start services (requires 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
+```
+
+## Project Structure
+
+```
+telecom-platform/
+├── apps/
+│   ├── api-server/          # Go: Developer BSS API
+│   ├── carrier-connector/   # Go: eSIM ES2+ Provisioning
+│   ├── charging-engine/     # Rust: OCS Real-time Credit Control
+│   ├── packet-gateway/      # Rust: eBPF UPF Data Plane
+│   └── web-dashboard/       # TypeScript: Next.js Frontend
+├── libs/
+│   ├── shared-ts-sdk/       # TypeScript: Drop-in Widget SDK
+│   └── proto/               # Shared Protobufs
+├── deployments/
+│   ├── kubernetes/          # K8s manifests
+│   └── docker/              # Dockerfiles
+├── docs/                    # Architecture & API docs
+├── scripts/                 # Automation scripts
+├── Makefile                 # Master build orchestrator
+├── Cargo.toml              # Rust workspace config
+├── go.work                 # Go workspace config
+└── pnpm-workspace.yaml     # TypeScript workspace config
+```
+
+## Development
+
+### Build Commands
+
+```bash
+# Build everything
+make all
+
+# Build specific language
+make build-go        # Go services
+make build-rust      # Rust components
+make build-ui        # TypeScript dashboard
+
+# Run tests
+make test
+
+# Clean artifacts
+make clean
+```
+
+### Working with Specific Components
+
+**Go Services:**
+```bash
+cd apps/api-server
+go run main.go
+```
+
+**Rust Components:**
+```bash
+cd apps/charging-engine
+cargo run --release
+```
+
+**TypeScript Dashboard:**
+```bash
+cd apps/web-dashboard
+pnpm dev
+```
+
+## Documentation
+
+- **[Complete TODO List](./todos.md)**: Comprehensive development roadmap
+- **[API Documentation](./docs/api-spec.yaml)**: OpenAPI 3.0 specification
+- **[Architecture Guide](./docs/architecture.md)**: System design and data flows
+- **[Deployment Guide](./docs/deployment.md)**: Kubernetes and Docker setup
+
+## Testing
+
+```bash
+# Unit tests
+make test
+
+# Go tests
+go test ./apps/...
+
+# Rust tests
+cargo test --workspace
+
+# TypeScript tests
+pnpm -r test
+```
+
+## Deployment
+
+### Docker
+
+```bash
+make docker-build
+docker-compose up -d
+```
+
+### Kubernetes
+
+```bash
+kubectl apply -f deployments/kubernetes/
+```
+
+## Environment Variables
+
+Create `.env` files in each service directory:
+
+**API Server** (`apps/api-server/.env`):
+```env
+MONGODB_URI=mongodb://localhost:27017/free5gc
+REDIS_URI=redis://localhost:6379
+API_PORT=8000
+JWT_SECRET=your-secret-key
+```
+
+**Charging Engine** (`apps/charging-engine/.env`):
+```env
+REDIS_URI=redis://localhost:6379
+SERVER_PORT=8080
+```
+
+**Web Dashboard** (`apps/web-dashboard/.env.local`):
+```env
+NEXT_PUBLIC_API_URL=http://localhost:8000
+```
+
+## 📖 Key Resources
+
+- **free5GC**: [https://free5gc.org/](https://free5gc.org/)
+- **Aya eBPF**: [https://aya-rs.dev/](https://aya-rs.dev/)
+- **GSMA eSIM Specs**: [https://www.gsma.com/esim/](https://www.gsma.com/esim/)
+- **Go 1.26 Docs**: [https://go.dev/doc/go1.26](https://go.dev/doc/go1.26)
+- **Rust 1.94 Blog**: [https://blog.rust-lang.org/2026/03/05/Rust-1.94.0/](https://blog.rust-lang.org/2026/03/05/Rust-1.94.0/)
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/yourorg/telecom-platform/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/yourorg/telecom-platform/discussions)
+- **Email**: support@yourcompany.com
+
+## Acknowledgments
+
+- **free5GC Team**: For the open-source 5G core implementation
+- **Aya Community**: For the pure-Rust eBPF framework
+- **GSMA**: For standardizing eSIM technology
+- **Go Team**: For the amazing Go 1.26 release
+- **Rust Team**: For continuous language improvements
+
diff --git a/deployments/docker/api-server.Dockerfile b/deployments/docker/api-server.Dockerfile
new file mode 100644
index 0000000..d92d607
--- /dev/null
+++ b/deployments/docker/api-server.Dockerfile
@@ -0,0 +1,22 @@
+FROM golang:1.26-alpine AS builder
+
+WORKDIR /app
+
+COPY apps/api-server/go.mod apps/api-server/go.sum ./
+RUN go mod download
+
+COPY apps/api-server/ ./
+
+RUN CGO_ENABLED=0 GOOS=linux go build -o api-server .
+
+FROM alpine:latest
+
+RUN apk --no-cache add ca-certificates
+
+WORKDIR /root/
+
+COPY --from=builder /app/api-server .
+
+EXPOSE 8000
+
+CMD ["./api-server"]
diff --git a/deployments/docker/carrier-connector.Dockerfile b/deployments/docker/carrier-connector.Dockerfile
new file mode 100644
index 0000000..0c1c14f
--- /dev/null
+++ b/deployments/docker/carrier-connector.Dockerfile
@@ -0,0 +1,20 @@
+FROM golang:1.26-alpine AS builder
+
+WORKDIR /app
+
+COPY apps/carrier-connector/go.mod apps/carrier-connector/go.sum ./
+RUN go mod download
+
+COPY apps/carrier-connector/ ./
+
+RUN CGO_ENABLED=0 GOOS=linux go build -o carrier-connector .
+
+FROM alpine:latest
+
+RUN apk --no-cache add ca-certificates
+
+WORKDIR /root/
+
+COPY --from=builder /app/carrier-connector .
+
+CMD ["./carrier-connector"]
diff --git a/deployments/docker/charging-engine.Dockerfile b/deployments/docker/charging-engine.Dockerfile
new file mode 100644
index 0000000..ad34fdd
--- /dev/null
+++ b/deployments/docker/charging-engine.Dockerfile
@@ -0,0 +1,27 @@
+FROM rust:1.94-slim AS builder
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y \
+    pkg-config \
+    libssl-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY Cargo.toml Cargo.lock ./
+COPY apps/charging-engine ./apps/charging-engine
+
+RUN cargo build --release --bin charging-engine
+
+FROM debian:bookworm-slim
+
+RUN apt-get update && apt-get install -y \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY --from=builder /app/target/release/charging-engine .
+
+EXPOSE 8080
+
+CMD ["./charging-engine"]
diff --git a/deployments/docker/web-dashboard.Dockerfile b/deployments/docker/web-dashboard.Dockerfile
new file mode 100644
index 0000000..1a532ce
--- /dev/null
+++ b/deployments/docker/web-dashboard.Dockerfile
@@ -0,0 +1,30 @@
+FROM node:22-alpine AS builder
+    
+WORKDIR /app
+
+RUN corepack enable
+
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY apps/web-dashboard ./apps/web-dashboard
+
+RUN pnpm install --frozen-lockfile
+
+RUN pnpm --filter web-dashboard build
+
+FROM node:22-alpine
+
+WORKDIR /app
+
+RUN corepack enable
+
+COPY --from=builder /app/apps/web-dashboard/.next ./apps/web-dashboard/.next
+COPY --from=builder /app/apps/web-dashboard/public ./apps/web-dashboard/public
+COPY --from=builder /app/apps/web-dashboard/package.json ./apps/web-dashboard/
+COPY --from=builder /app/apps/web-dashboard/next.config.js ./apps/web-dashboard/
+COPY --from=builder /app/node_modules ./node_modules
+
+WORKDIR /app/apps/web-dashboard
+
+EXPOSE 3000
+
+CMD ["pnpm", "start"]
diff --git a/deployments/kubernetes/00-namespace.yaml b/deployments/kubernetes/00-namespace.yaml
new file mode 100644
index 0000000..5c963ab
--- /dev/null
+++ b/deployments/kubernetes/00-namespace.yaml
@@ -0,0 +1,7 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: taas-platform
+  labels:
+    name: taas-platform
+    environment: production
diff --git a/deployments/kubernetes/01-mongodb.yaml b/deployments/kubernetes/01-mongodb.yaml
new file mode 100644
index 0000000..aa072f0
--- /dev/null
+++ b/deployments/kubernetes/01-mongodb.yaml
@@ -0,0 +1,93 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: mongodb-config
+  namespace: taas-platform
+data:
+  MONGO_INITDB_DATABASE: "free5gc"
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: mongodb-secret
+  namespace: taas-platform
+type: Opaque
+stringData:
+  MONGO_INITDB_ROOT_USERNAME: "admin"
+  MONGO_INITDB_ROOT_PASSWORD: "changeme-in-production"
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: mongodb-pvc
+  namespace: taas-platform
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 10Gi
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: mongodb
+  namespace: taas-platform
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: mongodb
+  template:
+    metadata:
+      labels:
+        app: mongodb
+    spec:
+      containers:
+      - name: mongodb
+        image: mongo:7.0
+        ports:
+        - containerPort: 27017
+        env:
+        - name: MONGO_INITDB_ROOT_USERNAME
+          valueFrom:
+            secretKeyRef:
+              name: mongodb-secret
+              key: MONGO_INITDB_ROOT_USERNAME
+        - name: MONGO_INITDB_ROOT_PASSWORD
+          valueFrom:
+            secretKeyRef:
+              name: mongodb-secret
+              key: MONGO_INITDB_ROOT_PASSWORD
+        - name: MONGO_INITDB_DATABASE
+          valueFrom:
+            configMapKeyRef:
+              name: mongodb-config
+              key: MONGO_INITDB_DATABASE
+        volumeMounts:
+        - name: mongodb-storage
+          mountPath: /data/db
+        resources:
+          requests:
+            memory: "512Mi"
+            cpu: "250m"
+          limits:
+            memory: "2Gi"
+            cpu: "1000m"
+      volumes:
+      - name: mongodb-storage
+        persistentVolumeClaim:
+          claimName: mongodb-pvc
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: mongodb
+  namespace: taas-platform
+spec:
+  selector:
+    app: mongodb
+  ports:
+  - port: 27017
+    targetPort: 27017
+  type: ClusterIP
diff --git a/deployments/kubernetes/02-redis.yaml b/deployments/kubernetes/02-redis.yaml
new file mode 100644
index 0000000..d1aa8ac
--- /dev/null
+++ b/deployments/kubernetes/02-redis.yaml
@@ -0,0 +1,46 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: redis
+  namespace: taas-platform
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: redis
+  template:
+    metadata:
+      labels:
+        app: redis
+    spec:
+      containers:
+      - name: redis
+        image: redis:7-alpine
+        ports:
+        - containerPort: 6379
+        command:
+        - redis-server
+        - --maxmemory
+        - "2gb"
+        - --maxmemory-policy
+        - allkeys-lru
+        resources:
+          requests:
+            memory: "256Mi"
+            cpu: "100m"
+          limits:
+            memory: "2Gi"
+            cpu: "500m"
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: redis
+  namespace: taas-platform
+spec:
+  selector:
+    app: redis
+  ports:
+  - port: 6379
+    targetPort: 6379
+  type: ClusterIP
diff --git a/deployments/kubernetes/03-api-server.yaml b/deployments/kubernetes/03-api-server.yaml
new file mode 100644
index 0000000..4096862
--- /dev/null
+++ b/deployments/kubernetes/03-api-server.yaml
@@ -0,0 +1,77 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: api-server-config
+  namespace: taas-platform
+data:
+  API_PORT: "8000"
+  GIN_MODE: "release"
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api-server
+  namespace: taas-platform
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: api-server
+  template:
+    metadata:
+      labels:
+        app: api-server
+    spec:
+      containers:
+      - name: api-server
+        image: taas-api-server:latest
+        imagePullPolicy: IfNotPresent
+        ports:
+        - containerPort: 8000
+        env:
+        - name: MONGODB_URI
+          value: "mongodb://admin:changeme-in-production@mongodb:27017/free5gc"
+        - name: REDIS_URI
+          value: "redis://redis:6379"
+        - name: API_PORT
+          valueFrom:
+            configMapKeyRef:
+              name: api-server-config
+              key: API_PORT
+        - name: GIN_MODE
+          valueFrom:
+            configMapKeyRef:
+              name: api-server-config
+              key: GIN_MODE
+        resources:
+          requests:
+            memory: "128Mi"
+            cpu: "100m"
+          limits:
+            memory: "512Mi"
+            cpu: "500m"
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 8000
+          initialDelaySeconds: 30
+          periodSeconds: 10
+        readinessProbe:
+          httpGet:
+            path: /health
+            port: 8000
+          initialDelaySeconds: 5
+          periodSeconds: 5
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: api-server
+  namespace: taas-platform
+spec:
+  selector:
+    app: api-server
+  ports:
+  - port: 8000
+    targetPort: 8000
+  type: LoadBalancer
diff --git a/deployments/kubernetes/04-charging-engine.yaml b/deployments/kubernetes/04-charging-engine.yaml
new file mode 100644
index 0000000..62d59d3
--- /dev/null
+++ b/deployments/kubernetes/04-charging-engine.yaml
@@ -0,0 +1,60 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: charging-engine
+  namespace: taas-platform
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: charging-engine
+  template:
+    metadata:
+      labels:
+        app: charging-engine
+    spec:
+      containers:
+      - name: charging-engine
+        image: taas-charging-engine:latest
+        imagePullPolicy: IfNotPresent
+        ports:
+        - containerPort: 8080
+        env:
+        - name: REDIS_URI
+          value: "redis://redis:6379"
+        - name: SERVER_PORT
+          value: "8080"
+        - name: RUST_LOG
+          value: "info"
+        resources:
+          requests:
+            memory: "128Mi"
+            cpu: "100m"
+          limits:
+            memory: "512Mi"
+            cpu: "1000m"
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 8080
+          initialDelaySeconds: 10
+          periodSeconds: 10
+        readinessProbe:
+          httpGet:
+            path: /health
+            port: 8080
+          initialDelaySeconds: 5
+          periodSeconds: 5
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: charging-engine
+  namespace: taas-platform
+spec:
+  selector:
+    app: charging-engine
+  ports:
+  - port: 8080
+    targetPort: 8080
+  type: ClusterIP