# Upstand — Full Technical Platform Documentation

Upstand is a container-first self-hostable control plane (PaaS) built with Bun, TypeScript, Next.js, Hono, tRPC, Drizzle, PostgreSQL 18, Redis 8, Docker Swarm, and Better Auth.

## 1. System Components & Architecture

### 1.1 Web Console (apps/web)
The dashboard interface is implemented in Next.js 16 App Router using React 19, Tailwind CSS v4, tRPC React Query client, and `@upstand/ui` primitives. It handles:
- Organization, project, and environment lifecycle management.
- Real-time build log streaming and container telemetry.
- UpGal AI assistant interactive chat with approval cards for mutating actions.
- Web SSH terminal connection to remote servers via secure WebSocket.

### 1.2 API Server & Broker (apps/server)
A high-throughput Hono HTTP server and WebSocket broker providing:
- tRPC API endpoints for all control-plane operations.
- Better Auth authentication handlers supporting Passkeys, TOTP, and Corporate SSO (SAML/OIDC).
- SCIM 2.0 endpoints (`/api/scim/v2.0/<orgId>`) for automated enterprise directory provisioning.
- Model Context Protocol (MCP) JSON-RPC endpoint at `/api/mcp` for external AI agent integration.
- Remote server terminal multiplexing and connection auditing.

### 1.3 Deployment Workers & Queues (packages/redis)
Background asynchronous workers orchestrated via BullMQ:
- Dedicated queues per node (`deployments-queue-<nodeId>`) to serialize builds and prevent CPU exhaustion.
- Support for Dockerfile, Railpack, Nixpacks, Heroku Buildpacks, Paketo Buildpacks, and static folder serving.
- Secret injection via BuildKit `--secret` flags preventing sensitive credentials from leaking into image layers.

### 1.4 Dynamic Caddy Edge Proxy
Upstand uses Caddy as its reverse proxy layer:
- Dynamic Caddyfile generation based on active project routes and domain bindings.
- In-container dry-run syntax verification prior to applying changes.
- In-memory atomic reload with 0 ms connection drops.
- Automated Let's Encrypt TLS certificate provisioning with Caddy internal CA fallback for air-gapped networks.
- Middleware: Basic auth, Forward auth with header forwarders, HSTS, 301/302/307/308 redirects.

### 1.5 Database Engine Provisioning
Natively provisions managed container instances of:
1. PostgreSQL 18 (with custom volume tuning and health probes)
2. MySQL 8.x
3. MariaDB 11.x
4. MongoDB 7.x
5. Redis 8.x (with persistence and auth tokens)
6. libSQL (sqld) with dynamic HTTP/gRPC/admin port bindings and JWT-derived authentication.

All databases support automated cron S3 backups via integrated `rclone` processes.

### 1.6 UpGal AI Assistant
An autonomous infrastructure operations assistant built on a bounded 12-step `ToolLoopAgent`:
- Capable of reading cluster status, inspecting container logs, generating Compose files, and troubleshooting deployments.
- Employs strict human-in-the-loop validation: actions classified as destructive or mutating (stopping a container, purging a volume, rolling back a database) generate a signed dashboard approval card requiring global owner confirmation.
- Exposes tools via MCP protocol with scoped API key permissions (`upk_...`).

## 2. CLI and Production Installer

The production installer is located at `install.sh`:

```bash
curl -fsSL https://upstand.dev/install.sh | sudo bash
```

Flags supported:
- `--interactive`: guided interactive installation.
- `--upgrade`: upgrades existing installation while taking a protected backup of PostgreSQL and Caddy configs.
- `--self-hosted`: sets default self-hosted mode.
- `--cloud`: sets cloud multi-tenant mode.

Environment variables:
- `UPSTAND_IMAGE_REPOSITORY`: custom image repository (defaults to ghcr.io/upstandplatform/upstand).
- `UPSTAND_ALLOW_SINGLE_REPLICA`: acknowledge single-replica deployment for dev hosts.
- `UPSTAND_ALLOW_UNDERSIZED_HOST`: bypass host requirement check (allows <2 vCPUs and <4GB RAM).
- `DATABASE_URL`: external high-availability PostgreSQL connection string.
- `REDIS_URL`: external high-availability Redis connection string.

## 3. Security Standards

- **Owner-First Bootstrap**: First user registration is designated Global Owner; public sign-ups are immediately locked.
- **SSO Domain Enforcement**: Domains verified via DNS TXT records (`_upstand-sso.<domain>`).
- **2FA Requirement**: TOTP multi-factor verification required for database resets, volume deletions, and terminal access.
- **Air-Gapped Ready**: Self-contained images and local Caddy CA allow fully offline deployment.