Postgres, and a client that shouldn’t be reborn every request

Wiring up Postgres was the easy part: a table for exchanges (prompt, response, timestamp) and a DatabaseClient wrapping a SQLAlchemy connection. The first version created a new client and a new connection on every single request. It worked, but it’s the wrong shape: a real app should open one connection when it starts and reuse it, not pay connection overhead on every prompt.

The fix uses FastAPI’s lifespan context manager: the client is created once, as a global, when the app starts, and closed once, when it stops. It’s a small thing, but the difference between “works in a demo” and “works under real traffic.” is very important.

db_client = DatabaseClient()

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
    db_client.close()

app = FastAPI(lifespan=lifespan)

One more bug here, easy to miss: the Postgres container’s credentials were hardcoded directly in docker-compose.yml (admin/example), while the backend correctly read them from .env. They happened to match, so everything worked right up until someone changes .env and the two sides silently disagree. This was fixed by making the database service read the same environment variables as the backend.

Teaching the backend to delegate

The interesting part: how does a Python backend running in a container actually talk to Claude Code?

The obvious-looking answer is to mount the host’s ~/.claude directory into the container but it turns out to be the wrong one. The real mechanism, already proven in a different part of this same infrastructure (a local AI agent I run for other things), is simpler: claude setup-token generates a long-lived OAuth token once and the CLI picks it up from a CLAUDE_CODE_OAUTH_TOKEN environment variable. No mounted credentials directory, no interactive login inside the container.

The rest is a normal Docker build: claude installed via npm (Node’s official Alpine build, chosen specifically to avoid repeating a glibc-vs-musl binary compatibility trap I’d already hit once with a different tool), a persistent named volume for the CLI’s own config so it doesn’t reset on every restart, and a minimal, empty working directory. For now, there is no need for a real project, since the backend is using Claude Code as a text-generation engine here, not as a coding agent that needs to touch real files.

Delegation itself is a subprocess call, deliberately async so one slow request doesn’t block every other one:

proc = await asyncio.create_subprocess_exec(
    "claude", "-p", full_prompt,
    cwd="/workspace",
    stdout=asyncio.subprocess.PIPE,
    stderr=asyncio.subprocess.PIPE,
)
stdout, stderr = await proc.communicate()

It worked on the first real test. Measured round-trip for a simple prompt: about 3.6 seconds for a full CLI process starting up. Worth knowing before this becomes the path for anything latency-sensitive.

The bugs that don’t announce themselves

The endpoint needed conversation history. I’ve decided to get the last N exchanges and fed them back in as context so the model isn’t starting cold every time. This is where the quiet bugs live.

Bug one, the loud one. The query to fetch recent exchanges was written as:

SELECT (prompt, response, created_at) FROM exchanges ...

Those parentheses around the column list look harmless. My wrong assumption was to prevent SQL Injection attacks without knowing Postgres reads that as one composite column, not three separate ones. The first test request worked fine, because there was no history yet to fetch. The second one crashed:

AttributeError: Could not locate column in row for column 'prompt'

A one-word explanation, once you see it: no parentheses, three real columns.

Bug two, the silent one. The timestamp was meant to be captured the moment a request arrives right before it goes anywhere near the LLM. The code looked right:

response = ChatResponse(
    prompt=msg.prompt,
    response=await call_llm(msg.prompt),   # ~3.6s
    created_at=datetime.now(timezone.utc),
)

But… Python evaluates keyword arguments in the order they’re written, not by name. The created_at argument is the last one on the page, so it’s the last thing evaluated after the multi-second LLM call already finished. The timestamp was quietly measuring the wrong moment. Fixed by capturing it as its own variable, first line of the function, before anything else runs.

Bug three, the one that ate its own fix. Recent-history queries naturally come back newest-first. Fed straight into a prompt, that reads backwards to the model: the last message first and the first message last. The fix is to reverse the list in Python before building the context, except the first attempt changed the SQL to sort oldest-first and added the Python-side reverse. Confirmed by literally asking the model to recite the conversation back in order and it gave the order correctly, 1 through 4.

None of these three would show up in a five-minute demo. Two of them only show up once there’s enough data or enough history for the wrong behavior to matter. It is exactly the kind of bug that’s cheap to fix now and expensive to debug later, in production, with a confused conversation to untangle.

What’s next

Backend and database talk to each other, and the backend talks to Claude Code. What’s still missing is a way for a person to talk to any of it. Task 4 is the chat UI. No deadline on when that happens; it happens when it happens.

→ Full build series · Project page

A UI, and a bug that only shows up in markdown

