flagtide.
Public repository
Self-hosted feature flag service. Uses Quarkus as a backend which pushes flag updates to every open browser via WebSockets and has an Angular SDK which evaluates the flags locally with the same result as the server.
Left is the admin and right is the demo shop. Then there is a flag turned off and back on. A rollout changes from 20 to 60 and back to 30 percent. Then there is the propagation monitor showing p50, p95 and p99.
Live demo shows admin next to the shop using the same production images. Flags can be edited by anyone and the data is reset hourly back to the seed. Recording from the repository, no sound.
Why I built it.
I use feature flags on a daily basis. I had been wondering about two things. How can a flag update be propagated to thousands of open browsers in well under a second? How do you ensure that the same flag produces the same result in both the TypeScript client and the Java server?
I primarily develop in Angular but also develop Quarkus and Java back ends. This project straddles this divide. I also wanted one compact project that shows domain-driven design and hexagonal architecture on a real domain with real rules rather than a CRUD toy.
Try it in the demo.
The admin writes to one server instance and the shop listens to the other, so every change crosses PostgreSQL.
- Flag toggle
- Switch promo-banner off in the admin on the left. The banner leaves the shop on the right, although the shop listens to another server instance.
- Percentage rollout
- Open beta-recommendations and change the percentage in the default rule. The Browsing as field in the shop footer switches the visitor and the Recommended link appears or disappears in the shop.
- Try a context
- In the flag editor, enter a key and attributes under Try a context. The draft, including unsaved edits, is evaluated by the same evaluator used by the browser SDK.
- Propagation monitor
- The Propagation tab in the admin shows the time from commit to the client's acknowledgement: p50, p95 and p99.
- Overrides and status
- The Flags corner panel only overrides browser flags. The status of the flags (live, cached or offline) is indicated by the badge in the header.
Three hard parts.
Each decision has its ADR in the repository, with the alternatives that lost.
Two languages, one answer.
Rollouts uses hashing on the context key. If there is a difference in signed arithmetic, semver ordering, UTF-8 processing between the browser and server a user will be routed to a different rollouts variant. The algorithm is a written spec and both implementations are written by me. 616 common test vectors are run in both implementations as part of the CI process. An independent Python oracle provides the expected hash values. This means that a fault present in both implementations would be caught.
The cost: two MurmurHash3 implementations of my own instead of a library, and a spec with a version number.
What was lost: floating point percentages (rounding differs across languages), library hashes from Guava or npm (which would have masked the Unicode and signedness decisions), and expected values generated by the Java engine (enabling an undetected common flaw).
ADR 0009 on GitHubSeveral instances, no broker.
PostgreSQL NOTIFY is ordered but not durable and is limited to 8,000 bytes. This means the payload is only a pointer and every instance reads the change log after the version it has already seen. Listeners will also need to resync on reconnect. A test will kill the listener backend and verify the next change still arrives.
The cost is that the instance that wrote a change must make one extra round trip through the database before its own clients can view the change. This is a few milliseconds in compose.
So, what is lost? An external broker (Kafka, NATS, Redis), an additional moving piece while PostgreSQL already has the data, the full change in the payload, which breaks at the 8,000 byte limit, and polling which causes constant database load and latency.
ADR 0008 on GitHub5,000 sockets and a slow one.
Changes are serialized once per instance and are delivered to all sockets as the same string. If a connection has more than 256 frames pending, the connection is closed to avoid one stuck client from impacting the others.
The cost: each instance fans out from one thread, and a client that cannot keep up loses its connection.
What lost: a frame serialized per client (several times more allocation at 5,000 clients) and a thread per environment (the work per notification is one query and one string, and the fan-out is dominated by socket writes anyway).
ADR 0017 on GitHub
Numbers.
Only what the scripts in the repository measured.
- 77 ms
- p95 from commit to receipt in client. 30 changes, 150,000 frames, 5,000 WebSockets on two instances. p50 38 ms, p99 90 ms. Goal: <300 ms. 6 runs here on this machine with p95 ranging from 77 to 169 ms.
- 412 ns
- Mean time to evaluate a percentage rollout flag in @flagtide/core, in Node. 315 ns in headless Chromium. Target: under 5 µs.
- 616
- Shared conformance vectors, 419 of them evaluation cases. They run in Java and in TypeScript, and any mismatch stops CI.
- 30 to 80 ms
- From a click in the admin to the changed DOM in the shop, in a Cypress test on the full stack. Budget: one second.
- 1,327
- Testing in the server modules. 199 tests in @flagtide/core, 39 in @flagtide/angular, 200 in admin and 64 in shop. Line coverage: 98.7% in @flagtide/core and 99.1% in the server domain.
- 100
- Lighthouse accessibility on six admin pages and two shop pages, against the production images.
On one laptop using: Docker 29.1.3, Node 24.21, Linux under WSL2, Intel Core i7-12700H with 20 logical cores and 15.5 GiB of RAM. The clients, the servers and PostgreSQL were all on the same machine. These results are for that machine and do not represent communication between a phone and a data center.
The result files in bench/resultsWhat is not built.
Stretch goals went first. Tests and correctness never did.
- Flags that depend on flags
- They need a spec change, cycle detection and new vectors in both languages. One more place where Java and TypeScript could disagree.
- Scheduled changes
- They need a scheduler that fires exactly once across two instances. That is a design of its own.
- An Oracle adapter
- The ports already have contract tests, so the target is clear. The Oracle container in CI is heavy for a shared laptop.
- An SSE fallback
- With a second transport next to WebSockets, reconnect and status testing would double as well. The acknowledgement messages for the propagation monitor travel back on the same socket.
- A login for the admin
- Admin keys are passed to the browser via a config.json file. This works fine for this demo but is not suitable for a production system which should require login in front of the admin.
- Other browsers
- The end-to-end suite and every browser number come from Chrome. Firefox, Safari and screen readers are untested.
What comes next.
Start with the Oracle adapter. We already have contract tests that specify its requirements. Next, prerequisites with a cycle check. This will generate a spec change and new vectors in both languages. Finally, scheduled changes with a single runner across instances.
ADR 0021: what I did not buildTech
- Angular
- TypeScript
- RxJS
- Signals
- Angular Material
- Java
- Quarkus
- WebSockets
- REST API
- Docker
- Cypress
- Nx monorepo
- Hexagonal architecture
- DDD
Let's talk about the role.
Tell me about the team, the product and the stack.