System Architecture

arcx.run is a cloud-first AI development environment. This document describes the system components, data flow, and security model.

High-Level Overview


  Browser / CLI / Agent
        |
        | HTTPS (TLS 1.3)
        v
  +------------------+
  |  Cloudflare CDN  |  WAF, DDoS protection, TLS termination
  +------------------+
        |
        v
  +------------------+
  |    Traefik        |  Reverse proxy, routing, rate limiting
  +------------------+
        |
   +----+------+------+
   |           |      |
   v           v      v
+--------+ +-------+ +----------+
| Orch.  | | Proxy | | Team     |
| :3000  | | :3002 | | State    |
|        | |       | | :3001    |
+--------+ +-------+ +----------+
   |           |           |
   v           v           v
+------+   +------+   +------+
|Docker|   | PG   |   |  WS  |
|Engine|   | + PG |   | (ws) |
+------+   +------+   +------+
   |
   v
+-----------------------------+
| Workspace Containers        |
| (code-server + arcx-agent)  |
| per-user, isolated          |
+-----------------------------+

Components

Component	Port	Role
`orchestrator`	3000	Core API server. Handles auth, workspace lifecycle, billing, admin, webhooks, workflow engine. Serves the landing page, dashboard, and docs.
`arc-proxy`	3002	Secret-scrubbing reverse proxy. Sits between workspace containers and external APIs. Intercepts outbound requests and redacts secrets from logs and responses.
`team-state`	3001	Real-time collaboration service. WebSocket server for live cursor positions, file edits, and team presence. Backed by PostgreSQL.
`PostgreSQL`	5432	Primary data store. Users, sessions, workspaces, teams, audit log, billing, invite codes, waitlist.
`Traefik`	80/443	Edge proxy. Routes `*.arcx.run` to workspace containers, main domain to orchestrator. Handles TLS via Let's Encrypt.
`Prometheus`	9090	Metrics collection. Scrapes /metrics from all services.
`Grafana`	3003	Dashboards and alerting. Visualizes Prometheus data.
`NATS`	4222	Internal message bus for async events between services.

Data Flow: User Request to Workspace

1. Authentication

Browser --> GET /auth/github --> 302 to GitHub OAuth
GitHub  --> GET /auth/callback?code=xxx
Orch    --> exchanges code for access_token
Orch    --> fetches GitHub user profile
Orch    --> upserts user in PostgreSQL
Orch    --> creates HMAC-signed session token (arc_session cookie)
Orch    --> 302 to /dashboard

2. Workspace Creation

Browser --> POST /dashboard/workspace { name: "my-project" }
Orch    --> validates session cookie (HMAC verification)
Orch    --> checks tier limits (free: 1 workspace, pro: 5, team: 20)
Orch    --> docker.createContainer({
              Image: WORKSPACE_IMAGE,
              Labels: { "traefik.http.routers...": "my-project.arcx.run" },
              HostConfig: {
                Memory: 8GB, NanoCpus: 4 cores,
                PidsLimit: 512, SecurityOpt: [seccomp profile],
                NetworkMode: "arc-net"
              }
           })
Orch    --> stores workspace record in PostgreSQL
Orch    --> returns { url: "https://my-project.arcx.run" }

3. Workspace Access

Browser --> https://my-project.arcx.run
Traefik --> routes to workspace container (code-server)
User    --> full IDE with arcx-agent, MCP servers, terminal

Security Model

Authentication and Sessions

GitHub OAuth 2.0 — no passwords stored. Users authenticate via GitHub.
HMAC-SHA256 session tokens — signed with ARC_ADMIN_TOKEN, stored as HTTP-only cookies.
Signup modes — invite (closed beta), open (public), stripe (payment required).
RBAC — admin endpoints require Authorization: Bearer <ARC_ADMIN_TOKEN>.

Secret Scrubbing (arc-proxy)

All outbound API calls from workspaces route through arc-proxy.
Proxy intercepts requests and scrubs API keys, tokens, and credentials from logs.
Environment variables containing secrets are injected at runtime, never baked into images.
Audit log records all proxy-intercepted calls.

Container Isolation

Each workspace runs in an isolated Docker container on arc-net bridge network.
Resource limits: memory (8 GB default), CPU (4 cores), PID limit (512).
Optional seccomp profile for syscall filtering.
Containers cannot reach other workspace containers directly.
Idle timeout auto-stops workspaces after configurable inactivity period.

Network Security

Cloudflare provides DDoS protection, WAF rules, and TLS termination.
Traefik handles internal TLS and rate limiting.
Internal services communicate over arc-net Docker network (not exposed externally).
ARC_INTERNAL_TOKEN authenticates inter-service calls.

Monitoring and Audit

Prometheus scrapes all service metrics.
Grafana dashboards for workspace count, response times, error rates.
PostgreSQL audit log records: user actions, workspace lifecycle, admin operations.
GitHub and Stripe webhook events are logged and verified (signature validation).