HTTP clients

The whole frontend talks to one configured address — the gateway. apps/web/src/lib/api/httpClient.ts exposes two Axios instances that both point at that single origin and share one auth interceptor. All network calls go through them — never fetch directly, never a fresh Axios instance per feature.

One origin

// apps/web/src/lib/api/routes.ts
export const API_ORIGIN = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3110'

NEXT_PUBLIC_API_URL is the single backend variable, resolved identically in the browser and on the server — no legacy per-service fallbacks. It points at the gateway (apps/gateway, :3110 in dev), which routes by path prefix to the right upstream (platform-api vs agent-service). The frontend never addresses individual services.

API_ORIGIN lives in the dependency-free routes.ts (not httpClient.ts) so both client and server can import it without pulling Axios in.

Two instances, same origin

import { httpClient } from '@/lib/api/httpClient'

httpClient.api      // CRUD-style calls (resumes, users, notifications…)
httpClient.agent    // AI-style calls (interview, …)

Instance	Intent
`httpClient.api`	Product CRUD — resumes, version history, sharing, users, notifications
`httpClient.agent`	AI / long-running — interview and other agent calls

Both are createClient(API_ORIGIN) — the same base URL. The split is purely for call-site semantics (CRUD vs AI reads better than one client everywhere); it is not two different backends. The gateway decides where each /api/... path actually goes.

Auth interceptor

configureHttpClient(getter) registers one request interceptor on both clients:

configureHttpClient(async () => clerk.session?.getToken())

The interceptor calls getAuthToken() and, if a token comes back, sets Authorization: Bearer <jwt> (unless the caller already set one). getAuthToken() also caches the last good token; getCachedAuthToken() exposes it synchronously for exit-time keepalive requests (see resumeApi.syncResumeKeepalive), where the page may die before an async token fetch resolves.

Don’t pass tokens manually in feature code. If you’re writing httpClient.api.get(url, { headers: { Authorization: ... } }), the interceptor isn’t wired in that context — fix the wiring, don’t bypass it.

Centralized routes

All paths live in src/lib/api/routes.ts and are all under the /api/* prefix (the gateway’s namespace):

export const API_ROUTES = {
  resumes: {
    list:   '/api/resumes/mine',
    create: '/api/resumes',
    byId:   (id: string) => `/api/resumes/${id}`,
    patch:  (id: string) => `/api/resumes/${id}`,        // see resume-schema for the patch contract
    versions: (id: string) => `/api/resumes/${id}/versions`,
    // …sharing, comments, replies
  },
  users:         { pats: '/api/users/me/personal-access-tokens', /* … */ },
  notifications: { list: '/api/notifications', /* … */ },
  knowledge:     { timelines: '/api/knowledge/timelines' },
}

export const AGENT_ROUTES = {
  interview: { start: '/api/interview/start', chat: '/api/interview/chat', /* … */ },
}

// Next.js route handlers the AI Lab service layer calls (app/api/chat-agent/*)
export const WEB_AGENT_ROUTES = { chat: '/api/chat-agent', chatApprove: '/api/chat-agent/approve', /* … */ }

Rules:

No inline path strings — every backend path lives in one of these maps.
API_ROUTES / AGENT_ROUTES hit the gateway; WEB_AGENT_ROUTES are the web app’s own Next.js route handlers (app/api/chat-agent/*) that proxy to the agent.

This is what makes a backend route rename a one-file change instead of a grep-and-pray.

Adding a new endpoint

Add the path to the right map in routes.ts.
Add a typed wrapper in src/lib/api/<feature>.ts returning a typed response.
Use httpClient.api or httpClient.agent — never axios.create() a third client.
If the feature is cloud-only, gate the caller on APP_MODE === 'cloud'.

Introduction

Self-hosting & deployment

Architecture

MCP server

Development

One origin

Two instances, same origin

Auth interceptor

Centralized routes

Adding a new endpoint

​One origin

​Two instances, same origin

​Auth interceptor

​Centralized routes

​Adding a new endpoint

One origin

Two instances, same origin

Auth interceptor

Centralized routes

Adding a new endpoint