The chat UI itself is unremarkable in the good way: a controlled input, Enter to send, Shift+Enter for a new line, disabled while a response is pending. The more interesting part is what happens to the response once it arrives. Claude Code’s replies come back as markdown and rendering that as plain text loses all of it. Using the react-markdown plus remark-gfm modules fixed that in about ten lines; user messages stay plain text, since they’re not meant to be formatted.

The bug that only exists in the built version

Docker Compose was already running backend, frontend, and Postgres separately in dev (pnpm dev, docker compose up for the rest). The actual test: a full docker compose up from nothing, then a real browser hitting :3000 is where things fell apart, in two layers.

The first layer was the one I expected: no CORS headers on the backend, so a browser calling :8000 directly from :3000 gets blocked. The fix was small: use the CORSMiddleware module scoped to a FRONTEND_ORIGIN environment variable. CORS stands for Cross-Origin Resource Sharing and is a security feature used by web browsers to control how a website on one domain can request and access resources from a different domain. It was chosen over a reverse proxy specifically because this app still isn’t exposed publicly; a proxy earns its complexity once that changes, not before.

The second layer was quieter, and CORS headers wouldn’t have fixed it. The frontend’s fetch('/chat') and fetch('/history') calls use relative paths. In pnpm dev, Vite’s own proxy rewrites those transparently to :8000 so it looked correct. But the Docker frontend serves a static production build (serve -s dist), with no proxy layer at all. A relative /history request there just hits the frontend’s own static server, finds no matching file, and falls through to index.html. This caused the app’s own shell to be silently returned in place of JSON. No error, no crash, just the wrong response shape. It surfaced by literally running curl :3000/history and noticing HTML come back where JSON should have been. This is the kind of gap that only shows up when you run the real, built artifact, not when you re-read the code that produced it.

The fix: bake the backend’s real origin into the static build itself as a VITE_API_BASE_URL build argument threaded through frontend/Dockerfile and docker-compose.yml. Vite inlines VITE_* variables at build time, so the compiled JS calls the backend directly, origin and all, with no proxy required.

Conversation history, for real this time

The exchanges table always had an id column but nothing before now had ever selected it. Adding it to the response model was the easy part; three endpoints followed naturally: GET /history for the full conversation, DELETE /history/{id} for a single exchange, and DELETE /history for everything.

The UI treats a prompt/response pair as the actual unit of storage, which makes it the natural unit of deletion too so history loads on page mount (a refresh won’t lose the conversation in this way), each exchange gets its own delete control, and clearing everything sits behind an explicit confirm/cancel step, since there’s no undo once it’s gone.

Tests, so the browser stops being the test

Every one of the bugs above and the two from Part 3 were caught by hand: reading a stack trace, running curl, opening a real browser. That works, but it doesn’t scale, and it doesn’t repeat automatically. The last piece of v1 was a test suite built specifically so a future change can be verified without a browser at all.

The one real decision here was the backend’s test database: a disposable Postgres, not SQLite. It would have been faster to fake it but the raw SQL in this codebase is Postgres-specific, and two of the bugs already found (the composite-column SELECT and the timestamp-ordering one) are exactly the kind that a friendlier substitute database could paper over instead of catching. Testing against the real thing paid for itself immediately: writing the fixtures surfaced a genuine deadlock where the app’s read methods never closed their implicit transaction, which was harmless in a long-lived production connection but left a lock held just long enough to hang the next test’s cleanup. Something SQLite would never have shown at all. This could’ve been prevented by explictly calling SQLAlchemy’s own .commit() on the connection after a query was called.

The two regression tests for Part 3’s bugs weren’t just written to check current behavior. This was done so each one can be verified by literally reintroducing the original bug, watching the test fail, then reverting it. The frontend side is smaller in comparison: Vitest and React Testing Library, fetch mocked, covering send-and-render, per-exchange delete, and the clear-all confirmation gate.

Where it stands

The v1 is done: the chat, the persisted and deletable history, a Docker Compose stack that survives a clean checkout, and a test suite that means the next change doesn’t have to be verified by hand. What comes after this is a larger, deliberately undated idea. Turning this into something closer to a content system than a chat demo and it stays exactly that: available whenever there’s real appetite for it, not scheduled. This would include a deliberate stage for automatic deployment of the app over to Kubernetes, using a lightwight version of it called K3s.

All posts in this series → · Project page →

None of them got built. Not because the ideas were bad — the architectures were actually fairly detailed — but because each one tried to prove too much at once: a backend split across multiple languages “to show I know them all,” telemetry, observability, multi-agent orchestration, all in the same first version. The kind of scope that feels good on paper and turns overwhelming right when you’d need to write the first line of code.

So this time I’m starting differently: Sovereign AI Nexus is a very small application — a Python/FastAPI backend, a PostgreSQL database, a React/TypeScript frontend, and exactly one working flow. You send a prompt, you get back a response generated by an AI model, rendered as a text artifact. That’s it. No conversation history, no authentication, no agent orchestration. All real ideas, just not part of the first version.

