Brok's Forge
The AI Engineering Operating System.
Most AI tooling tells you what happened. Brok’s Forge is built to tell you why your system is the way it is — the decisions behind it, the evidence for them, and the reasoning that connects the two, answered deterministically.
- 122public REST endpoints
- 499backend tests passing
- 34end-to-end browser tests
- 802Java files — 663 main · 139 test
- 10Maven modules
- 49public documentation pages
Ask Brok something.
A scripted walkthrough, not a live connection — but every behavior here is real and shipped: intent resolution, epistemic labeling, and refusal when the record can’t support an answer.
brok — grounded Q&A, zero LLM in the reasoning path
scripted, not liveask brok
resolved intent — prompt promotion rationale
v8 was promoted because it passed the evaluation profile v7 failed on hallucination detection — and the promoting engineer’s note is attached verbatim.
composed from
- · AI Git — promotion record, checkout-agent v8
- · Evaluation job #4471 (v7, failing)
- · Evaluation job #4483 (v8, passing)
fig. 00 — a scripted illustration of shipped behavior, not a live call to the API.
Teams lose the reasoning behind their AI systems.
The prompt is in version control, but why v8 replaced v7 is in a Slack thread. Evaluation results sit on a dashboard, but which decision they justified is recorded nowhere. The engineer who knew has moved on. Six weeks later something fails and nobody can reconstruct which change mattered.
Existing tooling answers the mechanical questions well — what did this request do, which calls were slow, did this prompt change break a test. It doesn’t answer the engineering questions: why was this promoted, what evidence covers it, has this happened before, what’s the blast radius of changing this dataset.
- The reasoning behind a decision, not just the decision itself
- Evidence that a promoted configuration is actually defensible
- Whether a failure has happened before, and what fixed it last time
- The blast radius of a change, known before you make it, not after
- A distinction between "nobody measured this" and "this is healthy"
Reasoning, modeled as a first-class object.
Brok’s Forge models the engineering act itself — artifacts, versions, observations, claims, decisions, evidence, knowledge — and derives its knowledge layer from work the engineer was doing anyway, rather than asking anyone to document anything. Promoting a version is a decision. Running an evaluation is evidence. Nobody writes documentation, so nothing rots.
And the reasoning layer contains no language model. Questions resolve to a fixed set of engineering intents and are answered by composing real rows — reproducible and auditable rather than merely plausible.
- Knowledge is derived, never authored and never generated
- Every statement declares how it’s known — Derived, Inferred, Suggested or Unknown
- Absence is never reported as health — an unmeasured artifact returns "unknown," not "passing"
- Positioning is deliberately non-competitive — the public comparison page concedes that LangSmith, Langfuse, Promptfoo and Weights & Biases are more mature at what they do
What Brok's Forge actually adds.
Six ideas, each doing one job. None of them own data they don't need to.
Brok
A grounded engineering assistant with no LLM in its reasoning path. Resolves a question to one of 25 engineering intents and composes the answer from real rows. Asked something the record can’t support, it refuses and offers what it can answer instead. Also produces standing briefs — daily, deployment, incident, prompt, evaluation, dataset, knowledge, architecture.
Root Cause Explorer
Opening a failure yields an already-assembled investigation: a dated chronology of the engineering that led there, the cause at four depths — immediate, contributing, historical, related change — the evidence and version chains, and every earlier failure on the same ground.
AI Git
Version control for engineering reasoning, not source. Records what was promoted, why, what it superseded and what evidence covered it — and displays a rollback as a rollback when production runs an older revision than the newest one. The reason an engineer writes at promotion time becomes Engineering Memory, recalled verbatim.
Engineering Intelligence
The derived layer: observations, claims, decisions, evidence and knowledge — all produced as a by-product of normal engineering work, never authored by hand.
Forge Graph
A live map of artifacts and their real relationships, built from what the system actually recorded rather than a maintained document. Narrowed to a single run it becomes the Execution Graph; narrowed to a failure, the Failure Graph.
Forge Kernel
A deliberately framework-free, append-only event log with its own API / core / TCK / PostgreSQL-store split. The Postgres adapter manages its own schema in a dedicated forge_kernel namespace and intentionally avoids Flyway, so the kernel inherits no application framework.
Also shipped
- Agent registry across frameworks, with per-provider health checking
- Provider management — Claude, GPT, Gemini, Groq, OpenRouter via Spring AI
- Encrypted agent credential storage with connection testing
- Prompt management with versioning and comparison
- Dataset management with versions, items and column mapping
- Evaluation profiles, versioned; evaluation jobs, runs and results
- Benchmark gallery — RAG, coding, hallucination, safety, summarization templates
- Execution Graph and Failure Graph, per run
- AI Git evolution, promotion, rollback and deployment timeline
- Organizations, projects, membership and role-based access
- Public documentation site — 49 pages, llms.txt, sitemap, JSON-LD
Five layers. Read down. Never duplicate.
Each layer can read everything beneath it and nothing above it, and is forbidden from duplicating a layer below — which is why adding a reasoning surface never means adding a table.
Read down. Never duplicate.
Engineering Applications
Brok, Root Cause Explorer, Briefs. Own no data.
Forge Graph
Artifacts, real relationships, reasoning on top.
AI Git
Revisions, promotions, rollbacks, rationale.
Registry
Every artifact and derived knowledge object.
Forge Kernel
Identity, tenancy, persistence, execution.
A modular monolith (Spring Boot) that depends on local Maven modules rather than microservices. The kernel and forge-* modules are separate, published-in-repo artifacts, consumed through public APIs only.
10 Maven modules — the repository, as it actually is
forge-fxp/
The experience platform composing every layer above into product. Currently v2.0.0.
Locked down where it actually matters.
A platform that holds credentials and calls endpoints outbound has to treat security as infrastructure, not a checklist added at the end.
Nothing exposed but the proxy
Postgres and Redis publish no host ports at all — reachable only over the internal Docker network. The backend isn’t bound to a host port either; only Nginx can reach it.
Secrets never leave the server
The JWT signing key, encryption key, database/Redis passwords and SMTP credentials live only in a .env on the server, deliberately not duplicated into GitHub Secrets. The deploy workflow never reads or transmits them.
A deploy key that can’t do much
A dedicated SSH keypair with strict host-key checking, written with umask 077 and removed under if: always(). The deploy job is guarded to the canonical repo owner, so a fork can’t trigger it.
HTTPS only
HTTP serves only the ACME challenge and a 301 redirect to HTTPS. Nothing else is reachable over plain HTTP.
The stack, exactly as shipped.
Backend
- Java 21
- Spring Boot 3.4.13
- Spring Security
- Spring Data JPA
- Spring AI
- Hibernate
- Flyway
- JWT (jjwt)
- MapStruct
- Lombok
- springdoc-openapi
- Micrometer / Prometheus
- Apache POI
- JSON Schema Validator
- Maven (multi-module)
Data
- PostgreSQL 16
- Redis 7
Frontend
- TypeScript
- Next.js 15 (App Router)
- React
- Tailwind CSS
- Radix UI
- Framer Motion
- next-themes
Testing
- JUnit 5
- Testcontainers
- JaCoCo
- Playwright
- Newman / Postman
Infra
- Docker
- Docker Compose
- BuildKit / Buildx
- Nginx
- Certbot
- AWS EC2
- Vercel
- GitHub Actions
- CodeQL
Deployed and operated, not just described.
A split deployment, both sides driven automatically by a push to main.
Browser
broksforge.gokul.quest
Vercel
Next.js 15 frontend
Nginx + Certbot
api.broksforge.gokul.quest — TLS terminator
Spring Boot API
built from source on the host
PostgreSQL 16 · Redis 7
internal Docker network only — no host ports
9 GitHub Actions workflows
- backend-ci
- frontend-ci
- docker
- e2e
- encoding
- codeql
- dependency-review
- deploy-production
- release
The production deploy is fully automatic and unattended: SSH, pull, build, apply, reload Nginx, wait for container health, verify the public HTTPS endpoint, prune. It tags the live image before building, so a backend that never becomes healthy is automatically rolled back, reloaded and re-checked.
Written down. Non-negotiable. Outranks the code.
Governed by a written three-volume constitution — identity, UX, design language — that outranks any implementation that conflicts with it.
- 01
Meaning before measurement
Every screen opens with what happened and why, never with raw data.
- 02
Nothing asserted that cannot be traced
An answer you have to independently verify hasn’t saved you the work of finding it.
- 03
Causality is the axis; time is an attribute
The record is organized around why, not when.
- 04
One substrate, many lenses
No surface owns its own data, so no two surfaces can disagree.
- 05
Depth chosen, never forced
The default view is meaning; detail is one click away, not a wall of it.
- 06
Objects, not pages; acts, not events
Decisions and evidence are things you can point at, not log lines.
- 07
There is no playground
Every trial is a real, recorded act — nothing tried is ever lost.
- 08
Never duplicate
One product, one navigation, one engineering language, one identity.
Reserved in the constitution. Not yet built.
Described here as planned — never as delivered.
The Exemplar
A read-only demonstration organization, so a visitor can explore a real engineering record without registering.
The Bench and Trials
An inner-loop workspace where every trial is a durable recorded act and nothing tried is lost.
The Question Language
Relationship queries over the record, instead of metric queries.
Four ingress doors at parity
UI, CLI, CI and API/SDK — each with its own laws.
Governance and audit
Including erasure reconciliation — content may be erased, but the existence of the act never is.
Architecture Diff & AI pull requests
Plus reports, production learning, and additional graph lenses — Impact, Delta.
Known follow-ups — stated honestly
Admitted, not discovered by someone else first.
- The automatic rollback path in the deploy pipeline is implemented and syntax-verified, but has never fired in anger — no deployment has yet failed its health gate.
- The kernel and forge-* modules install with tests skipped in CI, so their own suites don’t run there yet.
- The production host is resource-constrained — ~912 MB RAM, 8 GB root volume — and would benefit from a larger instance before further growth.
The platform is live. The source is public.
Ask Brok a question, read the design constitution, or open the source — everything on this page is verifiable, including the parts that admit what isn't finished yet.
Back to portfolio