barycenter/book/src/getting-started/architecture.md

Architecture

Barycenter uses a three-port architecture where each port serves a distinct role. All three servers share a single database connection pool, JWKS manager, and application state.

Three-Port Design

graph TB
    subgraph "Barycenter Process"
        subgraph "Public Server (port 8080)"
            OIDC["OIDC Endpoints"]
            Auth["Authentication"]
            WebAuthn["WebAuthn/Passkeys"]
            Device["Device Authorization"]
            UserInfo["UserInfo"]
        end

        subgraph "Admin Server (port 8081)"
            GQL["GraphQL API"]
            Jobs["Job Management"]
            UserMgmt["User Management"]
        end

        subgraph "Authz Server (port 8082)"
            Policy["Policy Evaluation"]
            KDL["KDL Policy Engine"]
        end

        State["Shared Application State"]
        JWKS["JWKS Manager"]
        Scheduler["Background Job Scheduler"]
    end

    DB[(Database<br/>SQLite or PostgreSQL)]

    OIDC --> State
    Auth --> State
    WebAuthn --> State
    Device --> State
    GQL --> State
    Policy --> State
    State --> DB
    State --> JWKS
    Scheduler --> DB

    Client["OIDC Clients"] --> OIDC
    Browser["User Browsers"] --> Auth
    Browser --> WebAuthn
    Admin["Admin Tools"] --> GQL
    Services["Backend Services"] --> Policy

Public Server (default port 8080)

The public server handles all user-facing and client-facing OIDC operations:

• Discovery: /.well-known/openid-configuration and /.well-known/jwks.json
• Client Registration: POST /connect/register
• Authorization: GET /authorize with PKCE enforcement
• Token Exchange: POST /token (authorization code, refresh token, device code grants)
• Token Revocation: POST /revoke
• UserInfo: GET /userinfo
• Authentication: Login pages, password verification, WebAuthn flows
• Device Authorization: POST /device/authorize and GET /device verification page
• Consent: User consent approval and tracking

Admin Server (default port 8081)

The admin server exposes a GraphQL API on the port immediately following the public port. It is intended for internal management and should not be exposed to the public internet.

• User Management: Query users, set 2FA requirements
• Job Control: Trigger background jobs manually, view execution history
• System Queries: List available jobs, check user status

Authorization Policy Server (default port 8082)

The authorization policy server runs on the second port after the public port. It evaluates access control decisions using KDL-defined policies.

• Policy Evaluation: HTTP API for checking authorization decisions
• ReBAC + ABAC: Combines relationship-based and attribute-based access control

Technology Stack

Component	Technology	Purpose
Language	Rust (stable)	Systems language with memory safety
Web framework	axum	Async HTTP framework built on tokio and hyper
Database ORM	SeaORM	Async ORM supporting SQLite and PostgreSQL
JWT/JOSE	josekit	JSON Web Token creation and signing
WebAuthn	webauthn-rs	FIDO2/WebAuthn server implementation
GraphQL	async-graphql	GraphQL server for the admin API
Scheduling	tokio-cron-scheduler	Cron-based background job scheduling
Password hashing	argon2	Memory-hard password hashing
Configuration	config-rs + TOML	Layered configuration with file and environment support
WASM client	wasm-pack + wasm-bindgen	Browser-side WebAuthn operations

Startup Sequence

When Barycenter starts, it follows this initialization order:

sequenceDiagram
    participant CLI as CLI Parser
    participant Cfg as Settings
    participant DB as Database
    participant Mig as Migrations
    participant JWKS as JWKS Manager
    participant WA as WebAuthn
    participant GQL as GraphQL Schemas
    participant Sched as Scheduler
    participant Srv as Servers

    CLI->>Cfg: 1. Parse --config flag and subcommands
    Cfg->>Cfg: 2. Load defaults + config.toml + env vars
    Cfg->>DB: 3. Initialize database connection pool
    DB->>Mig: 4. Run pending migrations
    Mig->>JWKS: 5. Initialize JWKS (generate or load RSA keys)
    JWKS->>WA: 6. Initialize WebAuthn configuration
    WA->>GQL: 7. Build GraphQL schemas (admin + authz)
    GQL->>Sched: 8. Start background job scheduler
    Sched->>Srv: 9. Start all three servers concurrently

1. Parse CLI: Read --config path and any subcommands (e.g., sync-users --file)
2. Load settings: Merge default values, configuration file, and environment variables
3. Initialize database: Create connection pool to SQLite or PostgreSQL
4. Run migrations: Apply any pending schema migrations automatically
5. Initialize JWKS: Generate a 2048-bit RSA key pair on first run, or load existing keys from disk
6. Initialize WebAuthn: Configure the WebAuthn relying party based on the server's public URL
7. Build GraphQL schemas: Construct the async-graphql schemas for admin and authorization APIs
8. Start scheduler: Register cron jobs for cleanup of sessions, tokens, and challenges
9. Start servers: Launch all three HTTP servers concurrently on their respective ports

All three servers share the same tokio runtime and application state. If any server fails to bind its port, the entire process exits with an error.