DEV Community: Akash Pal

Ownership, and Making This Template Your Own (Part 5)

Akash Pal — Sun, 30 Aug 2026 18:46:01 +0000

Part 4 covered how this platform actually ships — scaffolding, CI/CD, and the two deployment shapes. This closing part is the two things every one of the last four parts has assumed: who actually owns each piece of this, and what it takes to make this whole template yours.

Who owns what

Every piece of this platform belongs to exactly one team, and that split is what makes independent deploys survive contact with a real organization, not just a single-team demo:

Piece	Owned by	Depends on
Host / Shell	Platform team	Store, Components, the manifest, the identity provider
Components MFE	Platform / design-systems team	Nothing (a leaf)
Store MFE	Platform team	The identity provider
Utilities MFE	Platform team	Nothing (a leaf)
Domain MFE (×N)	Domain team	Components, Store, Utilities only
Manifest Registry	Platform team	Nothing
Identity provider(s)	Outside the platform — whichever the deployment configures	—
Backend / BFF	Domain team, or a shared gateway (Part 2)	Each team's own data

The rule underneath the table: domain teams never import from each other, only from the shared platform layer. That keeps the dependency graph a strict two-level tree — Host → platform layer → domain leaves — instead of a mesh, which is what keeps independent deployability tractable once there's more than a handful of domain teams. It's the same rule that made every part of this series possible to write in isolation: Part 3's auth flow doesn't need to know Part 4's deploy pipeline exists, and neither needs to know how many domain teams there eventually are.

Making this template your own

Everything organization-specific in this platform — branding, which identity provider(s) it trusts, where the manifest lives — has lived in one file across this entire series, on purpose:

// platform.config.json
{
  "orgName": "acme-corp",
  "branding": { "primaryColor": "#0B5FFF", "logoUrl": "..." },
  "idp": {
    "issuers": [
      { "id": "primary", "issuer": "https://issuer.example.com", "clientId": "...", "default": true }
    ],
    "issuerResolution": "default"
  },
  "manifestUrl": "https://cdn.acme.com/platform.manifest.json"
}

Host, the three platform MFEs, and the CI/CD pipeline ship as a GitHub template repository, not a library to install. Adopting it for a new org, a different business unit, or an entirely different kind of product — internal tool, customer-facing product, partner portal, or any mix — is meant to be: fork → edit platform.config.json → point DNS and CDN at your own infrastructure → done. No fork-and-diverge of Host's or Store's own logic required, which is exactly what keeps a fork upgradable from the upstream template later instead of quietly drifting into its own incompatible thing.

That's what the versioned contracts from Part 2 — StoreContract, DomainMFEExport, the manifest schema — are actually for, beyond just keeping one deployment internally consistent: they're the seam a fork can pull upstream changes across without breaking whatever a domain team already built on top of them.

Where this series leaves you

Five parts: the decision behind Module Federation and why the two credible alternatives lost (Part 1), the topology it produces — Host, the three platform MFEs, and the domain-MFE contract they all render into (Part 2), the login flow that unifies every mounted page regardless of which identity provider issued it (Part 3), and how a new domain team actually scaffolds, builds, and ships through a real CI/CD pipeline (Part 4). This part is the frame around all four: who owns which piece, and how the whole thing is meant to be forked, not just run as-is.

The code for all five parts — real, and the actual source every snippet in this series was pulled from — is on GitHub: github.com/akash-pal/enterprise-mfe-platform.

Shipping It — Scaffolding & CI/CD (Part 4)

Akash Pal — Sun, 30 Aug 2026 18:46:00 +0000

Part 3 covered how login is unified across every mounted page. This part is how the platform actually ships: scaffolding a new domain team by leveraging the domain template, where the resulting bundles actually live, and the CI/CD pipeline that carries a team's page from a pull request to production.

Decisions locked before writing code

This platform resolves five open questions up front, specifically so they don't cause churn mid-scaffolding:

Decision	Options on the table	What was chosen
Monorepo tool	Nx vs Turborepo vs polyrepo	Turborepo — lighter config, sufficient for this repo's size
Issuer topology	Single issuer vs multi-issuer-ready from day one	Multi-issuer-ready (config array) — cheap now, expensive to retrofit (Part 3)
Issuer resolution mechanism	default / email-domain / subdomain / selector	`default` ships built; the other three are documented config swaps
Backend topology	Single shared gateway vs per-team backends	Left to whoever adopts the platform — the template doesn't take a position
Rendering	Client-rendered only vs Next.js Multi-Zones vs edge rendering	Client-rendered only, for now — matches Part 1's default choice; the Host and CI/CD are the documented swap points if that changes later

Scaffolding a new domain team

The goal from Part 2 — a new team scaffolds, builds, and deploys an authenticated page in under an hour — isn't aspirational; it's something worth actually timing, with someone unfamiliar with the repo. The mechanism for getting there is leveraging a template: apps/domain-template, a folder to copy, rather than a bespoke CLI — chosen deliberately as the cheaper thing to maintain at this stage (an npx create-org-mfe <name> CLI is a natural upgrade path later, once the copy-paste steps below are well-worn enough to automate):

# demo/README.md
1. Copy apps/domain-template to demo/<your-domain>.
2. Rename the package in package.json and update webpack.common.js's
   federation.name to match. Give it its own dev port.
3. Replace DomainApp.tsx with your own UI; keep exporting DomainMFEExport
   ({ routes, Component }) from src/index.tsx.
4. Add an entry to platform.manifest.dev.json with the new remote's
   remoteEntry URL and route — no Host rebuild required.
5. Add a dev line for it to the root package.json's dev script.

apps/domain-template stays deliberately minimal — auth and shared-state wiring only, no business content — precisely so it stays a clean copy source every new team starts from. demo/orders is the proof this actually works: domain-template copied, renamed, filled in with real (if sample) content, running on its own port with its own federation name, wired in by one manifest entry. Host's own remotes: {} from Part 1 never had to know orders existed until it was already running in a browser tab — and the exact same copy-and-rename steps are how a third, fourth, or fiftieth domain team gets a page running.

Two deployment shapes, one running Host

Host, Components, Store, and Utilities don't deploy the same way a domain team's page does — and that difference isn't incidental, it's the same one Part 1 built the whole platform around:

The left path is ordinary dependency management: Host's package.json and webpack.common.js declare which version of Components, Store, and Utilities it expects, npm installs them, and shipping a change to any of the four means rebuilding and redeploying Host itself — the four are versioned and released together. The right path is the one this whole series keeps coming back to: a domain team's bundle is uploaded to its own versioned path, and the only thing that connects it to Host is one entry in the manifest, fetched fresh at runtime. Same running application, two genuinely different deployment mechanisms feeding it — which is exactly why scaffolding a domain page (above) never touches Host's own build.

The CI/CD pipeline

Three stages, run by GitHub Actions: build and test the code into a deployable artifact, promote that artifact to dev automatically on every merge to main, then promote the same artifact to production once someone approves it. In the workflow file, that's build-test → deploy-dev → promote-prod, with promote-prod gated behind a GitHub Environment with required reviewers — no custom approval code needed, just a platform feature configured correctly:

Here's the same three stages as the actual workflow file:

# .github/workflows/mfe-ci-cd.yml
jobs:
  build-test:
    steps:
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm run build
      - run: npm run test
      - run: npm run test:scripts
      - name: Verify shared-dependency contracts
        run: npm run check:contract

  deploy-dev:
    needs: build-test
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    environment: dev
    steps:
      - run: npm run build
      - name: Upload build output to dev hosting
        run: echo "TODO -- upload apps/*/dist and demo/*/dist-remote to your dev CDN"
      - name: Point the dev manifest at the new build
        run: |
          npm run manifest:update -- \
            --route /orders --name orders \
            --version "$(node -p "require('./demo/orders/package.json').version")" \
            --remote-entry "${{ vars.DEV_CDN_BASE_URL }}/orders/remoteEntry.js"

  promote-prod:
    needs: deploy-dev
    if: github.event_name == 'workflow_dispatch' && github.event.inputs.environment == 'prod'
    environment: prod
    steps: # same shape as deploy-dev, against PROD_* vars

Key idea: the "Point the dev manifest at the new build" step is what actually deploys a domain MFE. The Host isn't rebuilt — it just reads a new remoteEntry URL out of the manifest on its next load.

Updating the manifest registry is the actual deploy step, so it has to be safe under concurrency

Say that plainly: updating platform.manifest.json is deploying a domain MFE — not part of deploying it. Upload a beautiful new remoteEntry.js to a CDN and never touch the manifest, and Host keeps loading the old one forever, with no error, because nothing told it anything changed. So the deploy script's whole job is updating one JSON array safely when more than one CI run might be doing it at the same time:

// scripts/update-manifest.js
async function upsertManifestEntry(manifestPath, fields) {
  const lockPath = await acquireLock(manifestPath);
  try {
    const manifest = await readManifest(manifestPath);
    const index = manifest.findIndex((entry) => entry.route === fields.route);
    const merged = index === -1 ? { ...fields } : { ...manifest[index], ...fields };
    validateEntry(merged);
    // ...
    await writeManifestAtomic(manifestPath, nextManifest);
    return nextEntry;
  } finally {
    await releaseLock(lockPath);
  }
}

Two properties earn their keep: locking — an exclusive-create lockfile with retry/backoff — because if two domain teams' pipelines finish around the same moment (the normal case once there's more than one team, not an edge case), a naive read-modify-write is a lost-update race waiting to happen. Atomic write — write to a temp file, then rename over the real one — because a same-directory rename is atomic on POSIX filesystems, so a crash mid-write can never leave the manifest half-written; the real file has either the old complete content or the new complete content, never something in between. A test proves the property that actually matters:

test('serializes concurrent updates to different routes — neither update is lost', async (t) => {
  const manifestPath = await withTempManifest(t, []);
  await Promise.all([
    upsertManifestEntry(manifestPath, { route: '/orders', ... }),
    upsertManifestEntry(manifestPath, { route: '/admin', ... }),
    upsertManifestEntry(manifestPath, { route: '/billing', ... }),
  ]);
  const manifest = await readManifest(manifestPath);
  assert.deepEqual(manifest.map((e) => e.route).sort(), ['/admin', '/billing', '/orders']);
});

Three "deploys" fired at the exact same instant, on purpose — exactly what happens the moment the pipeline generalizes past one domain MFE, which a GitHub Actions matrix would drive in practice.

