# Teamgram Server Architecture

> Teamgram Server architecture guide for building Telegram-compatible backends. Use when designing service topology, implementing MTProto services, or self-hosting Teamgram. Covers service拆分, data flow, deployment patterns, and development workflows based on the official teamgram/teamgram-server repository.

- Skill: `dvcrn/teamgram-server-architecture` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add dvcrn/teamgram-server-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/teamgram-server-architecture/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/teamgram-server-architecture

---


# Teamgram Server Architecture

Complete architecture guide based on the official teamgram/teamgram-server repository.

## Overview

Teamgram Server is an unofficial open-source MTProto server implementation in Go, compatible with Telegram clients and supporting self-hosted deployment.

**API Layer**: 223  
**MTProto Versions**: Abridged, Intermediate, Padded intermediate, Full

## Core Features

- ✅ **Private Chat** - End-to-end encrypted messaging
- ✅ **Basic Group** - Small group chats (up to 200 members)
- ⚠️ **Super Group** - Large groups (requires additional implementation)
- ✅ **Contacts** - Contact management and sync
- ✅ **Web** - Web client support

## Service Architecture

### High-Level Topology

```
                    ┌─────────────────┐
                    │   Load Balancer │
                    │    (Nginx/HA)   │
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
┌───────▼───────┐   ┌────────▼────────┐   ┌──────▼──────┐
│   gnetway     │   │   httpserver    │   │   session   │
│  (TCP/MTProto)│   │   (HTTP API)    │   │ (WebSocket) │
└───────┬───────┘   └────────┬────────┘   └──────┬──────┘
        │                    │                    │
        └────────────────────┼────────────────────┘
                             │
                    ┌────────▼────────┐
                    │   BFF Layer     │
                    │ (Business Logic)│
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
┌───────▼───────┐   ┌────────▼────────┐   ┌──────▼──────┐
│   Service     │   │    Service      │   │   Service   │
│   Layer       │   │    Layer        │   │   Layer     │
└───────────────┘   └─────────────────┘   └─────────────┘
```

### Interface Layer (app/interface)

| Service | Protocol | Purpose |
|---------|----------|---------|
| **gnetway** | TCP/MTProto | Main client gateway, handles MTProto encryption |
| **httpserver** | HTTP/REST | Bot API and webhooks |
| **session** | WebSocket | Web client connections |

### BFF Layer (app/bff)

Backend-for-Frontend aggregation layer:
- Aggregates multiple service calls
- Handles client-specific logic
- Reduces client-side complexity

### Service Layer (app/service)

| Service | Responsibility | Key Features |
|---------|----------------|--------------|
| **authsession** | Authentication & Session | Auth key management, session validation |
| **biz** | Core Business Logic | Chat, message, user, dialog, updates |
| **dfs** | Distributed File Storage | File upload/download, MinIO integration |
| **geoip** | Geo-location | IP geolocation for security |
| **idgen** | ID Generation | Snowflake-style distributed IDs |
| **media** | Media Processing | Thumbnail generation, FFmpeg integration |
| **status** | Online Status | User presence, last seen |

### Messenger Layer (app/messenger)

| Service | Purpose |
|---------|---------|
| **msg** | Message routing and delivery |
| **sync** | Multi-device synchronization |

## Biz Service Breakdown

The `biz` service is a monolithic business logic container:

```
app/service/biz/
├── biz/        # Core business operations
├── chat/       # Group/channel management
├── code/       # Verification codes (SMS/email)
├── dialog/     # Conversation management
├── message/    # Message storage and retrieval
├── updates/    # Real-time updates push
└── user/       # User profiles and settings
```

### Recommended Refactoring

For large-scale deployments, split `biz` into:

```
chat-service/      - Group & channel management
message-service/   - Message CRUD and search
user-service/      - User profiles and contacts
notification-service/ - Push notifications
```

## Data Flow

### Message Sending Flow

```
Client → gnetway → session → msg → message (biz)
                                           ↓
                                    MySQL (persist)
                                           ↓
                                    Kafka (broadcast)
                                           ↓
                              sync → updates → Client
```

### Authentication Flow

```
Client → gnetway → authsession
                        ↓
                   MySQL (auth_keys)
                        ↓
                   Redis (sessions)
```

### File Upload Flow

```
Client → gnetway → dfs → MinIO
                  ↓
               MySQL (file_metadata)
```

## Infrastructure Dependencies

| Component | Purpose | Required |
|-----------|---------|----------|
| **MySQL 5.7+** | Primary data store | ✅ Yes |
| **Redis** | Cache, sessions, deduplication | ✅ Yes |
| **etcd** | Service discovery & config | ✅ Yes |
| **Kafka** | Message pipeline, events | ✅ Yes |
| **MinIO** | Object storage | ✅ Yes |
| **FFmpeg** | Media transcoding | ⚠️ Optional |

## Project Structure

