Architecture and API

A self-hosted feature-flag service: a Spring Boot API, client libraries that evaluate flags in memory, live updates over Server-Sent Events, and an Angular dashboard. It's built and hosted for ₹0, with no payment card on any provider.

For what it does in plain language, see the user guide.

Working name. Rename freely before the first public release (check the GitHub org, npm and Maven Central first).

#Goals

1. Show backend depth in Spring Boot: API design, multi-tenant data, an audit trail, caching, live push and failure handling.
2. Fast flag checks: libraries evaluate flags locally in memory (target: well under 1 ms per check, no network call).
3. Instant changes: a flag change reaches connected clients within about a second.
4. Failure safety: if the server is down or asleep, clients keep serving their last known flags.
5. Free forever: free tiers only, no card on file, and easy to move if a provider changes its terms.

#Architecture

 Dashboard (Angular, Cloudflare Pages)
        │  admin API (Bearer GitHub sign-in session, or the admin token)
        ▼
 Switchyard server (Spring Boot 4, GraalVM native image, Render free)
        │  Postgres (Neon free) · Flyway migrations · audit log
        │
        ├── GET /sdk/v1/flags      full flag set, ETag + 304 for cheap polling
        └── GET /sdk/v1/stream     SSE: "version" event on every change, ping every 25 s
              ▲
   Java / JS client libraries: cache flags in memory, evaluate locally,
   poll as a fallback, keep the last good copy when the server is unreachable

#Key design decisions

#Data model

• projects: key, name
• environments: per project (development, production by default), sdk_key_hash, sdk_key_hint, version
• flags: per project, key, name, description, archived_at
• flag_states: one row per flag × environment: enabled, version, updated_at
• audit_log: actor, action, flag, environment, before / after (JSON)

Phase 3 added rules and fallthrough (JSON) to flag_states: targeting rules and percentage rollouts, evaluated by the clients as spec/EVALUATION.md defines.

Phase 5b added users (GitHub id, login, name, avatar), sessions (token hash, expiry), sign_in_attempts (OAuth state hash, where to return) and audit_log.reverts_id.

Phase 9 added users.role (viewer, editor, admin) and environments.is_protected (Production starts protected), then environments.requires_approval, pending_changes (change requests and scheduled changes: pending_approval → scheduled → applied, or rejected / cancelled / failed), api_tokens (hashed, with a role and an optional project) and webhooks.

Phase 8 added environments.client_id (public) and flags.client_side.

Phase 7 added flags.type and flags.variations (multivariate flags), flag_states.off_variation and flag_states.prerequisites, and segments (per project: included and excluded keys, rules). Segment changes bump every environment of the project.

#API

Admin (Authorization: Bearer <session token from GitHub sign-in>, Bearer <API token> or Bearer <SWITCHYARD_ADMIN_TOKEN>):

Browsers (public client-side ID in the path; CORS open to every origin):

Sign-in (no token):

SDK (Authorization: Bearer <sdk key>):

#Phases

#Free hosting (verify each limit when deploying, and record the date)

Avoid: Render's free Postgres (expires after about 30 days) and Supabase free (pauses after a week idle) for this project.

#Numbers to measure (for the write-up)

• Flag checks per second and time per check in the Java library (JMH)
• /sdk/v1/flags latency: 200 vs 304
• Time for a change to reach 1,000 connected SSE clients (k6)
• Native image vs JVM: startup time and memory on the free instance
• Client behaviour with the server stopped: errors seen by the app (target: 0)

#Measured so far

To verify on Render (phase 6): whether an open SSE stream counts as traffic for the free tier's 15-minute sleep timer. Run the load test with ./mvnw verify -Dtest=StreamLoadTests -Dswitchyard.load=true.

View this page's source on GitHub