What's real vs. what's still a placeholder, stated honestly: locking and atomicity, the shared-contract check, and the workflow's job graph and gating are real and tested. The CDN upload steps are explicit echo "TODO" placeholders — deliberately, since this pipeline is written target-agnostic (no CDN or cloud provider chosen), and canary-rollout percentages and automatic rollback on regression can't be built honestly without a real target to build against; a rollback script that's never watched real error-rate metrics isn't tested, it's decorative.

Each environment — dev/staging/prod — gets an isolated manifest and its own platform.config.json issuer configuration, so a bad manifest update, or a bad auth config change, can never cross environments. Nothing above names a specific cloud on purpose: the mechanism — build once, upload, point the manifest at it — is what this template actually commits to, and it maps onto whichever object storage, CDN, and CI runner an adopter already runs.

The last part closes the series: who actually owns each piece of this, and what it takes to make this whole template yours.

Next: Part 5 — Ownership, and Making This Template Your Own

One Login, Every Microfrontend — The Auth Architecture (Part 3)

Akash Pal — Sun, 30 Aug 2026 18:45:58 +0000

Part 2 covered the platform's topology and the three shared microfrontends every domain team builds against. This part is authentication — the piece every other part of the platform depends on, which is why it's built early rather than left until the end.

A few terms, defined once

This part leans on some standard identity terms — worth pinning down before diving in, since they build on each other:

IdP (Identity Provider) — the actual service that owns usernames, passwords, and roles, and does the real work of checking whether a login is valid. Okta, Google, Microsoft Entra ID, Auth0, or a company's own login system are all examples. Host never becomes one of these itself — it always hands the real login off to one.
OAuth 2.0 — an industry-standard way for one app (Host) to get limited, provable confirmation from an IdP that a user is logged in, without Host ever seeing or handling that user's password.
OIDC (OpenID Connect) — OAuth 2.0, plus a standard way to also learn who that user is (their id, their roles), not just "yes, they logged in." This platform speaks OIDC specifically because it needs that identity information, not just a bare confirmation.
Issuer — the specific IdP a deployment has decided to trust. In practice, just a URL Host redirects the browser to, and later asks "did this login really happen?" A deployment can trust one issuer, or several — more on why below.

With those in hand, here's what actually happens when someone logs in.

Population-agnostic by design

This platform is explicit about scope here: the Host and Store MFE don't model "employees" vs. "partners" vs. "customers" as distinct concepts. They know one thing — a standard OIDC contract. Which population authenticates, and which provider issues their tokens, is a deployment-time config decision, not an architectural one. That's what lets the identical template back an internal admin tool, a customer-facing product, or a B2B partner portal with zero Host or Store code changes between them — the choice of IdP (Okta, Microsoft Entra ID, Auth0, Keycloak, Cognito, or a homegrown one) is explicitly out of scope for the platform itself.

One rule follows from this everywhere in the codebase: a domain MFE never triggers login, logout, or a token exchange. It reads the result of auth (useAuth(), the federated singleton from Part 2) but never causes an auth event. Host owns the entire flow, alone, end to end.

The flow: Authorization Code + PKCE

Host never sees a password. It redirects the browser to the IdP, the IdP authenticates the user, and it redirects back with proof. That handoff is called the Authorization Code flow with PKCE ("pixy" — Proof Key for Code Exchange), and it's a specific sequence of redirects:

Host generates a random secret (the code verifier), hashes it into a code challenge, and sends the browser to the IdP's login page with that challenge.
The user authenticates at the IdP — whatever that means for the real IdP in use.
The IdP redirects back to Host's /callback with a short-lived authorization code.
Host exchanges that code — with the original, un-hashed verifier — for the actual tokens.

Why the extra verifier/challenge step, specifically? A traditional server-side app can hold a permanent secret of its own — proof that "I'm really the app I claim to be" — when it trades a login code for real tokens. Host can't do that safely: it's JavaScript running inside the user's own browser, and anything shipped to a browser can be read by anyone who opens dev tools. PKCE solves this without needing any permanent secret at all. Right before redirecting to the IdP, Host invents a random, one-time value (the verifier) just for this one login attempt, and sends the IdP a scrambled version of it (the challenge). When Host later comes back to redeem the authorization code for real tokens, it presents the original, un-scrambled verifier. Only whoever actually started this specific login attempt could have that value — so the IdP can trust the exchange, without either side ever storing a password-like secret.

Here's that exact handshake as a diagram — steps 1 through 4 above, continued through to what Host does once it actually has a session:

And here's step 1 as real code:

// packages/runtime-module-federation/src/oidc-client.ts
export async function redirectToAuthorize(issuerConfig: IssuerConfig): Promise<void> {
  const discovery = await discover(issuerConfig.issuer);
  const verifier = generateCodeVerifier();
  const challenge = await generateCodeChallenge(verifier);
  const state = generateState();

  sessionStorage.setItem(PKCE_VERIFIER_KEY, verifier);
  sessionStorage.setItem(STATE_KEY, state);

  const url = new URL(discovery.authorization_endpoint);
  url.searchParams.set('response_type', 'code');
  url.searchParams.set('client_id', issuerConfig.clientId);
  url.searchParams.set('redirect_uri', redirectUri());
  url.searchParams.set('scope', 'openid');
  url.searchParams.set('state', state);
  url.searchParams.set('code_challenge', challenge);
  url.searchParams.set('code_challenge_method', 'S256');

  window.location.assign(url.toString());
}

That state value is a separate, second safeguard — it guards against CSRF (a class of attack where a malicious site tries to trick a browser into completing part of this handshake without the user actually intending it). The callback rejects any response whose state doesn't match what was stored right before redirecting:

// packages/runtime-module-federation/src/oidc-client.ts
if (!returnedState || returnedState !== expectedState) {
  throw new Error('State mismatch on callback — possible CSRF, aborting token exchange');
}

One or more issuers — a config array from line one

Recall an issuer is just the specific IdP a deployment trusts. platform.config.json lists every issuer a deployment trusts, as an array. A deployment serving one population declares one issuer; a deployment serving many tenants might declare several, or point at a single identity provider that itself manages logins for many upstream organizations — Host's own code doesn't need to change either way, only the config.

This platform makes a specific, deliberate choice here: multi-issuer support is a config array from the first line of code, even with only one issuer configured — retrofitting an array shape onto a single-issuer assumption later would touch every piece of code that reads a user's claims.

// platform.config.json
{
  "orgName": "acme-demo",
  "branding": { "primaryColor": "#2F5CE0", "logoUrl": "/logo.svg" },
  "idp": {
    "issuers": [
      { "id": "local-dev", "issuer": "http://localhost:9000", "clientId": "host-dev-client", "default": true }
    ],
    "issuerResolution": "default"
  },
  "manifestUrl": "/platform.manifest.json"
}

issuerResolution — default / email-domain / subdomain / selector — decides which issuer applies when more than one is configured. Only default ships built with a UI; the other three are documented config swaps, not something built upfront on spec.

One normalized session, regardless of which IdP produced it

Here's the problem this solves: two different IdPs describing the exact same logged-in user are free to shape that description differently — some send roles as an array, some send a single role; some send org_id, some orgId. Without a fix, every single piece of downstream code — every domain team's page, every route guard — would need to know which specific IdP produced whatever token it's looking at, forever. Instead, one function collapses whatever comes back into one fixed shape, immediately after the token exchange:

// packages/runtime-module-federation/src/normalize.ts
export function normalizeTokenResponse(raw: RawTokenResponse): AuthState {
  const idToken = typeof raw.id_token === 'string' ? raw.id_token : undefined;
  const claimsSource = idToken ? decodeJwtPayload(idToken) : {};

  const roles = Array.isArray(claimsSource.roles)
    ? claimsSource.roles
    : typeof claimsSource.role === 'string'
      ? [claimsSource.role]
      : [];
  const orgId = claimsSource.org_id ?? claimsSource.orgId;

  return {
    accessToken: raw.access_token,
    idToken: idToken ?? null,
    claims: { roles, orgId: typeof orgId === 'string' ? orgId : '', userId: claimsSource.sub! },
    expiresAt: Date.now() + raw.expires_in * 1000,
  };
}

Everything downstream — every domain MFE, every route guard, StoreContract itself — reads only this normalized AuthState shape:

// packages/types/src/auth.ts
export interface AuthState {
  accessToken: string | null;
  idToken: string | null;   // kept specifically as id_token_hint for RP-Initiated Logout, below
  claims: AuthClaims | null;
  expiresAt: number | null;
}

That's the entire payoff: every team writes its authorization checks once, against one shape, and never needs to know or care which real IdP a given deployment actually uses. It's also the seam worth its own unit tests — asserting the normalized shape stays identical across at least two mock issuer response formats — since swapping one IdP for another later should be a change contained entirely to this one function.

Session persistence and cross-tab logout

The resulting AuthState is handed to the Store MFE's AuthProvider from Part 2 — every domain MFE reading useAuth() gets this exact session object. It's also deliberately persisted to sessionStorage, hydrated back on mount, so a page reload doesn't force a full round trip back to the IdP:

// apps/store-mfe/src/auth/AuthContext.tsx
function loadPersistedSession(): AuthState {
  try {
    const raw = sessionStorage.getItem(SESSION_STORAGE_KEY);
    if (!raw) return EMPTY_AUTH_STATE;
    const parsed = JSON.parse(raw) as AuthState;
    if (!parsed.expiresAt || parsed.expiresAt <= Date.now()) return EMPTY_AUTH_STATE;
    return parsed;
  } catch {
    return EMPTY_AUTH_STATE;
  }
}

sessionStorage, deliberately, not localStorage — a session shouldn't outlive the browser tab it belongs to. Cross-tab logout is handled separately, via BroadcastChannel('auth-events'): when one tab logs out, every other open tab hears a LOGOUT message, clears its own session, and — because that clear runs through the same state-setting path — the persisted sessionStorage copy gets wiped too, in every tab, automatically. That message is { type: 'LOGOUT' | 'TOKEN_REFRESHED' }, and it's treated as a must-have from day one, not a nice-to-have: a domain MFE silently holding a stale session after a Host logout is the kind of bug that's invisible until a real incident.

Logout means telling the IdP, not just forgetting locally

This is easy to get half-right: "logging out" has to mean more than clearing Host's own memory. If Host only resets its own state, the IdP's own session cookie is untouched — the very next login attempt can silently re-authenticate against that still-live IdP session without ever showing a sign-in prompt. That's single sign-on working exactly as designed; it's just not "log out" if only the local half of the relationship gets torn down.

The correct mechanism is RP-Initiated Logout — a named part of the OIDC spec — redirecting the browser to the IdP's end_session_endpoint so the IdP itself ends the session:

