Architecture

System Overview

The License Server is a full-stack application for managing software licenses, customers, and features. It provides a REST API, gRPC API, and a web-based admin UI.

Project Structure

license-server/
├── server/                    # Server application
│   ├── cmd/server/            # Entry point (main.go)
│   ├── cmd/                   # CLI commands (Cobra)
│   ├── biz/                   # Business logic
│   ├── data/                  # Data/Repository layer (Ent queries)
│   ├── server/                # HTTP/gRPC handler wiring
│   ├── service/               # Service layer (Proto → Biz bridge)
│   └── ui/                    # Embedded frontend assets
│
├── client/                    # Go client library (separate module)
│   ├── admin/                 # Admin HTTP client
│   ├── events/                # Event system
│   ├── offline/               # Offline mode (cache, .lic, reconnect)
│   └── examples/              # Usage examples
│
├── release/                   # Release tool
│   ├── cmd/release-tool/      # Entry point
│   ├── builder/               # Build logic
│   ├── docker/                # Docker build
│   ├── keys/                  # Key management
│   └── packager/              # Customer package generation
│
├── shared/                    # Shared code (used by server + client)
│   ├── auth/                  # JWT, LDAP, TOTP, Password
│   ├── config/                # Configuration (Viper)
│   ├── database/              # Database client
│   ├── ent/                   # Ent ORM (generated schemas)
│   ├── errors/                # Error handling
│   └── ...                    # Logging, metrics, etc.
│
├── web/                       # Frontend (React/TypeScript)
│   └── src/
│       ├── pages/             # Page components
│       ├── components/        # Shared components
│       ├── stores/            # Zustand stores
│       ├── hooks/             # React Query hooks
│       └── gen/               # Generated types from proto
│
├── api/                       # API definitions
│   ├── proto/                 # Protobuf definitions
│   └── gen/                   # Generated Go + TypeScript code
│
└── deployment/                # Docker, Compose, monitoring

Request Flow

HTTP Request

License Validation (gRPC)

Offline Licensing

The client supports a three-tier fallback chain for validation in disconnected environments:

Tier	Use Case	Duration	Requires Server
Online Validation	Normal operation	Realtime	Yes
Offline License (.lic)	Air-gapped / permanent offline	Up to 365 days	No
Grace Period Token	Temporary network outage	Typically 72h	Initially yes

Heartbeat Lifecycle

Client Session Lifecycle

Usage Tracking

Authentication & Authorization

Authentication methods:

Method	Format	Use Case
JWT	Bearer <token>	Web UI, interactive sessions
API Key	Bearer lsk_<key>	Programmatic access, CI/CD
LDAP	Via login endpoint	Enterprise SSO

Roles:

Role	Permissions
super_admin	Full access, manage admins + groups
admin	Manage customers/licenses within assigned groups
editor	Create/edit customers and licenses
viewer	Read-only access

Database

Supports SQLite (default) and PostgreSQL.

SQLite is recommended for single-instance deployments:

• WAL mode enabled for concurrent reads
• Foreign keys enforced
• Data stored in data/license.db

PostgreSQL is recommended for production/multi-instance:

• Full ACID compliance
• Connection pooling support
• Configured via environment variables or config.yaml

Schema management uses Ent ORM with auto-migration on startup.

Technology Stack

Layer	Technology
Framework	Go-Kratos (HTTP + gRPC)
ORM	Ent (schema-driven, code generation)
API	Protobuf + gRPC + google-annotations
Auth	JWT + TOTP (2FA) + LDAP + API Keys
Frontend	React 19 + Vite 7 + TailwindCSS + HeroUI
State	Zustand + React Query
Database	SQLite (mattn/go-sqlite3) / PostgreSQL
Metrics	Prometheus
Logging	Zerolog
CLI	Cobra + Viper
Signing	Ed25519 (license + offline files)
Encryption	AES-256-GCM (backups, offline cache)