Architecture Overview

AI Admin Panel is a single-binary application with an embedded frontend, backed by PostgreSQL, Valkey, Traefik, and Keycloak. This page describes the system architecture and how the components interact.

System Diagram

                        Internet
                           |
                      [Traefik v3]
                      (SSL, routing)
                     /      |       \
                    /       |        \
          [Panel]    [Keycloak]   [Deployed Services]
           |   |        |              |
        [PostgreSQL]  [PostgreSQL]  [Docker]
           |
        [Valkey]

All traffic enters through Traefik on ports 80/443. Traefik routes requests to the panel, Keycloak, or deployed services based on hostname matching.

Go Backend

The backend is written in Go 1.25 using the Echo v5 web framework.

Domain-Driven Design

Code is organized by domain:

internal/
  domain/
    service/        # Service entity, types, business logic
    customer/       # Customer entity, types, business logic
    template/       # Template entity, types, business logic
    plan/           # Service plan entity, types, business logic
    backup/         # Backup entity, types, business logic
    notification/   # Notification entity, types, business logic
  api/
    handler/        # HTTP handlers (one file per domain)
    middleware/     # Auth, logging, rate limiting middleware
    router.go       # Route registration
  repository/
    queries/        # SQL files for sqlc code generation
    generated/      # sqlc-generated Go code
  worker/           # Async job workers (River)
  templates/
    catalog/        # Template YAML specs (embedded)
    loader.go       # Template loading and compose generation

Key Patterns

Pattern	Usage
sqlc	SQL queries in internal/repository/queries/, code-generated Go types and functions
Interface-based DI	All dependencies injected via interfaces; nil-means-disabled for optional deps
River async jobs	Background work (deploys, backups, health checks) via {Job}Args + {Job}Worker structs
go:embed	Frontend files and template catalog embedded in the binary at compile time
Echo v5	HTTP routing, middleware, request binding, response rendering

Entry Point

cmd/panel/main.go wires all services, handlers, and workers together. The application startup:

1. Loads configuration from environment
2. Connects to PostgreSQL and runs migrations
3. Connects to Valkey
4. Initializes the OIDC provider (Keycloak)
5. Loads the template catalog from embedded files
6. Registers HTTP routes and middleware
7. Starts River workers for async jobs
8. Starts the Echo HTTP server

Frontend Embedding

The frontend is embedded in the binary via cmd/panel/embed.go:

//go:embed all:frontend/dist
var frontendFS embed.FS

The embed path is cmd/panel/frontend/dist/ — the frontend build output must be copied here before compiling the Go binary.

React Frontend

The frontend is built with React 19, Vite 7, shadcn/ui, and Tailwind v4.

Structure

frontend/src/
  features/
    dashboard/      # Dashboard page and components
    services/       # Service list, detail, deploy forms
    customers/      # Customer management
    templates/      # Template catalog and detail pages
    settings/       # Settings pages (AI, notifications, DNS, etc.)
    auth/           # Login, session management
  components/
    ui/             # shadcn/ui components (button, dialog, table, etc.)
    layout/         # App shell, sidebar, header
  hooks/            # Shared React hooks
  lib/              # Utility functions, API client
  routes/
    index.tsx       # Lazy-loaded route definitions

Key Patterns

Pattern	Usage
Feature-based structure	Each feature owns its components, hooks, and types
React Query	Server state management (@tanstack/react-query) — caching, refetching, mutations
WebSocket	Real-time updates for deploy progress, log streaming, health status
Lazy routes	Code-split routes for faster initial page load
shadcn/ui	Accessible, composable UI components built on Radix primitives

PostgreSQL 16

The primary data store for all application data:

• Service records, customer data, plans, backups
• Template metadata and deploy history
• Audit logs and event tracking
• Keycloak also uses PostgreSQL (separate database in the same instance)

Migrations are managed in Go and run automatically on startup.

Database Schema (Key Tables)

Table	Purpose
services	Deployed services with config, status, and metadata
customers	Customer/tenant records
service_plans	Plan definitions with quotas
backups	Backup records with status and storage location
deploy_logs	Deploy event history
notifications	Notification channel configuration
users	User records (synced with Keycloak)

Valkey 8

In-memory cache and session store:

• HTTP session data
• Template catalog cache
• Rate limiting counters
• Pub/sub for real-time WebSocket events
• Short-lived deploy state

Traefik v3

Reverse proxy and SSL terminator:

• Routes traffic to the panel, Keycloak, and deployed services based on hostname
• Automatic SSL via Let's Encrypt (HTTP-01 or DNS-01 challenge)
• Wildcard certificate support with Cloudflare DNS challenge
• Docker provider — automatically discovers containers with Traefik labels
• HTTP to HTTPS redirect on all routes

Keycloak 26

Identity provider for authentication and authorization:

• OIDC authorization code flow for browser login
• Realm: aiadminpanel with roles (admin, operator, viewer)
• Client: panel (confidential)
• User management with group-based customer association
• Custom dark-branded login theme

Docker

The panel communicates with Docker via the Docker socket (/var/run/docker.sock) to:

• Create and manage containers for deployed services
• Pull images from registries
• Manage volumes and networks
• Stream container logs
• Monitor container health and resource usage

All deployed services run as Docker containers on the aiadminpanel bridge network, making them accessible to Traefik and to each other via service name DNS.

Async Job Processing

Background work is processed by River, a PostgreSQL-based job queue:

Job	Purpose
DeployService	Pull images, create containers, start services
DeleteService	Stop containers, remove volumes, clean up DNS
BackupService	Create volume archives and database dumps
RestoreService	Restore from backup archives
HealthCheck	Periodic health monitoring for all services
DNSCreate	Create Cloudflare DNS records
DNSDelete	Remove Cloudflare DNS records
Notify	Send notifications across configured channels
AIAnalyze	AI-powered project analysis for AI Deploy