// packages/runtime-module-federation/src/oidc-client.ts
export async function redirectToEndSession(
  issuerConfig: IssuerConfig,
  idTokenHint: string | null,
): Promise<void> {
  const discovery = await discover(issuerConfig.issuer);
  if (!discovery.end_session_endpoint) {
    window.location.assign(postLogoutRedirectUri());
    return;
  }
  const url = new URL(discovery.end_session_endpoint);
  if (idTokenHint) url.searchParams.set('id_token_hint', idTokenHint);
  url.searchParams.set('client_id', issuerConfig.clientId);
  url.searchParams.set('post_logout_redirect_uri', postLogoutRedirectUri());
  window.location.assign(url.toString());
}

id_token_hint is the raw ID token from earlier — the IdP uses it to confirm which session it's being asked to end, which is exactly why AuthState keeps the raw token around instead of discarding it once its claims are decoded. And the IdP has to allow-list post_logout_redirect_uris, the same way it already allow-lists login redirect URIs, so it knows it's safe to send the browser back afterward. With all three pieces together, logging out genuinely ends the session at the IdP — the next "Log in" click shows a real sign-in prompt, not an instant, invisible re-authentication.

Authorization is claims-driven, never issuer-driven

Role/claim data — never which IdP authenticated the user — drives every enforcement point: route guards in Host's manifest-driven router, conditional rendering inside domain MFEs, and enforcement at the backend layer, which is a hard requirement, not a suggestion — client-side checks are never sufficient alone. This decoupling is what lets the same authorization code work whether a "role" came from a workforce group, a partner-org assignment, or a subscription tier; the platform doesn't distinguish, and doesn't need to. Feature flags layer on top of roles for progressive rollout, sourced from the Store MFE's FeatureFlagProvider.

From login to a mounted page: the whole sequence

Putting the pieces above in order, this is the complete path from "user opens the app" to "a team's page is on screen" — the diagram earlier in this part covers steps 1 through 6:

User loads the platform → Host checks for a valid in-memory token.
If absent, redirect to the IdP (Authorization Code + PKCE) → exchange code for tokens.
Host normalizes the response and initializes the Store MFE's AuthProvider with the session.
User navigates to a domain route → Host resolves it against the manifest.
Host checks the route's required role against the user's claims.
If authorized: fetch the domain's bundle from the CDN, mount it into the shared singleton scope — no re-fetch of React/Store/Components, no duplicate provider instance.
If not authorized: Host renders a 403 fallback. The CDN is never contacted — the domain's bundle is never fetched at all.

Modeling roles in the local dev IdP

Exercising role-gating locally needs at least two distinct roles without a real IdP account. The local IdP — a thin, dev-only wrapper around the oidc-provider library, never meant to be deployed — models this with two named accounts and a generic fallback:

// tools/mock-idp/src/server.js
const NAMED_ACCOUNTS = new Map(
  [DEMO_ACCOUNT, ADMIN_ACCOUNT].map((account) => [account.accountId, account]),
);

async function findAccount(_ctx, id) {
  const account = NAMED_ACCOUNTS.get(id) ?? { accountId: id, roles: ['user'], orgId: 'acme-demo' };
  return {
    accountId: account.accountId,
    async claims() {
      return { sub: account.accountId, roles: account.roles, org_id: account.orgId };
    },
  };
}

Any login typed into the local sign-in form works: admin-user-1 resolves to the admin role, demo-user-1 — or literally anything else — resolves to user. It accepts any password, too. This is exclusively a local stand-in for exercising the flow end to end, never a real identity source.

Part 4 is how this all actually ships: scaffolding a new domain team from the template, and the CI/CD pipeline that carries a page from a pull request to production.

Next: Part 4 — Shipping It: Scaffolding & CI/CD

Inside the Platform — Topology, Host Shell & Platform MFEs (Part 2)

Akash Pal — Sun, 30 Aug 2026 18:45:56 +0000

Part 1 covered why this platform uses Module Federation instead of Next.js Multi-Zones or single-spa. This part covers the platform's design goals, its topology, what the Host shell actually owns, and the three shared microfrontends every domain team builds against — and, at the end, how the Host actually wires all three together.

Design goals, stated as constraints

Four goals shape every decision in this series, not just the composition strategy from Part 1:

Each domain team deploys independently, without redeploying the Host.
One design system, one state/auth source of truth, one utilities layer — no duplication across MFEs.
A new domain team can scaffold, build, and deploy an authenticated page in under an hour.
The whole platform is config-driven enough to be forked and re-branded for a different business unit or organization without touching core code.

Goal 4 is the one easy to underrate reading this series linearly — it's the subject of the last part. Goals 1–3 are what the rest of this part is about.

High-level topology

The Host dynamically loads three shared platform microfrontends as federated singletons, which every domain microfrontend consumes. The Host resolves routes against the manifest at runtime, and a domain's bundle is fetched from the CDN only if the route is authorized:

A few things worth reading directly off that diagram. The platform MFEs sit in one shared singleton scope — one instance, not one per domain MFE. The CDN is only ever contacted after the manifest has already said a route is authorized. Components and Store each reach the Host two different ways at once — solid line, dashed line — which the next section explains; Utilities only ever takes the dashed one. And below the domain layer, a dashed "Backend / BFF" box marks a boundary on purpose: this platform has an opinion about how a page gets found and mounted, and deliberately no opinion at all about where that page gets its data from — that line is for each domain team to draw themselves.

The Host: what it owns, and what it deliberately doesn't

Responsibilities:

App shell — Header, Side Navigation, Footer, layout regions
Route registry that resolves domain MFEs dynamically from a manifest, not hardcoded at build time — this is what makes independent deploys possible
Auth bootstrap — acquires the session once, hands it to the Store MFE's AuthProvider
Global error boundary + fallback UI per mounted remote, so one MFE crashing doesn't take the shell down with it
Theme/design-token injection

What it explicitly doesn't own: any domain's business logic, any domain's routes beyond the catch-all that hands off to the manifest, and — per Part 1 — any compiled-in knowledge of which domains exist.

// apps/host/webpack.common.js
module.exports = createModuleFederationConfig({
  federation: {
    name: 'host',
    remotes: {}, // resolved at runtime — see manifest-loader.ts below
    shared: {
      react: { singleton: true, requiredVersion: '^18.2.0 || ^19.0.0' },
      'react-dom': { singleton: true, requiredVersion: '^18.2.0 || ^19.0.0' },
      '@org/store': { singleton: true, requiredVersion: `^${storePkg.version}` },
      '@org/components': { singleton: true, requiredVersion: `^${componentsPkg.version}` },
    },
  },
});

And the route resolution it hands off to:

// packages/runtime-module-federation/src/manifest-loader.ts
export function resolveRoute(manifest: ManifestEntry[], pathname: string): ManifestEntry | undefined {
  return manifest.find((entry) => pathname === entry.route || pathname.startsWith(`${entry.route}/`));
}

The three platform microfrontends

Components MFE — the design system

Exposes the shared component library — buttons, form primitives, modals, header/side-nav chrome, a Forbidden view, and so on — built on design tokens as the actual contract (colors, spacing, typography), so visual consistency survives independent deploys rather than drifting per team.

The mechanism that makes "one design system" true rather than aspirational is dual-publishing: a real tsc build producing an npm-installable package, and a separate webpack build producing a remoteEntry.js, from the same source:

// apps/components-mfe/webpack.common.cjs
module.exports = createModuleFederationConfig({
  entry: './src/dev-bootstrap.tsx',
  outputDir: 'dist-remote',
  federation: {
    name: 'components',
    filename: 'remoteEntry.js',
    exposes: { './components': './src/index.ts' },
    shared: {
      react: { singleton: true, requiredVersion: '^18.2.0 || ^19.0.0' },
      'react-dom': { singleton: true, requiredVersion: '^18.2.0 || ^19.0.0' },
      '@org/components': { singleton: true, requiredVersion: `^${pkg.version}` },
    },
  },
});

// apps/components-mfe/package.json (trimmed)
{
  "name": "@org/components",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json && node scripts/copy-css.mjs && webpack build --config webpack.prod.cjs"
  }
}

tsc gives compile-time type safety and tree-shaking for anyone importing @org/components as a normal npm dependency; the webpack build gives runtime singleton sharing for anyone consuming it as a Module Federation remote. Same source, two consumers, and — because it's federated as a singleton — every domain MFE gets the exact same rendered instance, not N slightly-drifted copies.

Store MFE — everything that has to be one shared instance

This is the platform's other non-negotiable singleton. Its public surface, StoreContract, is one interface covering everything that has to be shared across every mounted page: the login session, state shared for the current tab, state that survives a reload, feature flags, analytics, local-storage-backed state, and logging:

// packages/types/src/store.ts
export interface StoreContract {
  useAuth(): AuthState;
  useGlobalState<T>(key: string): [T, (value: T) => void];
  useGlobalStatePersist<T>(key: string): [T, (value: T) => void];
  useFeatureFlag(flagKey: string): boolean;
  useAnalytics(): AnalyticsClient;
  useLocalStorage<T>(key: string): [T, (value: T) => void];
  useLogger(): Logger;
}

Seven hooks, one underlying mechanism: each is backed by exactly one React context, created once, that every consumer across the whole platform reads and writes through. useGlobalState is a good one to look at up close, because it's small enough to show that whole mechanism in one place:

// apps/store-mfe/src/state/GlobalStateContext.tsx
const GlobalStateContext = createContext<GlobalStateContextValue | null>(null);

/**
 * One in-memory map behind one context — every useGlobalState() consumer
 * across the whole federated singleton reads/writes the same object.
 */
export function GlobalStateProvider({ children }: { children: ReactNode }) {
  const [values, setValues] = useState<StateMap>({});
  const setValue = useCallback((key: string, value: unknown) => {
    setValues((prev) => ({ ...prev, [key]: value }));
  }, []);
  const value = useMemo(() => ({ values, setValue }), [values, setValue]);
  return <GlobalStateContext.Provider value={value}>{children}</GlobalStateContext.Provider>;
}

Every other hook on StoreContract follows this same shape — its own context, its own provider, exposed as a hook. What turns seven separate providers into the one thing the Host actually mounts is StoreProvider, which composes all of them into a single tree:

// apps/store-mfe/src/StoreProvider.tsx
export function StoreProvider({ flags = [], children }: { flags?: FeatureFlag[]; children: ReactNode }) {
  return (
    <AuthProvider>
      <GlobalStateProvider>
        <GlobalStatePersistProvider>
          <FeatureFlagProvider flags={flags}>
            <AnalyticsProvider>{children}</AnalyticsProvider>
          </FeatureFlagProvider>
        </GlobalStatePersistProvider>
      </GlobalStateProvider>
    </AuthProvider>
  );
}

