Architecture

GopherForge has 16 domain API services, an AI worker embedded in ai-service, shared packages, a React SPA and a Traefik gateway. The Hermes client and FreeSWITCH media stack run separately; external providers require user configuration.

Interactive platform subset

This retained diagram shows the seven foundation services, not the added business domains. The table below defines the complete service scope.

Open full screen

Services

Service	Responsibility
auth	Login, JWT access/refresh issuing & revocation, captcha, TOTP, OAuth, gateway ForwardAuth verification
identity	Users, roles, permissions, departments, positions, tenants & packages, data scopes, tenant isolation GORM plugin
system	Menus, dictionaries, notices, hot-reloadable settings, online users, SMS, error codes, code generator
audit	Login/operation/audit logs; consumes login events from NATS durably
file	Upload/download with local / MinIO / any S3-compatible storage
monitor	Server/PostgreSQL/Redis monitoring, cron jobs, health checks, Prometheus metrics; owns shared goose migrations and the gateway fallback route
bpm	Lightweight approval workflow engine — see Workflow
ai	AI chat, knowledge, agents, seats and a separate worker
crm	Customers, leads, assignment and follow-up
im	Messaging, conversations, visitors and dictionaries
pay	Payment configuration, orders and callbacks
mp	Official-account content and messages
notify	Channels, templates and delivery
ticket	Tickets, events and participants
cc	Agents, calls, billing, reporting and speech configuration
visibility	Business visualization and dashboards
shared	Shared packages within the same Go module, not a service

Request path

Browser
  └─▶ Traefik gateway :8000
        ├─ ForwardAuth ─▶ auth (verifies, injects X-Auth-* headers)
        └─ routes by PathPrefix ─▶ services
                                     └─ trust only gateway-injected
                                        X-Auth-User-ID / X-Auth-Tenant-ID

Security conventions: host ports bind loopback only, all external traffic goes through the gateway; services never parse JWTs themselves; internal service-to-service calls use a shared X-Internal-Token.

Data layer

• PostgreSQL 18 (pgvector image), one shared database, tables prefixed per service.
• Single migration source of truth: versioned goose SQL under services/monitor/migrations/, executed by the migrate container; experimental services (e.g. bpm) self-manage tables via GORM AutoMigrate.
• Redis 8: rate limiting, online users, token blacklist, permission cache.
• NATS JetStream: decouples login events from auth to audit (durable consumption).

Frontend

React 19 + TypeScript + Vite 8 + Ant Design 6, Redux Toolkit, Axios interceptors unwrapping the {code, message, data} envelope with transparent token refresh. Dual dark/light themes.

Dedicated Frontend documentation (stack, directory layout, request layer, routing & permissions, page conventions, state & theme, demo mode) lives under the Frontend section of the nav. Read Page Development before writing a new page — the shared list-page trio and component conventions will save you rework.

CI gates

Per-service go test + go vet, frontend lint/build/audit, plus three distinctive gates: OpenAPI contract drift detection, migration rehearsal on a clean database, and a full-stack smoke + Playwright E2E job.