How Agent Forge
was engineered

System Architecture

Agent Forge is a monorepo with a shared TypeScript codebase. The frontend and backend run as a single Node.js process in production, with Vite handling the client bundle. All API traffic flows through tRPC procedures — there are no REST endpoints for feature logic.

  Browser (React 19 + Tailwind 4)
  │
  ├── tRPC Client (TanStack Query)  ──────────────────────────────┐
  │   └── trpc.*.useQuery / useMutation                          │
  │                                                               ▼
  ├── Web Speech API (real-time STT)          Express Server (Node.js)
  │   └── SpeechRecognition → interim text    │
  │                                           ├── tRPC Router
  └── Audio playback (base64 MP3)             │   ├── auth.*        (OAuth, session)
                                              │   ├── simulation.*  (scenarios, sessions)
                                              │   ├── courses.*     (AI authoring)
                                              │   ├── sandbox.*     (flags, personas)
                                              │   ├── agentic.*     (5-agent system)
                                              │   └── coaching.*    (personas, chat, TTS, report)
                                              │
                                              ├── LLM (GPT-4 class)
                                              │   └── invokeLLM()
                                              │
                                              ├── ElevenLabs TTS
                                              │   └── elevenLabsTTS() → MP3 buffer
                                              │
                                              ├── Drizzle ORM
                                              │   └── TiDB Serverless (MySQL)
                                              │
                                              └── AWS S3
                                                  └── storagePut() / storageGet()

Voice Simulation Data Flow

The voice simulation loop was redesigned from a 4-step manual process (record → stop → transcribe → send) to a fully automatic cycle. The user speaks; the AI responds. No buttons, no waiting, no decisions.

Technology Stack

Every dependency was chosen for a specific reason — not defaults or familiarity. The table below maps each library to the problem it solves.

Key Engineering Decisions

The decisions below reflect deliberate trade-off analysis — each one had a clear problem, a considered solution, and an acknowledged downside. This is the kind of reasoning that distinguishes architecture from assembly.

Database Schema

19 tables in TiDB Serverless (MySQL-compatible), defined in drizzle/schema.ts with full TypeScript inference. All timestamps are stored as UTC; all scores are stored as floats to support fractional precision.

Product Modules

Agent Forge is composed of 7 independent product modules, each with its own routes, tRPC router, and database tables. Modules are loosely coupled — a user can use the course builder without ever touching the simulation engine.

Testing & Code Quality

All server-side logic is covered by Vitest unit tests. TypeScript strict mode is enabled across the entire monorepo. The CI check runs tsc --noEmit and vitest run before every deployment.

Security Model

Agentic Orchestration System

Agent Forge includes a 5-agent orchestration layer that operates autonomously on learner data. Each agent has a single responsibility and writes its outputs to dedicated database tables, which the Agentic Dashboard reads in real time.

Learning Science Foundations

Agent Forge's architecture is grounded in three evidence-based learning science frameworks. Each framework directly informs a distinct technical component — the connection between pedagogy and engineering is explicit, not incidental.

50-Point Competency Rubric

Every simulation session is automatically scored across 6 competency domains by the Evaluation Agent. The rubric satisfies three requirements simultaneously: pedagogical validity (scores reflect genuine competency), production alignment (categories map to enterprise QA frameworks), and predictive power (simulation scores correlate with real-world performance).

Scoring uses a criterion-referenced approach — scores reflect absolute competency against defined standards, not relative performance against peers. The rubric deliberately targets Bloom's Levels 3–6 (Apply, Analyse, Evaluate, Create) — not recall or comprehension.

Coaching Agent — 3-Tier Intervention System

The Coaching Agent monitors learner actions in real time and delivers contextual interventions calibrated to avoid disrupting simulation flow. Research shows that forced scaffolding creates dependency — so interventions are severity-tiered and non-intrusive by design.

Inter-Agent Communication — Cascade Example

The orchestration layer manages a shared state bus where agents publish events and subscribe to relevant signals. A single learner action can trigger a coordinated cascade across all five agents simultaneously. The example below shows what happens when a critical compliance error is detected.

AI Coaching Module Beta

The AI Coaching module is a distinct pillar from simulation — where simulation trains performance through repetition, coaching develops the person through reflection. The module is built on four coach personas, each grounded in a real coaching framework, with a voice-first session experience and a structured post-session report.

Session Arc

Every coaching session follows a 5-phase arc tracked implicitly through conversation history. The LLM system prompt instructs the coach to move through phases naturally — no explicit state machine required.

Post-Session Coaching Report

At session end, the full conversation transcript is passed to the LLM with a structured JSON schema. The report is personalised — it references specific things the coachee said, not generic feedback.

Competitive Differentiation

Agent Forge occupies a unique position — combining multi-agent AI simulation with adaptive difficulty, a 50-point automated rubric, and zero license cost. No existing commercial platform implements all of these capabilities in a single product.