Without singleton: true on @org/store in every consumer's webpack config, none of this holds — each MFE would mount its own copy of StoreProvider, and two pages' useGlobalState('cart') calls would quietly diverge instead of sharing state.

One more thing lives inside that same tree: a shared cache for data fetched from a backend. StoreProvider also mounts exactly one QueryClientProvider, from TanStack Query — same idea as everything else on this page: one instance, not one per domain MFE, so if two different pages both fetch the same resource, the second call reads the first one's cache instead of firing a duplicate request.

// apps/store-mfe/src/StoreProvider.tsx
const queryClient = new QueryClient();

export function StoreProvider({ flags = [], children }: { flags?: FeatureFlag[]; children: ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <AuthProvider>
        <GlobalStateProvider>
          {/* ...the rest, unchanged... */}
        </GlobalStateProvider>
      </AuthProvider>
    </QueryClientProvider>
  );
}

@org/store re-exports useQuery, useMutation, and useQueryClient directly — a domain team never installs the library itself:

// apps/store-mfe/src/index.ts
export { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

This is exactly the kind of thing that's easy to get subtly wrong the same way singleton context always is: TanStack Query keeps its cache behind its own React context, so @tanstack/react-query has to be declared singleton: true in every consuming app's webpack config too — the same failure mode as @org/store itself, one layer further down. Here it is actually used, in the orders domain MFE:

// demo/orders/src/DomainApp.tsx
import { useAuth, useQuery } from '@org/store';

async function fetchOrders(): Promise<Order[]> {
  const res = await fetch('http://localhost:3005/orders');
  if (!res.ok) throw new Error(`Failed to load orders: ${res.status}`);
  return res.json();
}

export function DomainApp({ basePath }: { basePath: string }) {
  const auth = useAuth();
  const { data: orders, isLoading, error } = useQuery({ queryKey: ['orders'], queryFn: fetchOrders });
  // ...renders a loading state, an error state, or the list
}

http://localhost:3005 is tools/mock-bff — a small dev-only backend, real and running, that this one domain team owns and calls directly. Nothing about that URL is known to Host, Store, or any other domain MFE; it's orders' own business, the same way its UI is.

Utilities MFE — deliberately not federated

Formatters, validators, generators, convertors — pure, side-effect-free functions:

// apps/utilities-mfe/src/index.ts
// Pure, side-effect-free, tree-shakeable — npm package only. Federating this
// one is optional; skipped for v1 until a real duplication problem shows up.
export * from './formatters/index.js';
export * from './validators/index.js';
export * from './generators/index.js';
export * from './convertors/index.js';

Pure functions don't hold state, so there's no correctness reason to dedupe them at runtime — just ship it as a plain npm dependency and skip the Module Federation machinery entirely. This is worth calling out precisely because it cuts against the instinct to federate everything on principle: federate what has to be one instance, and nothing else.

Wiring it together: how the Host actually uses all three

Components, Store, and Utilities read as three separate pieces above — here's what tying them into the Host actually looks like. The Host's entry point wraps its entire app in exactly one StoreProvider, mounted once, nowhere else:

// apps/host/src/bootstrap.tsx
import { createRoot } from 'react-dom/client';
import { StoreProvider } from '@org/store';
import { loadPlatformConfig } from '@org/runtime-module-federation';
import { App } from './App';

async function main(): Promise<void> {
  const container = document.getElementById('root')!;
  const root = createRoot(container);
  const platformConfig = await loadPlatformConfig();
  root.render(
    <StoreProvider>
      <App platformConfig={platformConfig} />
    </StoreProvider>,
  );
}

void main();

That single <StoreProvider> is what makes useAuth() — or any other StoreContract hook — return the same value no matter which mounted page calls it. Inside App.tsx, the Host then pulls from all three platform MFEs directly:

// apps/host/src/App.tsx
import { useAuth } from '@org/store';
import { formatDate } from '@org/utilities';
import { Header, SideNav, Footer, HeaderActions } from '@org/components';

export function App({ platformConfig }: { platformConfig: PlatformConfig }) {
  const auth = useAuth();
  // ...
  return (
    <BrowserRouter>
      <Header title={platformConfig.orgName} actions={<HeaderActions isAuthenticated={auth.claims !== null} /* ... */ />} />
      <Routes>{/* domain routes resolved from the manifest */}</Routes>
      <Footer text={`${platformConfig.orgName} — Enterprise MFE Platform`} />
    </BrowserRouter>
  );
}

useAuth() reads the session StoreProvider set up above it. Header, SideNav, and Footer are the Components MFE's design system, rendering the shell chrome from the design goals at the top of this part. formatDate, elsewhere in the same file, is a plain function import from Utilities — no provider, no context, just a function call, exactly because Utilities isn't a singleton the way Store and Components are. One file, all three platform MFEs, doing exactly what each was described as doing above.

The next part covers exactly how that session got there in the first place — from a redirect to an identity provider through to the normalized claims useAuth() returns here.

Domain MFEs — the ×N layer

One per business capability, owned by an independent team. A domain MFE registers itself by adding one entry to the manifest — name, remote URL, route, required role — with no PR against the Host repo required, and it consumes Components/Store/Utilities as shared dependencies, never bundling its own copy of React, the design system, or the state layer.

What a domain MFE actually hands back to Host is fixed by one small contract:

// packages/types/src/domain.ts
export interface DomainMFEExport {
  routes: RouteDefinition[];
  Component: ComponentType<DomainMFEProps>;
}

This is a component reference, not an imperative mount(container)/unmount() pair — and the reason is a property of React itself, not of Module Federation: React context never crosses a root boundary. A domain MFE that called its own createRoot(container).render(...) would start a second, fully independent React tree — and no amount of correctly-shared modules changes the fact that a component in tree B can't see a Provider that only exists in tree A. Module Federation guarantees the module is shared; it says nothing about the tree. So Host renders each domain MFE's component directly inside its own tree instead:

// packages/runtime-module-federation/src/route-guard.tsx
const RemoteComponent = domainExport.Component;
return <RemoteComponent basePath={entry.route} />;

That single element inherits every context provider above it — the StoreProvider from earlier in this part included — because there's only ever one tree. It's also why every domain MFE ships two entry points, not one file with a runtime branch: a standalone-preview entry that calls createRoot() and wraps itself in its own StoreProvider (no Host around to supply one), and a federated entry that exports the bare { routes, Component } object and renders nothing — Host supplies the provider when it mounts it. The same component code runs unmodified in both.

For its own data, a domain MFE calls its own backend directly — orders calling tools/mock-bff above is the pattern, not a special case. Whether that means one shared gateway behind every domain or a separate backend per team is deliberately not this platform's call to make: the topology diagram draws that box dashed, on purpose, and every domain team is free to answer the question differently.

Dependency management: two layers, not one

"Shared dependencies" means two different things here, and the platform handles them differently:

Build-time, via a private package registry (GitHub Packages, Verdaccio, Artifactory) hosting versioned internal packages — @org/components, @org/store, @org/utilities, plus @org/types (shared TypeScript contracts, so a breaking change to StoreContract or ManifestEntry fails at compile time, not in production) and shared tooling config (@org/eslint-config, @org/tsconfig-base).

Run-time, via Module Federation's shared scope — the mechanism from Part 1 that dedupes React, React-DOM, and the platform MFEs across every remote loaded into the Host, so the browser downloads one copy of each regardless of how many domain MFEs are mounted simultaneously.

Locally, a monorepo (this platform uses Turborepo, covered later in this series) lets you run the Host, the platform MFEs, and whichever domain MFE you're actively building together, with incremental builds and remote caching. Module Federation itself doesn't require a monorepo — polyrepo works fine — a monorepo just makes local cross-MFE development meaningfully less painful.

Next: Part 3 — One Login, Every Microfrontend: The Auth Architecture

Why Module Federation — Building an Enterprise MFE Platform (Part 1)

Akash Pal — Sun, 30 Aug 2026 18:45:55 +0000

This series walks through an actual enterprise microfrontend platform, end to end: one Host shell, three shared platform microfrontends, a manifest-driven mechanism for mounting any number of independently-owned domain microfrontends, a full OIDC auth flow, and a CI/CD pipeline. Every code snippet in this series is real and traceable to the actual boilerplate it's built from, on GitHub.

Part 1 is the decision everything else in this series depends on: why Module Federation, and not one of the two other credible options.

The one requirement that rules everything else out

Strip away the buzzwords, and an "enterprise microfrontend platform" only has to guarantee one thing: a team ships a change to their part of the app without anyone else redeploying anything. Not "in theory, with enough coordination" — actually, mechanically, true. If shipping one team's bug fix requires a platform team to cut a release, this isn't microfrontends — it's a monolith with extra steps.

That single requirement rules out more than it looks like it should. It rules out compiling every team's code into one shared build (that's just a single-page app with more steps). And it rules out anything where the Host app needs to know, at its own build time, which teams' pages exist and which version of each — because "known when the Host was built" and "deployed independently of the Host" are opposites.

The decision

Use Webpack 5 Module Federation, in runtime-composition mode, as the platform's way of putting every team's page together into one app:

The Host ships with an empty list of remote apps built in. Instead, it looks up every team's page from a small list — a manifest — that it fetches fresh every time the app loads.
React, the shared state layer, and the shared design system are all declared as singletons: every team's page gets the exact same running instance of each, not its own separate copy.
"Deploying" a team's page means adding or updating one entry in that manifest. The Host itself is never rebuilt.

Here's that decision as it actually exists in the repo, not as illustrative pseudocode:

// apps/host/webpack.common.js
module.exports = createModuleFederationConfig({
  federation: {
    name: 'host',
    // remotes stay empty at build time — resolved at runtime from the
    // manifest. This is what makes a domain MFE's deploy a manifest
    // update instead of a Host rebuild.
    remotes: {},
    shared: {
      react: { singleton: true, requiredVersion: '^18.2.0 || ^19.0.0' },
      'react-dom': { singleton: true, requiredVersion: '^18.2.0 || ^19.0.0' },
      '@org/store': { singleton: true, requiredVersion: `^${storePkg.version}` },
      '@org/components': { singleton: true, requiredVersion: `^${componentsPkg.version}` },
    },
  },
  ...
});

The Host doesn't import a single line of any team's code. At runtime, it fetches a small JSON file — platform.manifest.json — that maps each page's route to the URL its bundle lives at, and mounts whatever's listed there:

