Language: English | 简体中文 | 日本語

Aegis is a production-oriented, multi-tenant user platform built with Go for high concurrency, clean service boundaries, and realtime-ready delivery.

Platform Profile · Architecture · Technology Stack · Capability Map · API Reference · Deployment · Development

Platform Profile

Runtime Model Unified Go runtime for api + worker, with clear bootstrap boundaries and shared infrastructure clients.	Tenant Isolation Application boundaries are enforced through appid, with scoped session, cache, notification, and realtime paths.	Operational Focus Built around predictable hot paths, cache-first validation, async pipelines, and public-safe edge behavior.
Primary Storage PostgreSQL for transactional data, Redis for session, cache, unread-count, and presence indexing.	Async Backbone NATS handles event fan-out and decoupled processing; Temporal handles workflow orchestration.	Realtime Layer Gorilla WebSocket hub with Redis presence and NATS-based cross-instance targeted delivery.

Engineering Snapshot

Dimension	Description
Positioning	Multi-tenant backend platform for user systems and application-facing services
Runtime	Gin API + Worker runtime under a unified Go entrypoint
Isolation	appid-scoped services, caches, notifications, and online presence
Persistence	PostgreSQL
Cache and Presence	Redis
Messaging	NATS
Workflow	Temporal
Edge Security	Coraza WAF, transport encryption, sanitized responses

Architecture

flowchart LR
    Client[Web / Mobile / Admin]
    API[Gin API]
    Mid[Auth / WAF / Encryption / Location]
    Services[Domain Services]
    Realtime[Realtime Hub]
    Worker[Worker Runtime]
    PG[(PostgreSQL)]
    Redis[(Redis)]
    NATS[(NATS)]
    Temporal[(Temporal)]

    Client --> API
    API --> Mid
    Mid --> Services
    Services --> PG
    Services --> Redis
    Services --> NATS
    Services --> Temporal
    Services --> Realtime
    Realtime --> Redis
    Realtime --> NATS
    NATS --> Worker
    Worker --> PG
    Worker --> Redis
    Worker --> Temporal

Loading

Request Strategy

Authentication JWT parse + Redis session validation	Public App Content PostgreSQL + Redis cache	User View Cache-aware aggregation	Realtime Push Local hub + NATS fan-out
Online Presence Redis TTL indexes	Background Events NATS → Worker	Workflow Tasks Temporal execution	Public Errors Sanitized edge-safe responses

Technology Stack

Layer	Technology
Language	Go 1.26
HTTP	Gin
Database	PostgreSQL
Cache / Session / Presence	Redis
Messaging	NATS
Workflow	Temporal
Realtime	Gorilla WebSocket
Security	JWT, Coraza WAF, transport encryption
Logging	Zap
Deployment	Docker Compose, Windows scripts

Capability Map

Identity and Access Password authentication OAuth2 provider integration JWT issuance and validation Session indexing and revocation Layered administrator model

User Platform Profile and settings management Sign-in status and history Notification center Session auditing Points and ranking services

Realtime and Runtime Global WebSocket gateway Online presence indexing NATS cross-instance fan-out Worker event processing Temporal workflow execution

Realtime Model

The realtime layer is intentionally designed as an independent subsystem rather than a transport sidecar attached to business services.

Concern	Implementation
Connection lifecycle	in-process hub
Presence storage	Redis TTL indexes
Cross-node fan-out	NATS subjects
Tenant scope	appid + userId
Business integration	interface-based publisher

Realtime Endpoints

GET /api/ws
GET /api/admin/system/online/stats
GET /api/admin/system/online/apps/:appid
GET /api/admin/system/online/apps/:appid/users

API Reference

The project now ships with an auto-generated OpenAPI document and a modern built-in reference UI.

Artifact	Path
API reference	GET /docs
OpenAPI JSON	GET /openapi.json
Static export command	go run ./cmd/server openapi ./docs/openapi.json

Why this stack

• Uses kin-openapi for code-driven OpenAPI generation instead of Swagger-style annotation tooling.
• Uses a built-in offline-ready reference page so deployed environments do not depend on external CDNs.
• Keeps the documentation layer isolated from service logic so route evolution stays low-coupling.

Deployment Modes

Local Development cp .env.example .env docker compose -f deploy/docker/docker-compose.yml up -d go run ./cmd/server migrate go run ./cmd/server

Windows One-Click .\deploy\windows\one-click-deploy.cmd Support scripts: start-stack.cmd stop-stack.cmd status.cmd

Project Layout

cmd/
  api/                API entry
  server/             unified runtime entry
  worker/             worker entry
internal/
  bootstrap/          application assembly
  config/             configuration loading
  db/                 postgres / redis / nats / temporal clients
  domain/             domain contracts and types
  event/              subjects and publisher
  middleware/         auth, waf, encryption, location
  repository/         postgres, redis, legacy adapters
  service/            business orchestration
  transport/http/     gin handlers and router
deploy/
  docker/             docker runtime assets
  windows/            deployment scripts
migrations/postgres/  schema migrations
pkg/
  errors/             typed application errors
  logger/             logger bootstrap
  response/           response envelope
  tracing/            tracing integration

Expanded API Surface

Authentication

POST /api/auth/register/password
POST /api/auth/login/password
POST /api/auth/oauth2/auth-url
GET  /api/auth/oauth2/callback
POST /api/auth/oauth2/mobile-login
POST /api/auth/refresh
POST /api/auth/logout
POST /api/auth/password/verify
POST /api/auth/password/change

User

GET    /api/user/banner
GET    /api/user/notice
POST   /api/user/my
GET    /api/user/profile
PUT    /api/user/profile
GET    /api/user/settings
PUT    /api/user/settings
GET    /api/user/security
GET    /api/user/sessions
DELETE /api/user/sessions/:tokenHash
POST   /api/user/sessions/revoke-all
GET    /api/user/signin/status
GET    /api/user/signin/history
POST   /api/user/signin

Notifications

GET    /api/notifications
GET    /api/notifications/unread-count
POST   /api/notifications/read
POST   /api/notifications/read-batch
POST   /api/notifications/read-all
DELETE /api/notifications/:notificationId
POST   /api/notifications/clear

Development Workflow

Local Validation

go mod tidy
go test ./...

CI

GitHub Actions runs:

• dependency resolution
• go test ./...

Workflow file:

• .github/workflows/go-ci.yml

Security Notes

• Do not commit .env or production secrets.
• Keep sensitive configuration in environment variables or secret stores.
• Public-facing responses should not expose internal runtime details.

License

This project is released under a proprietary license. Commercial use and redistribution are prohibited without prior written permission. See LICENSE for the full text.