```
teamgram-server/
├── app/
│   ├── bff/              # Backend-for-Frontend
│   ├── interface/        # Gateway layer
│   │   ├── gnetway/      # MTProto gateway
│   │   ├── httpserver/   # HTTP API
│   │   └── session/      # WebSocket session
│   ├── messenger/        # Message routing
│   │   ├── msg/          # Message service
│   │   └── sync/         # Sync service
│   └── service/          # Core services
│       ├── authsession/  # Auth & session
│       ├── biz/          # Business logic
│       ├── dfs/          # File storage
│       ├── geoip/        # Geo location
│       ├── idgen/        # ID generator
│       ├── media/        # Media processing
│       └── status/       # Online status
├── pkg/                  # Shared packages
│   ├── code/             # Error codes
│   ├── conf/             # Configuration
│   ├── net2/             # Network utilities
│   └── ...
├── clients/              # Client SDKs
├── data/                 # SQL schemas
├── docs/                 # Documentation
└── specs/                # Architecture specs
```

## Development Workflow

### 1. Code Generation

Teamgram uses TL (Type Language) schema:

```bash
# Generate Go code from TL schema
make generate
# or
dalgenall.sh
```

### 2. Database Migration

```bash
# Initialize database
mysql -u root -p < data/teamgram.sql

# Run migrations
make migrate
```

### 3. Service Development Pattern

Each service follows this structure:

```
app/service/<name>/
├── cmd/              # Entry point
├── etc/              # Configuration
├── internal/
│   ├── config/       # Config structures
│   ├── core/         # Business logic
│   ├── dao/          # Data access
│   ├── server/       # gRPC/HTTP handlers
│   └── svc/          # Service context
└── <name>.go         # Main service file
```

### 4. Adding New RPC

1. Define in TL schema (`specs/mtproto.tl`)
2. Run code generation
3. Implement handler in `internal/core/`
4. Register in `internal/server/`
5. Update client SDKs

## Configuration

### Service Configuration (YAML)

```yaml
# app/service/biz/etc/biz.yaml
Name: biz
Host: 0.0.0.0
Port: 20001

MySQL:
  DataSource: user:password@tcp(localhost:3306)/teamgram?charset=utf8mb4

Redis:
  Host: localhost:6379

Etcd:
  Hosts:
    - localhost:2379
  Key: biz
```

### Environment Variables

```bash
# .env file
MYSQL_DATA_SOURCE=user:password@tcp(localhost:3306)/teamgram
REDIS_HOST=localhost:6379
ETCD_ENDPOINTS=localhost:2379
KAFKA_BROKERS=localhost:9092
MINIO_ENDPOINT=localhost:9000
```

## Deployment Patterns

### Docker Compose (Development)

```bash
docker-compose up -d
```

### Kubernetes (Production)

```yaml
# Example deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: teamgram-biz
spec:
  replicas: 3
  selector:
    matchLabels:
      app: teamgram-biz
  template:
    spec:
      containers:
      - name: biz
        image: teamgram/biz:latest
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "2Gi"
            cpu: "2000m"
```

## Scaling Considerations

### Horizontal Scaling

- **Stateless services**: biz, httpserver, dfs (easy to scale)
- **Stateful services**: gnetway (connection-based), session (session affinity)
- **Database**: MySQL read replicas, Redis Cluster

### Vertical Scaling

- **Media service**: CPU-intensive (FFmpeg)
- **Message service**: Memory-intensive (caching)
- **Auth service**: Low resource usage

## Security Best Practices

1. **Network Isolation**
   - Internal services behind VPC
   - Only gnetway/httpserver exposed publicly

2. **Encryption**
   - MTProto end-to-end encryption
   - TLS for HTTP/WebSocket
   - mTLS between services (optional)

3. **Authentication**
   - Auth keys in secure storage
   - Session tokens with expiration
   - Rate limiting per user/IP

4. **Data Protection**
   - Database encryption at rest
   - MinIO bucket encryption
   - Backup encryption

## Monitoring

### Metrics

```
- Request rate per service
- Response latency (p50, p95, p99)
- Error rates
- Active connections
- Message throughput
```

### Logging

```go
// Structured logging
log.Info().
    Str("service", "biz").
    Str("method", "messages.sendMessage").
    Int64("user_id", userID).
    Int64("msg_id", msgID).
    Dur("latency", duration).
    Msg("request processed")
```

## References

- [Architecture DeepWiki](https://deepwiki.com/teamgram/teamgram-server)
- [Service Topology](specs/architecture.md)
- [Dependencies](specs/dependencies-and-runtime.md)
- [Official Repository](https://github.com/teamgram/teamgram-server)

## See Also

- [references/service-development.md](references/service-development.md) - Step-by-step service creation
- [references/deployment.md](references/deployment.md) - Production deployment guide
- [references/tuning.md](references/tuning.md) - Performance optimization