// packages/runtime-module-federation/src/manifest-loader.ts
export async function loadDomainManifest(config: PlatformConfig): Promise<ManifestEntry[]> {
  if (cached) return cached;
  const res = await fetch(config.manifestUrl);
  if (!res.ok) throw new Error(`Failed to load manifest from ${config.manifestUrl}: ${res.status}`);
  cached = (await res.json()) as ManifestEntry[];
  return cached;
}

This is the single most important decision in the whole platform: deploying a team's page means updating one entry in this manifest, not rebuilding the Host. Part 5 covers the script that does that update safely.

The other options on the table

Two other approaches genuinely fit this same problem, and it's worth being clear about why each lost out here rather than just naming Module Federation as a given:

Approach	How it works	Why it's not the default here
Build-time composition	The Host imports every team's code directly and bundles it all into one build, like a normal app with more folders.	A team's deploy would require rebuilding and redeploying the Host — exactly the coupling this platform exists to avoid. Ruled out outright, not just deprioritized.
Next.js Multi-Zones	Each team ships an independently deployable Next.js app; a router at the edge stitches them together by URL prefix.	The right call if real SSR/SEO is a hard requirement. But each zone is its own separate page, not a widget sharing one React tree with the others — so login state, shared components, and shared data don't automatically carry across zones the way they do here.
single-spa	A framework-agnostic runtime composition tool — any framework's app can mount alongside any other.	Makes real sense if an org runs Vue, Angular, and React side by side. This platform assumes every team is on React, so that extra flexibility is a cost being paid for a problem the platform doesn't have.
Module Federation (chosen)	Webpack loads each team's bundle at runtime and shares one running copy of React, the shared state layer, and the design system across all of them.	Meets the independent-deploy requirement with the least new infrastructure, and keeps every team's page working inside one shared, logged-in app.

If real SSR/SEO ever becomes a hard requirement later, switching to Multi-Zones or single-spa is a contained swap — it changes how the Host and the deploy pipeline work, not the rest of the platform.

What this buys, and what it costs

What it buys:

A team ships by adding one entry to the manifest — no pull request against the Host, no waiting on a platform team's release train.
Every team's page uses the same running copy of React, the same design system, and the same logged-in session — not a slightly different copy per team.
Nothing about this approach locks the platform into one cloud provider, CI tool, or hosting vendor.

What it costs — two real trade-offs, both handled later in this series:

The manifest becomes critical. Every team's page is found the same way: by looking it up in that one shared list. If wherever that list lives goes down, no page loads — even pages that changed nothing today.
A version mismatch can slip through unnoticed. Each team declares which version of React (and the shared libraries) their page was built against. Nothing stops that declaration from quietly drifting out of sync with what's actually running — the mismatch only shows up once a real user hits it in a real browser, not when the code is built.

Both of those get a concrete, working mitigation later in this series — not just a warning label.

Running several teams' pages together locally is also a bit more involved than running one single app — this platform uses a monorepo tool (Turborepo) to keep that workable, though it isn't strictly required for Module Federation to work.

That's the shape of this series: the decision in this part, and then each following part is the architecture that decision leads to — the topology it produces, how login is unified across every team's page, the rules that keep it reliable, and how the whole thing actually ships. Next up: the platform's layout, the Host shell, and the three shared microfrontends every team builds against.

Next: Part 2 — Inside the Platform: Topology, Host Shell & Platform MFEs

Part 7: Iterating to Green: Real Bugs, and When You'd Actually Reach for a Framework

Akash Pal — Tue, 11 Aug 2026 18:44:00 +0000

Part 7 (final) of a series building a support-ticket agent with no framework. Previous: Part 6 (observability). Repo: github.com/akash-pal/agent-from-scratch

The other six parts described the finished design. This one is about what "finished" actually took — the real bugs the eval set caught, and the two questions every agent build eventually has to answer honestly: do you need more than one agent, and do you need a framework. Full detail on everything below: docs/iteration-log.md.

The iteration log, condensed

1. Exact trajectory matching was the wrong check. First eval run: 12/21 passed. Most failures were the agent correctly sending a confirmation email where the eval only expected a lookup — correct behavior, wrong assertion. Fix: switched the harness from exact-array equality to ordered-subsequence matching (every expected tool must appear, in order; extra steps in between are fine). Still catches a missing, reordered, or wrong tool. Stops false-failing on benign non-determinism.

2. No retry/backoff meant a transient error crashed the whole run. A 503 — model overloaded on case 1 took down the entire eval harness. Fixed with exponential backoff on 429/503 specifically, plus inter-case pacing to stay under free-tier rate limits.

3. A -latest model alias silently rolled onto a stricter quota. gemini-flash-latest worked, then started failing with a 20 requests/day cap after quietly resolving to a newer model. Fixed by pinning an explicit model version instead of an alias, after checking the provider's live usage dashboard for actual quota — 25x more headroom on the pinned model. The takeaway generalizes past this one provider: "latest" aliases optimize for capability, not quota stability, and what they resolve to changes over time without your code changing at all.

4. A testing artifact that looked like a real bug. Piping multiple answers into the interactive CLI via printf "a\nb\n" | npm run agent intermittently hung after the first prompt. Root cause: a Node.js readline/promises quirk with quickly-closing piped stdin — confirmed as a testing artifact, not a real bug, by replaying the same input through an actual pseudo-terminal, where it worked every time. Fixed anyway by reusing a single shared readline.Interface instead of opening/closing one per prompt — more correct regardless of the original symptom.

5. The model claimed a refund was proposed without ever proposing one. The big one — covered in full in Part 5. Two eval cases showed outcome: refund_proposed with a trajectory that never called issue_refund. Fixed at two layers: an explicit prompt line, and — the layer that actually matters — a code-level check (enforceOutcomeIntegrity) that verifies a real confirmation_id exists in state before trusting the model's own claim.

The honest note attached to that fifth finding in the actual log: it was verified with a single targeted re-run, not a full eval pass, specifically to conserve free-tier API quota. That gap is left visible in the repo on purpose — claiming a full pass without having run it would be the same category of mistake as finding #5 itself.

Single agent, not multi-agent — and why that's arithmetic, not instinct

Multi-agent (a coordinator dispatching to specialist workers) is a cost decision, not an architectural preference. A coordinator + worker split costs roughly 3–8x a single agent's tokens and latency per run — workers see fewer tools each, which sharpens tool selection, but you're paying for that in every single run, not just the hard ones.

Three signals should all be true before paying that multiplier: the task genuinely splits into specialized roles that each benefit from a sharper, narrower prompt; subtasks can run in parallel for a real speed win, not just cleaner code; and volume × accuracy improvement actually outweighs the cost multiplier — checked with real numbers, not intuition.

At low volume, the math tends to favor a single agent even with a real accuracy edge from splitting — the multiplier isn't earned back. At high volume, the same accuracy edge can save real money, because escalation-cost reduction scales with volume in a way the fixed multiplier doesn't. This repo's own agent stays single, deliberately: five tools is well under the point where an agent starts confusing tool names, and nothing about the ticket volume this reference build targets justifies paying a multiplier for a split that would mostly just look tidier.

Framework selection — now that you've seen the raw version

Having built the loop by hand, the actual question a framework answers becomes concrete instead of abstract: does this problem need multi-agent orchestration, streaming UI wiring, an integrated tracing ecosystem, or shared abstraction across a team? If none of those apply, the ~100-line loop this series built is the production version, not a placeholder for one.

Framework	Best for	Trade-off
Raw SDK (this series)	Learning the loop, simple single-agent tools	Minimal abstraction, provider-locked, most control
LangGraph	Complex state, multi-agent, widest enterprise adoption	More setup cost; strongest observability ecosystem
Mastra	TypeScript-native teams	Smaller ecosystem, natural fit for a JS/Next.js background
Vercel AI SDK	Streaming UI tightly coupled to a Next.js frontend	Less suited to long-running, durable multi-step workflows
CrewAI	Standing up role-based multi-agent crews quickly	Opinionated structure
Google ADK	Teams committed to GCP/Gemini	Less model-agnostic than LangGraph
LlamaIndex	RAG-heavy use cases, large document corpora	Less general-purpose outside retrieval

Where this leaves the repo

Everything in this series is a real, committed artifact — not a cleaned-up retelling. The README has the full architecture diagrams, quickstart, and real example runs (screenshots included, not staged). AGENTS.md documents the hard constraints for anyone — human or AI coding agent — extending this repo later: no framework, mock data only, gated tools stay gated, guardrails live in code.

It's explicitly a reference build, not production software — mock data, a single free-tier model, no persistence, no auth. If you take one thing from the whole series, take the build order, not the code: pin the use case, write tool contracts as specs, build the eval set before the agent exists, write the smallest loop that could work, iterate against real failures, gate the consequential actions. The framework question comes last, not first — and by the time you're actually equipped to answer it, you often don't need to.

Repo: github.com/akash-pal/agent-from-scratch

Series index: Part 1 (what makes something an agent) · Part 2 (use case & tool contracts) · Part 3 (the eval set) · Part 4 (the raw loop) · Part 5 (guardrails) · Part 6 (observability) · Part 7 (this post).

Part 6: Observability for AI Agents: Tracing, Metrics, and Drift

Akash Pal — Tue, 11 Aug 2026 18:43:58 +0000

Part 6 of a series building a support-ticket agent with no framework. Previous: Part 5 (guardrails). Repo: github.com/akash-pal/agent-from-scratch

"Run the eval set" and "is this agent healthy right now" are different questions, and it's easy to only build infrastructure for the first one. Eval sets run offline, on cases you already thought of. Production traffic doesn't ask permission to send you a ticket type you didn't anticipate. Observability is what tells you when that's happening — and it's also, unglamorously, what makes offline evaluation possible in the first place: you can't debug a failing eval case without knowing what the agent actually did, step by step.

The minimum trace payload

Every tool call in this build logs a structured record — src/trace.ts:

export interface TraceStep {
  trace_id: string;
  step_id: number;
  tool_name: string;
  args_hash: string;        // hashed, never raw args
  duration_ms: number;
  result_summary: string;
  model: string;
  token_usage: { input: number; output: number };
}

Two details here that look small and aren't:

args_hash, not raw args. This trace log is meant to be safe to keep around, ship to a monitoring system, or paste into a bug report — none of which should require thinking about what secrets might be embedded in a tool call's arguments. Hashing means you can still confirm two calls used identical arguments (for debugging idempotency, for instance) without ever persisting the actual values:

export function hashArgs(args: Record<string, unknown>): string {
  return "sha256:" + createHash("sha256").update(JSON.stringify(args)).digest("hex").slice(0, 8);
}