The kind of app isn’t new to me. I’m essentially building a minimal, self-hosted version of the AI dashboards I already use daily (Claude Code, other agent tooling) — a conversation, a panel of generated artifacts. The difference is that this time it’s mine, from the infrastructure up.

What I did keep from the two earlier project ideas that got closest to actually being built:

• Docker Compose from the first task, not as an afterthought — every service in its own container, with hot-reload, verified working before the real code starts.
• Secret hygiene from day one — any API key stays strictly server-side, never in an environment variable that could accidentally end up in the bundle shipped to the browser.
• And, maybe most importantly: no pressure to build this for a specific role. It’s a project that demonstrates real interest in Backend and AI Platform Engineering.

Next up is starting the small tasks: a backend that runs, a table that persists, an endpoint that actually responds to a prompt. None of it has a deadline. The one thing in this whole process that doesn’t get to change its mind is publishing this post.

→ Full build series · Project page

The scaffold itself

For the backend I used FastAPI and uvicorn, managed with uv — fast, and about as simple as it gets to wire up: a @app.get(path="/") decorator over the handler function. For the frontend, React and TypeScript, scaffolded with Vite.

Each service becomes its own image via its own Dockerfile. The project orchestrates both containers through a docker-compose.yml at the root. Nothing unusual so far.

The reload that refused to work

The first thing I tested was backend hot-reload — edit a local file, expect to see the change without a rebuild. Nothing happened. I added --reload to uvicorn. Still nothing.

The real cause: the volume in docker-compose.yml mounted the host code to /code/app inside the container, but uvicorn was importing the app from core.main:app — i.e. from /code/core, a completely different path. My edits were landing in a directory nobody was reading. Simple fix once found: the mount has to target the exact import path, not a generic convention copied from a tutorial.

pnpm add -g and a PATH that doesn’t exist

On the frontend, the production build needed to serve static files through a package called serve, installed globally (pnpm add -g serve). The error: pnpm’s global bin directory wasn’t on PATH — and it had no way to be, since pnpm setup (which would normally fix this) edits a .bashrc, and a Docker RUN step has no interactive shell to read it.

The cleaner fix wasn’t patching PATH — it was avoiding the global install entirely: add serve as a normal project dependency and run it through pnpm exec serve, which resolves the binary from node_modules/.bin with nothing global involved.

A mount that broke exactly what it was meant to help

After fixing reload on the backend, I tried the same trick on the frontend — mount the whole codebase over /app. Result: a 404 on every request. The reason: the frontend container runs the already-built app (serve -s dist), not a dev server watching for changes. The mount replaced the entire /app from the image — including dist/, built at image-build time — with the host directory, which had no dist/ at all.

The lesson: not every container benefits from a volume mount. For real frontend iteration, the right answer isn’t Docker — it’s running pnpm dev directly. Vite already has native HMR, faster than anything I could build through a container.

Kaniko is not BuildKit

The most subtle bug came from CI, not local development. I used uv’s own official Docker recipe — RUN --mount=type=bind,source=uv.lock,... — which worked perfectly locally. On Jenkins, the build failed with “No pyproject.toml found,” an error that made no sense at first glance.

The cause, found straight from the Kaniko build log: RUN --mount is BuildKit-specific syntax, and Kaniko — the actual builder behind this CI — ignores it entirely, silently. No unknown-syntax error, it just runs the command without the mounts it was promised. The files never landed where uv sync was looking for them. The fix was a plain COPY — less elegant than the official recipe, but portable across builders, not just my machine.

On top of that: a uv.lock that had ended up gitignored by mistake, from a template meant for libraries rather than applications. A lockfile should always be committed for an application, exactly like a package-lock.json.

CI/CD: one image per service, one SSH key per repo

For the build side, I went with a single Jenkinsfile with separate stages per service (backend, frontend) rather than separate Jenkins jobs — a build failure in one service doesn’t block the other, without paying the setup cost of a whole new job.

The more interesting part was mirroring to GitHub. I wanted a single SSH key, with its blast radius scoped per-repo via GitHub Deploy Keys, rather than a new token to manage for every mirrored project. Gitea’s native Push Mirror doesn’t support SSH — confirmed directly from source, not just from failed attempts. The fix: the push happens from a dedicated Jenkins stage, right after checkout, using the key as a Jenkins credential — independent of whether the Docker build succeeds, so syncing to GitHub never depends on anything else.

What’s next

The next real step is Postgres — one table, one SQLAlchemy model, nothing more. No deadline attached; it happens when it happens.

→ Full build series · Project page