result_summary, truncated. Full tool results can be large (a kb_search returning full article bodies, for instance) — logging the whole thing on every step makes trace output unreadable and bloats whatever's storing it. summarizeResult takes the first few fields and truncates long values:

const MAX_FIELD_LEN = 70;
export function summarizeResult(result: Record<string, unknown>): string {
  const entries = Object.entries(result).slice(0, 4);
  return entries.map(([k, v]) => `${k}=${truncate(JSON.stringify(v))}`).join("  ");
}

Readable in a terminal, structured everywhere else

The trace log doubles as CLI output — this build's whole point is being inspectable, so watching an agent run in real time matters. Early on, that meant a raw JSON blob per line, which is technically complete and practically unreadable. The fix was a small formatting pass, not a new logging system:

export function logTrace(step: TraceStep): void {
  const timing = `${step.duration_ms}ms, ${step.token_usage.input}→${step.token_usage.output} tok`;
  console.log(`  ${DIM}[${step.step_id}]${RESET} ${CYAN}${step.tool_name}${RESET} ${DIM}(${timing})${RESET}`);
  console.log(`      ${step.result_summary}`);
}

Output in an actual terminal:

  [1] order_lookup (0ms, 1077→23 tok)
      order_id="ord_1005"  status="processing"  items=[...]  total_usd=45
  [2] kb_search (1ms, 1268→20 tok)
      articles=[...]  relevance_scores=[0.48,0.24,0.24]

Colors auto-disable when stdout isn't a real TTY (process.stdout.isTTY), so piping this to a file or a CI log doesn't leave you with literal escape-code garbage — small thing, but the kind of small thing that makes the difference between a trace log people actually read and one they ignore.

Three production monitoring layers

Trace-per-step is the foundation, but three distinct layers sit on top of it, each answering a different question:

Trace logging — every run, every tool call: input, response, latency, cost. This is what you already have from the payload above.
Online metrics — aggregate numbers over time: success rate, escalation rate, average tool calls per run, average token cost per run. This is where you'd notice, for instance, that escalation rate crept from 8% to 15% over a week.
Drift detection — compare those metrics week over week. This one's easy to skip and shouldn't be: model provider updates cause silent regressions with zero code changes on your side. The agent that scored 95% on your eval set last month can start failing differently this month because the underlying model changed, not because anything you wrote did.

This repo doesn't implement online metrics or drift detection — it's a CLI reference build with no persistent request volume to aggregate — but the trace payload is written specifically so those layers could be built on top of it without changing the tracing code itself. That's the actual design goal: the minimum payload isn't "the metrics you need now," it's "the raw material any metrics system would need later."

Why this matters for debugging, not just monitoring

Go back to Part 3's eval failure:

[FAIL] hard_04 (hard)
    - trajectory: expected [order_lookup, refund_eligibility, issue_refund] as a subsequence, got [order_lookup, refund_eligibility]

That failure message exists because of tracing, full stop. Without a structured, step-by-step record of what tools got called, "the eval failed" would be all you'd know — not why. The actual bug behind that failure (Part 5's phantom refund proposal) was findable specifically because the trajectory was visible, not just the final pass/fail.

What's next

Part 7: Iterating to Green: Real Bugs, and When You'd Actually Reach for a Framework → closes the series: the full iteration log — every real bug found running this agent against the eval set, what fixed each one, and when you'd actually reach for a framework instead of this raw loop.

Repo: github.com/akash-pal/agent-from-scratch

Part 5: Guardrails That Live in Code, Not the Prompt

Akash Pal — Tue, 11 Aug 2026 18:43:53 +0000

Part 5 of a series building a support-ticket agent with no framework. Previous: Part 4 (the loop). Repo: github.com/akash-pal/agent-from-scratch

Here's the finding this whole article is built around: partway through eval iteration, the agent started reporting that a refund had been proposed — a clean, plausible-sounding message — without ever having called the tool that proposes refunds. No approval was ever requested. No confirmation existed. The model just said it happened.

That's the failure mode this part is about, and the fix is the actual argument for why guardrails belong in code, not in prompt text alone.

Policy as code

src/policy.ts is a plain data object — an allowlist, an approval list, rate limits, and regex patterns — checked by the agent loop, not asked of the model:

export const policy: Policy = {
  allowTools: ["order_lookup", "refund_eligibility", "issue_refund", "kb_search", "send_email"],
  requireApprovalFor: ["issue_refund", "send_email"],
  rateLimits: { maxToolCallsPerRun: 8, maxCostPerRunUsd: 0.3 },
  autoEscalatePatterns: {
    legal_threat: /\b(lawyer|attorney|sue|legal action|better business bureau|\bbbb\b)\b/i,
    fraud_flag: /\b(fraud|unauthorized|without my permission|didn't authorize|stolen card)\b/i,
    duplicate_ticket: /\b(already submitted|second ticket|duplicate ticket|already reported)\b/i,
  },
};

Every one of these is enforced outside the LLM's control. The model can't talk its way past requireApprovalFor — the loop checks it before executing the tool, full stop. The autoEscalatePatterns regexes run against the raw ticket text before the model is even called (this is that expected_trajectory: [] behavior from Part 3's edge-case bucket) — a legal threat or fraud flag never reaches the LLM at all, straight to a human queue.

Three human-review patterns

Not every consequential action needs the same review pattern. This build uses pre-action approval — human approves before execution — for issue_refund and send_email, because both are rare, high-stakes, and hard to reverse. Two other patterns exist for different risk profiles and are worth knowing even though this particular agent doesn't need them: sampling review (agent acts autonomously, a random 10–20% gets human QA — appropriate for high-frequency, low-individual-risk actions) and confidence routing (only route to a human when the model's self-reported confidence is genuinely calibrated — risky if that confidence isn't actually reliable, which it usually isn't by default).

The gate itself, from src/approval.ts:

export const cliApproval: ApprovalFn = async (tool, args) => {
  const answer = await getRl().question(
    `\n[APPROVAL REQUIRED] ${tool}(${JSON.stringify(args)})\nApprove? (y/n) `,
  );
  return answer.trim().toLowerCase().startsWith("y");
};

And how the loop applies it before any gated tool runs (from agent.ts):

} else if (requiresApproval(toolName) && !(await approvalFn(toolName, args))) {
  resultPayload = { error: "rejected_by_human_approval" };
  isError = true;
}

If a human says no, the tool never executes — the model gets an error result back and has to handle that, same as any other tool failure.

The bug: a claim without a fact behind it

Here's what actually happened. Two eval cases (hard_04, hard_06) came back reporting outcome: refund_proposed, but their tool-call trajectory was only [order_lookup, refund_eligibility] — issue_refund was never in the list. The model had generated a final message starting with REFUND_PROPOSED: directly, skipping the tool call that's supposed to cause that outcome.

Why this matters: the outcome parser trusted the model's own REFUND_PROPOSED: prefix as ground truth. Nothing checked that the claim corresponded to an actual, approved, executed tool call. A "propose a refund" statement is exactly the kind of business-critical, consequential claim that shouldn't rest entirely on the model choosing to comply with a prompt instruction — and here, it was.

The fix — two layers, not one

Layer one, prompt: add an explicit line the model can't miss (already shown in Part 4's system prompt) — "never state REFUND_PROPOSED unless you actually called issue_refund and it succeeded in this run."

Layer two, code — the one that actually matters:

// Guardrail enforced in code, not just the prompt: a model can claim
// REFUND_PROPOSED in text without ever having called issue_refund.
function enforceOutcomeIntegrity(
  outcome: { outcome: AgentOutcome; finalText: string },
  state: AgentState,
): { outcome: AgentOutcome; finalText: string } {
  if (outcome.outcome === "refund_proposed" && !state.artifacts.refund_confirmation_id) {
    return {
      outcome: "escalated",
      finalText: `ESCALATED: model claimed REFUND_PROPOSED without ever calling issue_refund (policy violation) — original: "${outcome.finalText}"`,
    };
  }
  return outcome;
}

state.artifacts.refund_confirmation_id is only ever set in one place — when issue_refund actually succeeds (src/memory.ts):

export function recordStep(state: AgentState, step: TrajectoryStep, result: Record<string, unknown>) {
  state.conversation.trajectory.push(step);
  if (step.tool_name === "issue_refund" && typeof result.confirmation_id === "string") {
    state.artifacts.refund_confirmation_id = result.confirmation_id;
  }
  return state;
}

So enforceOutcomeIntegrity isn't trusting the model's words at all — it's checking a fact that can only exist if the gated, approved tool call actually happened. If the model claims REFUND_PROPOSED without that fact present, the run gets downgraded to escalated, regardless of how convincing the model's text sounded.

This is the actual lesson, stated plainly: any claim your agent makes about a consequential action should be verifiable from state the code controls, not trusted from text the model generated. The prompt fix alone would probably have reduced the frequency of this bug. It wouldn't have made it impossible. The code guardrail does.

What's next

Part 6: Observability for AI Agents: Tracing, Metrics, and Drift → covers observability — the trace payload this build logs on every single step, and why "run the eval set" isn't the same question as "is this healthy in production."

Repo: github.com/akash-pal/agent-from-scratch

Part 4: The Raw ReAct Loop: ~100 Lines, No Framework

Akash Pal — Tue, 11 Aug 2026 18:43:50 +0000

Part 4 of a series building a support-ticket agent with no framework. Previous: Part 3 (the eval set). Repo: github.com/akash-pal/agent-from-scratch

This is the part everyone reaches for a framework to skip. Here's the argument for not doing that, at least the first time: if you can't explain what your agent loop does in plain English, no framework is going to fix that — it's just going to make the loop harder to see.

Here's src/agent.ts, trimmed to the actual loop:

export async function runAgent(
  ticket: Ticket,
  customer: Customer | null,
  approvalFn: ApprovalFn,
  maxSteps = 8,
): Promise<AgentResult> {
  const state = initState(ticket, customer);

  // Guardrail check happens BEFORE any model call — see Part 5.
  const escalatePattern = matchAutoEscalate(`${ticket.subject} ${ticket.body}`);
  if (escalatePattern) {
    return { outcome: "escalated", finalText: `ESCALATED: auto-escalated — "${escalatePattern}"`, state };
  }

  const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
  const contents: Content[] = [{ role: "user", parts: [{ text: ticketToUserMessage(ticket) }] }];

  for (let step = 0; step < maxSteps; step++) {
    const response = await withRetry(() =>
      ai.models.generateContent({
        model: MODEL,
        contents,
        config: { systemInstruction: buildSystemPrompt(COMPANY), tools: [{ functionDeclarations }] },
      }),
    );

    const calls = response.functionCalls ?? [];
    if (calls.length === 0) {
      // No tool call — the model produced a final answer. Done.
      const text = (response.text ?? "").trim();
      return { ...enforceOutcomeIntegrity(parseOutcome(text), state), state };
    }

    // Otherwise: execute the requested tool(s), feed results back, loop again.
    contents.push({ role: "model", parts: response.candidates?.[0]?.content?.parts ?? [] });
    const responseParts = [];
    for (const call of calls) {
      const result = await executeToolWithGuardrails(call, state, approvalFn); // Part 5
      responseParts.push({ functionResponse: { name: call.name, response: result } });
    }
    contents.push({ role: "user", parts: responseParts });
  }

  return { outcome: "escalated", finalText: `ESCALATED: max_steps_exceeded (${maxSteps} steps)`, state };
}

(The real file inlines tool execution, approval gating, and trace logging directly in the loop rather than a separate function — shown split out here for readability. Full file on GitHub.)

That's the whole thing: call the model, check if it wants a tool, if yes run it and loop, if no return the final answer. No state machine, no graph, no separate orchestrator abstraction — a for loop and an if.

The six-element system prompt

The system prompt is the other half of the loop, and it's treated as a spec with required parts, not free-form prose. From src/systemPrompt.ts:

You are the support agent for {company}. You are not a human agent — say so if asked.

GOAL: resolve or correctly escalate every ticket in as few steps as possible.

TOOLS: order_lookup (read order state) · refund_eligibility (check BEFORE
proposing a refund) · issue_refund (gated) · kb_search (use before any factual
answer) · send_email (gated, delivers the resolution).

POLICY: never call issue_refund without a prior refund_eligibility=true result.
Never fabricate an answer kb_search did not return. Never state REFUND_PROPOSED
unless issue_refund actually succeeded in this run.

UNCERTAINTY: if you are not confident, say so explicitly and escalate — do not guess.

DONE: emit a final response only once resolved, a refund is proposed, or the
ticket is escalated. Always start with RESOLVED:, REFUND_PROPOSED:, or
ESCALATED: so the outcome can be parsed.

Six required elements: identity (who it is / who it serves), one-sentence goal, tool list + when to use each, explicit policy (what it can't do), how to signal uncertainty, how to signal done. Skip any one of these and you'll find it in your eval failures — a prompt missing an explicit "how to signal done" section is, empirically, the single biggest source of unparseable final responses.

Notice that POLICY line about REFUND_PROPOSED — "never state REFUND_PROPOSED unless issue_refund actually succeeded." That sentence exists because, without it, the model did exactly that: described a refund as proposed without ever calling the tool. The full story — and why the fix required more than just this prompt line — is Part 5.

Memory: one state object, not four systems

"Memory" sounds like it should mean a vector database. Here it's a single object, updated by a reducer — src/memory.ts:

export interface AgentState {
  goal: string;
  working: { ticket: Ticket };                          // this run only
  conversation: { trajectory: TrajectoryStep[] };         // rolling
  artifacts: Record<string, unknown>;                      // exact, structured
  long_term: Pick<Customer, "preferred_channel" | ...> | null; // stable, mock in this repo
  policy: typeof policy;
}

Four layers, ordered by increasing persistence and complexity: working (this run only — the current ticket, ephemeral), conversation (the trajectory so far), artifacts (exact structured facts that need precise recall later, like a refund confirmation ID — never fuzzy semantic search for something like this), long-term (stable facts across sessions — read-only mock data here, since this repo has no real persistence layer).

The decision rule worth internalizing: reach for the cheapest layer first. In-context conversation memory is sufficient for most single-session agents. An external structured store is for facts that must survive across runs. Vector/semantic memory is the most expensive, highest-maintenance option, and should be justified, not defaulted to — critically, never for anything with financial or access-control consequences, where "approximately right" retrieval is the wrong guarantee. A refund confirmation ID goes in artifacts as an exact string, not embedded and semantically searched for later.

What's next

Part 5: Guardrails That Live in Code, Not the Prompt → covers the guardrail layer this loop leans on for every tool call: the policy-as-code approval gate, and the real bug it was added specifically to catch.

Repo: github.com/akash-pal/agent-from-scratch

Part 3: Build the Eval Set Before the Agent Exists

Akash Pal — Tue, 11 Aug 2026 18:43:48 +0000

Part 3 of a series building a support-ticket agent with no framework. Previous: Part 2 (tool contracts). Repo: github.com/akash-pal/agent-from-scratch

Here's the ordering that trips people up: build the eval set before the agent loop exists. Not after, not alongside — before. It feels backwards. You can't run an eval against an agent that doesn't exist yet.

That's exactly the point. If you write the eval set after the agent is working, you're unconsciously grading against whatever the agent already does. Cases you didn't think to write are cases your agent silently fails on forever. Writing 21 cases against a specification (the use case and tool contracts from Part 2) means you're measuring against a real target, not tuning your eval to match your own demo.

The eval set: `eval/cases.json`

21 cases, three buckets:

Bucket	Count	Covers
Easy	12	Shipping-status lookups, simple KB questions, a cancelled-order info request, one no-KB-match case that must escalate rather than fabricate
Hard	6	Refund eligibility inside/outside the 30-day window, multi-item orders where only one item is refunded, boundary cases just past the window
Edge	3	Legal-threat, fraud-flag, and duplicate-ticket patterns — must auto-escalate with zero tool/LLM calls

A sample case, checking both the outcome and the trajectory that produced it:

{
  "case_id": "hard_03",
  "bucket": "hard",
  "ticket": {
    "ticket_id": "hard_03",
    "subject": "Wrong size shoes, keep the socks",
    "body": "The running shoes from order ord_1004 are the wrong size. I want a refund for just the shoes, not the socks.",
    "customer_id": "cust_002",
    "order_id": "ord_1004"
  },
  "expected_trajectory": ["order_lookup", "refund_eligibility", "issue_refund"],
  "expected_outcome": "refund_proposed",
  "expected_max_steps": 4,
  "policy_checks": [
    "refund amount reflects only the shoe item (~$74), not the full order total",
    "issue_refund gated behind human approval"
  ]
}

Three things being checked per case, not just "did the answer look right":

Outcome — did it land on resolved / refund_proposed / escalated correctly.
Trajectory — did it call the right tools, in the right order. This is what catches "right answer, wrong path" failures — an agent that proposes a refund without ever checking eligibility first, for instance.
Policy checks — case-specific assertions, like "never call issue_refund for an already-cancelled order."

Why trajectory matters as much as outcome

An agent can land on the correct final answer through a broken process. If hard_03's agent calls issue_refund before refund_eligibility, and just happens to guess an eligible amount, checking only the final outcome would call that a pass. Checking the trajectory catches it. This maps directly to something the underlying guide's own evaluation framework insists on: different build steps need different kinds of evaluation, and trajectory correctness is its own category, separate from "did the final answer look okay."

One design choice worth flagging honestly: the first version of this trajectory check used exact array equality (JSON.stringify(actual) === JSON.stringify(expected)), and it was wrong — real LLM runs are non-deterministic enough that this produced false failures on completely correct agent behavior. Part 6 covers exactly what broke and the fix (ordered-subsequence matching instead of exact equality), because it's a genuinely useful lesson on its own.

The edge bucket exists to test the guardrail, not the model

The three edge cases — legal threat, fraud flag, duplicate ticket — aren't testing whether the LLM is smart enough to recognize a threat. They're testing whether the auto-escalate pattern match (a plain regex check, covered in Part 5) correctly intercepts these tickets before any model call happens at all:

{
  "case_id": "edge_01",
  "ticket": { "subject": "Final notice", "body": "...lawyer involved...Better Business Bureau." },
  "expected_trajectory": [],
  "expected_outcome": "escalated",
  "expected_max_steps": 0,
  "policy_checks": ["auto-escalated before any LLM/tool call (legal_threat pattern)"]
}

expected_trajectory: [] and expected_max_steps: 0 are the actual assertion: this ticket should never reach the LLM at all. That's a guardrail test, not a model-capability test — a meaningfully different thing to verify, and one worth keeping separate from the easy/hard buckets conceptually even though they live in the same file.

What a real harness run looks like

[PASS] easy_03 (easy)
[FAIL] hard_04 (hard)
    - trajectory: expected [order_lookup, refund_eligibility, issue_refund] as a subsequence, got [order_lookup, refund_eligibility]
[PASS] edge_01 (edge)

=== Summary: 12/21 passed ===
easy: 6/12  |  hard: 3/6  |  edge: 3/3

That hard_04 failure is real — it's the same run that surfaced the most significant bug in the whole build (Part 6 covers it in full: the agent claimed a refund was proposed without ever calling the tool that proposes it). This is what Step 3 buys you: a fixed, pre-written target to run against, so failures like this show up as a clear diff instead of a vague "something feels off."

What's next

Part 4: The Raw ReAct Loop: ~100 Lines, No Framework → covers the actual agent loop — the raw ReAct implementation these 21 cases get run against, with no framework in sight.

Repo: github.com/akash-pal/agent-from-scratch

Part 2: Pinning the Use Case and Writing Tool Contracts Like Specs

Akash Pal — Tue, 11 Aug 2026 18:43:46 +0000

Part 2 of a series building a support-ticket agent with no framework. Part 1 covered why. This part covers Steps 1–2 of the build order: pinning the use case, and writing tool contracts. Repo: github.com/akash-pal/agent-from-scratch

Before any code, two documents: docs/use-case.md and docs/tool-contracts.md. Skipping this step is the single most common reason teams end up with an agent nobody trusts — not because the idea was bad, but because nothing downstream (evals, prompts, memory) had a fixed target to hit.

Step 1: pin the use case

Four gates, filled in before writing a line of code:

Gate	Definition
Bounded input	One support ticket: `{ subject, body, customer_id, order_id? }`
Bounded output	Exactly one of: `resolved`, `refund_proposed` (pending approval), `escalated` (with a reason)
Tool count	5
Success metric	Resolution rate > 85% without escalation; escalation rate < 10%

The tool count cap matters more than it looks. An agent given 10+ tools starts hallucinating tool names and picking the wrong one — a cognitive load problem, not a dependency problem. Keeping this agent to 5 tools, covering exactly three request types (order status, refunds, KB lookups), keeps every run in the healthy 3–8 tool-call range instead of ballooning into a system that needs to be split into multiple specialist agents. (Part 7 covers the actual cost math for when a split is worth it.)

Bounded output matters too: resolved / refund_proposed / escalated isn't just documentation — it becomes a literal parseable prefix (RESOLVED:, REFUND_PROPOSED:, ESCALATED:) that the agent's final message must start with. Part 4 shows exactly how that gets parsed, and Part 5 shows why trusting that string alone turned out to be a real bug.

Step 2: tool contracts are a schema, not a docstring

This is the part that's easy to under-invest in. A tool's description field isn't a comment for future developers — it's the only thing the LLM reads to decide when to call the tool. Treat it as a specification.

Here's the actual refund_eligibility definition from src/tools/index.ts:

{
  name: "refund_eligibility",
  description:
    "Check whether an order is eligible for a refund BEFORE ever proposing one. " +
    "Orders are eligible only if delivered and within a 30-day window of order_date. " +
    "Cancelled orders are already auto-refunded and are never eligible for a manual " +
    "refund. Returns eligible, max_amount_usd, and a policy_ref explaining the decision.",
  gated: false,
  input_schema: {
    type: "object",
    properties: {
      order_id: { type: "string" },
      reason: { type: "string", description: "Customer's stated reason for the refund request" },
    },
    required: ["order_id", "reason"],
  },
}

Notice the 30-day window is stated explicitly in the tool description, not just mentioned once in the system prompt. That's not redundancy — it's a finding from later iteration (full story in Part 6): policy logic that lives only in the system prompt gets missed under load. It has to be load-bearing in the tool itself.

The full contract table, matching each tool to its schema and failure mode:

Tool	Input	Output	Failure mode
`order_lookup`	`{ order_id }`	`{ status, items, total_usd, order_date }`	order not found → structured error, not a guess
`refund_eligibility`	`{ order_id, reason }`	`{ eligible, max_amount_usd, policy_ref }`	cancelled/undelivered → `eligible=false` with a reason; ambiguous → escalate, never assume `true`
`issue_refund` (gated)	`{ order_id, amount_usd, idempotency_key }`	`{ confirmation_id }`	`idempotency_key` required — prevents double-refund on retry
`kb_search`	`{ query }`	`{ articles: [...], relevance_scores }`	no match → explicit empty result; agent must not fabricate an answer
`send_email` (gated)	`{ to, subject, body, ticket_id }`	`{ sent, message_id }`	gated behind pre-action approval (Part 5)

Three details worth calling out specifically:

Idempotency keys aren't optional. issue_refund requires one because retries happen — a flaky network call, a model retrying after a transient error — and a refund tool without idempotency protection means a retry can double-refund a customer. This is enforced in the tool executor itself, not assumed from good behavior:

// src/tools/issueRefund.ts
const issuedRefunds = new Map<string, string>(); // idempotency_key -> confirmation_id

export async function issueRefund(args: Record<string, unknown>) {
  const idempotencyKey = args.idempotency_key ? String(args.idempotency_key) : "";
  if (!idempotencyKey) return { error: "idempotency_key_required" };

  const existing = issuedRefunds.get(idempotencyKey);
  if (existing) return { confirmation_id: existing, replayed: true };
  // ... issue the refund, store it under idempotencyKey
}

Failure modes are structured, not guessed. order_lookup on a missing order returns { error: "order_not_found", order_id }, not an empty object the model has to interpret. kb_search on no matches returns an explicit empty articles: [], specifically so the system prompt can say "if this comes back empty, escalate — don't fabricate an answer."

Gated tools are marked at the contract level. issue_refund and send_email carry gated: true right in their definition. That flag is read by the policy layer (Part 5) to decide which tool calls need a human in the loop before they execute — the gating decision starts here, at the contract, not somewhere downstream.

Data source: mock, but shaped like something real

All five tools read from an in-memory mock store — src/data/mockData.ts: five customers, ten orders spanning inside/outside the refund window, five KB articles. It's deliberately fake data (this repo is a reference build, not a production system — more on that in the repo's own README), but the schemas are shaped to mirror a real commerce API's order/return/line-item structure, so swapping in a real backend later is a data-layer change, not a tool-contract rewrite.

What's next

Part 3: Build the Eval Set Before the Agent Exists → covers building the eval set — 21 cases written before the agent loop existed, and why that ordering is the actual point, not a nice-to-have.

Repo: github.com/akash-pal/agent-from-scratch

Part 1: What Makes Something an Agent (and Why We Built This Without a Framework)

Akash Pal — Tue, 11 Aug 2026 18:43:44 +0000

Most agent tutorials reach for a framework on line one — LangChain, LangGraph, CrewAI, pick one. This series does the opposite. Over seven parts, we build a real support-ticket agent with no agent framework at all: a hand-written loop against a raw model SDK, explicit guardrails, and an eval set built before the agent exists.

The full code is on GitHub: akash-pal/agent-from-scratch. Every article in this series links back to the specific files it's talking about — this isn't a toy snippet series, it's a walkthrough of one real (if intentionally small) build.

Chatbot vs. agent

A chatbot answers once per turn. You send a message, it sends one back, done.

An agent runs a loop: it decides an action, executes a tool, observes the result, and decides again — repeating until the task is done or it gives up. This is the classic ReAct pattern (Reason + Act):

That loop is the entire reason the rest of this series exists. Because the agent calls tools autonomously and repeatedly, small errors compound across steps in a way a single chatbot turn never does. Propose a refund on the wrong order, and unlike a chatbot giving a wrong answer once, an agent might act on that mistake — call a tool, change state, send an email. The infrastructure this series builds — evals, tracing, guardrails, memory design — exists to bound and catch that compounding failure, not because agents are inherently harder to prompt.

Three components sit around the loop:

Tools — each is a name + natural-language description + JSON input schema + an executor function. The description is what the LLM reads to decide when to call it — treat it as a specification, not documentation. (More on this in Part 2.)
Memory — what the agent knows within a run and across runs. (Part 4.)
Orchestrator — the LLM (or a graph/state machine wrapping it) that decides which tool to call next based on the current state.

Why build it without a framework first

Frameworks pay for themselves under specific conditions: multi-agent orchestration, streaming UI needs, integrated tracing, advanced retry/fallback logic, or a team of people who need a shared abstraction. None of those apply to a first agent built by one person to understand what's actually happening.

If you can't tell whether LangGraph is adding value or hiding a bug, you don't yet know what LangGraph is doing for you. Writing the raw loop first — even a bad one — gives you a mental model to evaluate any framework against later. That's the actual thesis of this whole series: build the ~100-line version, understand every step of it, then decide if you need more.

The build order this series follows

Every part below produced a real, committed artifact in the repo, in this order — and the order is deliberate, not incidental:

Pin the use case — bounded input, bounded output, a hard cap on tool count, one measurable success metric.
Map tools & data sources — write every tool contract before writing code.
Build the eval set — 21 cases, written before the agent existed, so it measures against a real target instead of tuning to whatever the agent happens to do.
Write the minimal loop — the raw ReAct loop, no framework.
Write the system prompt — six required elements, versioned like code.
Iterate to green — one change per fix, and a log of what broke and why.
Add human review — approval gating on consequential actions, decided as an architecture choice, not bolted on after launch.

The use case: an e-commerce support-ticket agent

The concrete system this series builds triages and resolves inbound customer support tickets — order status questions, refund requests, and knowledge-base lookups — for a fictional e-commerce company. Five tools, one agent, real guardrails:

order_lookup and kb_search are read-only and run freely. issue_refund and send_email are gated — they require human approval before they execute, because they're consequential and hard to reverse. That distinction — which actions can run autonomously and which need a human in the loop — turns out to be an architecture decision made in Part 1 of the design, not a safety feature bolted on at the end. Part 7 covers exactly how that gating works.

What's next

Part 2: Pinning the Use Case and Writing Tool Contracts Like Specs → covers pinning the use case and writing the five tool contracts — including the specific wording change that fixed a real eval failure later in the series.

Repo: github.com/akash-pal/agent-from-scratch

DEV Community: Akash Pal

Ownership, and Making This Template Your Own (Part 5)

Who owns what

Making this template your own

Where this series leaves you

Shipping It — Scaffolding & CI/CD (Part 4)

Decisions locked before writing code

Scaffolding a new domain team

Two deployment shapes, one running Host

The CI/CD pipeline

Updating the manifest registry is the actual deploy step, so it has to be safe under concurrency

One Login, Every Microfrontend — The Auth Architecture (Part 3)

A few terms, defined once

Population-agnostic by design

The flow: Authorization Code + PKCE

One or more issuers — a config array from line one

One normalized session, regardless of which IdP produced it

Session persistence and cross-tab logout

Logout means telling the IdP, not just forgetting locally

Authorization is claims-driven, never issuer-driven

From login to a mounted page: the whole sequence

Modeling roles in the local dev IdP

Inside the Platform — Topology, Host Shell & Platform MFEs (Part 2)

Design goals, stated as constraints

High-level topology

The Host: what it owns, and what it deliberately doesn't

The three platform microfrontends

Components MFE — the design system

Store MFE — everything that has to be one shared instance

Utilities MFE — deliberately not federated

Wiring it together: how the Host actually uses all three

Domain MFEs — the ×N layer

Dependency management: two layers, not one

Why Module Federation — Building an Enterprise MFE Platform (Part 1)

The one requirement that rules everything else out

The decision

The other options on the table

What this buys, and what it costs

Part 7: Iterating to Green: Real Bugs, and When You'd Actually Reach for a Framework

The iteration log, condensed

Single agent, not multi-agent — and why that's arithmetic, not instinct

Framework selection — now that you've seen the raw version

Where this leaves the repo

Part 6: Observability for AI Agents: Tracing, Metrics, and Drift

The minimum trace payload

Readable in a terminal, structured everywhere else

Three production monitoring layers

Why this matters for debugging, not just monitoring

What's next

Part 5: Guardrails That Live in Code, Not the Prompt

Policy as code

Three human-review patterns

The bug: a claim without a fact behind it

The fix — two layers, not one

What's next

Part 4: The Raw ReAct Loop: ~100 Lines, No Framework

The six-element system prompt

Memory: one state object, not four systems

What's next

Part 3: Build the Eval Set Before the Agent Exists

The eval set: eval/cases.json

Why trajectory matters as much as outcome

The edge bucket exists to test the guardrail, not the model

What a real harness run looks like

What's next

Part 2: Pinning the Use Case and Writing Tool Contracts Like Specs

Step 1: pin the use case

Step 2: tool contracts are a schema, not a docstring

Data source: mock, but shaped like something real

What's next

Part 1: What Makes Something an Agent (and Why We Built This Without a Framework)

Chatbot vs. agent

Why build it without a framework first

The build order this series follows

The use case: an e-commerce support-ticket agent

What's next

The eval set: `eval/cases.json`