The Living Portfolio, explained from the ground up

Two apps, two clouds, one push

The portfolio is two separate applications that live on two separate clouds, tied together by GitHub:

• The site (living-portfolio) — a single hand-written index.html of plain HTML/CSS/JavaScript, served by Vercel.
• The API (samuel-ai-api) — a Python FastAPI backend hosted on Render, which calls the Anthropic (Claude) API for answers, the OpenAI API for embeddings, and a Neon Postgres database for its knowledge store.

%%{init:{'theme':'base','flowchart':{'htmlLabels':false},'themeVariables':{'fontFamily':'ui-monospace, monospace','fontSize':'13px','primaryColor':'#e9f0ff','primaryBorderColor':'#3f74f5','primaryTextColor':'#17223a','lineColor':'#8794ab','secondaryColor':'#e4f6f2','tertiaryColor':'#f2f5fb'}}}%%
flowchart LR
  Dev([You: git push]) --> GH[GitHub
source of truth]
  GH -- rebuilds --> V[Vercel
the website]
  GH -- rebuilds --> R[Render
the API]
  User([Visitor's browser]) -- loads page --> V
  User -- asks a question --> R
  R -- embeds text --> O[OpenAI
embeddings]
  R -- writes/reads vectors --> N[(Neon Postgres
+ pgvector)]
  R -- generates answer --> A[Anthropic
Claude]
      

The words you'll need

The rest of the guide uses these terms constantly. Here's each one in a sentence — the full glossary is at the bottom.

API

A server that answers requests over the web. The browser sends JSON, the API sends JSON back.

LLM

A large language model (here, Anthropic's Claude) — the thing that writes the answers.

RAG

Retrieval-Augmented Generation: look up the relevant real documents first, then make the model answer using only those.

Embedding

Turning a piece of text into a list of numbers (a vector) that captures its meaning, so similar meanings land close together.

Vector search

Finding the stored text whose meaning-vector is closest to the question's — search by meaning, not keywords.

Grounding

Forcing the model to answer only from the retrieved sources, and to refuse when they don't cover the question.

Agent

An AI that works in a loop — it decides which tools to call, reads the results, and repeats until it can answer.

MCP

Model Context Protocol: a shared standard for offering those tools to any AI app (Claude Desktop, an IDE, another agent).

Streaming (SSE)

Sending a reply in pieces as it's written, so words appear live instead of all at once.

Observability

Being able to tell what the system is doing from the outside — request ids, timings, and live health numbers.

The journey of one question

When you type a question into the chat and hit send, here is every real step it takes — from the browser to the answer and back. Each later section zooms into one part of this.

%%{init:{'theme':'base','flowchart':{'htmlLabels':false},'themeVariables':{'fontFamily':'ui-monospace, monospace','fontSize':'13px','primaryColor':'#e9f0ff','primaryBorderColor':'#3f74f5','primaryTextColor':'#17223a','lineColor':'#8794ab','secondaryColor':'#e4f6f2','tertiaryColor':'#f2f5fb'}}}%%
flowchart TD
  B([Browser POSTs the conversation]) --> C{CORS
allowed origin?}
  C -- no --> X[Browser blocks it]
  C -- yes --> M[Middleware: give it an ID,
start a timer]
  M --> RL{Rate limit:
under 20 / 60s?}
  RL -- no --> E429[429 Too Many Requests]
  RL -- yes --> Q[Build query from
last 2 user turns]
  Q --> EMB[Embed the question
OpenAI 1536-dim]
  EMB --> VS[Top-5 vector search
Neon + pgvector]
  VS --> G{Best match
≥ 0.35?}
  G -- no --> REF[Refuse — no model call, $0]
  G -- yes --> P[Ground Claude on the
numbered sources]
  P --> CL[Claude Haiku 4.5
writes the answer]
  CL --> FIN[Renumber citations,
strip markdown, price it]
  FIN --> RESP([Reply + citations + cost + trace])
  REF --> RESP
  RESP --> LOG[Middleware: log JSON line,
record metrics, set X-Request-ID]
      

The two-gate shape is the heart of it: retrieval decides whether to answer at all, and only a strong enough match reaches the model. Everything else — the middleware, the rate limit, the trace — wraps around that core.

The centerpiece: answers grounded in real documents

The chat assistant doesn't answer from the model's general memory. It answers only from Samuel's own documents, cites its sources, and refuses when the documents don't cover the question. That is RAG, and it's the most important part to understand.

%%{init:{'theme':'base','flowchart':{'htmlLabels':false},'themeVariables':{'fontFamily':'ui-monospace, monospace','fontSize':'13px','primaryColor':'#e9f0ff','primaryBorderColor':'#3f74f5','primaryTextColor':'#17223a','lineColor':'#8794ab','secondaryColor':'#e4f6f2','tertiaryColor':'#f2f5fb'}}}%%
flowchart LR
  subgraph Ingest [ Ingestion — run once, offline ]
    direction TB
    MD[corpus/*.md
6 markdown files] --> CH[Chunk: ~1000 chars,
150 overlap]
    CH --> EM1[Embed each chunk
OpenAI 1536-dim]
    EM1 --> DB[(Neon: documents
+ chunks + HNSW index)]
  end
  subgraph Ask [ Every question ]
    direction TB
    QQ[Question] --> EM2[Embed question]
    EM2 --> SR[Cosine top-5
vs the HNSW index]
    SR --> DB
  end
  DB --> GR{≥ 0.35?}
  GR -- no --> RF[Refuse]
  GR -- yes --> AN[Ground Claude → cited answer]
      

The corpus — knowledge as documents

Chunking — cutting documents into pieces

Embeddings — turning text into meaning

Vector search — finding the closest chunks

Grounding & the refusal threshold — the anti-hallucination gate

Citations you can touch

Measuring quality instead of guessing

"It seems to work when I try it" is not evidence. The evals system scores the assistant on a fixed set of questions with known-correct behaviour, so quality is a number, not a vibe.

The system reporting on itself

Every request gets a short id, is timed, and is logged as one line of JSON to stdout (which Render captures). An in-memory metrics registry tallies request counts, status classes, per-path counts, latency percentiles, and chat economics — always labelled with the process start time so the numbers are an honest "since this deploy" window, never a fake lifetime total.

An AI that uses tools in a loop

The chat answers one question in one shot. The agent is different: it's given a task plus a menu of tools, and it decides which to call, reads the results, and iterates until it can answer. That autonomous, multi-step tool use is the actual draw of agents.

%%{init:{'theme':'base','flowchart':{'htmlLabels':false},'themeVariables':{'fontFamily':'ui-monospace, monospace','fontSize':'13px','primaryColor':'#e9f0ff','primaryBorderColor':'#3f74f5','primaryTextColor':'#17223a','lineColor':'#8794ab','secondaryColor':'#e4f6f2','tertiaryColor':'#f2f5fb'}}}%%
flowchart TD
  T([Task: 'Is he a fit for this role?']) --> LLM[Claude + the 4 tool schemas]
  LLM --> D{Asked for
a tool?}
  D -- yes --> RUN[Run it: search_portfolio /
list_skills / list_projects / list_services]
  RUN --> FEED[Feed the result back]
  FEED --> LLM
  D -- no --> ANS([Final answer + every step it took])
  LLM -. hard cap: 6 loops .-> ANS
      

Publishing the tools to any AI client

The agent's four tools were useful but locked inside one endpoint. MCP (Model Context Protocol) is a shared standard — a universal plug — for offering tools to any AI app. mcp_server.py wraps the same four functions and publishes them over MCP with FastMCP, so Claude Desktop, an IDE, or another agent can use them.

Watching the answer type itself

Instead of waiting for the whole answer, /chat/stream sends it in pieces using Server-Sent Events — one long HTTP response where each message is data: {…}. The model's text arrives as token events as it's written, then a final done event carries the finished reply, citations, cost, and trace. /agent/stream does the same with step events (each thought or tool call) then a done.

The backend — a typed API

A Python FastAPI app. Every request and response is a typed Pydantic model, so a malformed request is auto-rejected with a 422 and the exact field errors before any handler runs — and the interactive docs at /docs generate from those same types. It exposes eight routes (plus the optional /mcp):

Rate limiting — protecting the paid endpoints

The chat and agent endpoints each cost real money per call and are open to the internet, so a script could run up a bill. A thread-safe sliding-window limiter caps each client IP at 20 requests per 60 seconds (both tunable by env var). Over the cap, the server returns 429 Too Many Requests with a Retry-After header. A blocked request isn't recorded, so a persistent caller recovers as its window slides rather than locking itself out. A normal visitor stays far under the cap; a script hits it.

The frontend — no framework, on purpose

The whole site is one hand-written index.html: HTML for structure, CSS custom properties (--accent, --bg, …) as a design-token system, and vanilla JavaScript for behaviour. No React, no build step. The only heavy library is three.js, lazy-loaded and only for optional 3D layers that are flagged off in production — so a normal visitor downloads none of it.

Two interactive explainers on the site are worth calling out: the Architecture X-Ray traces one request through its real layers (the system in time), and the Deployment Topology shows the six services and their connections (the system in space) — including the one push that fans out to two clouds, which a linear request trace can't express.

Deployment — one push, two clouds

There are no manual deploy steps. A git push to main triggers continuous deployment: Vercel rebuilds the site and Render rebuilds the API, in parallel, independently. Each half can ship or roll back on its own.

%%{init:{'theme':'base','flowchart':{'htmlLabels':false},'themeVariables':{'fontFamily':'ui-monospace, monospace','fontSize':'13px','primaryColor':'#e9f0ff','primaryBorderColor':'#3f74f5','primaryTextColor':'#17223a','lineColor':'#8794ab','secondaryColor':'#e4f6f2','tertiaryColor':'#f2f5fb'}}}%%
flowchart LR
  P([git push main]) --> GH[GitHub]
  GH --> V[Vercel
rebuilds the site]
  GH --> R[Render
rebuilds the API]
  R -.->|reads secrets at runtime| S[[ANTHROPIC / OPENAI /
DATABASE_URL — never baked in]]
      

The precise wording matters and is deliberate: the site says continuous deployment (automated deploy on push), not "CI/CD" — the automated test-gate in CI is a later module and isn't claimed yet. That's an honesty distinction, not a nitpick.

The last two — both shipped, each earned differently

Two deployment artifacts live in the repo. The honesty rule is that a green "Shipped" badge means built and verified — and both have now earned it, but the verification looked different for each.

The test suite — where honesty becomes a test

62 tests across seven files, covering the pure logic without needing the network or a paid API: chunking, the grounding/refusal decision, citation renumbering, the plain-text strip, the conversation query, cost math, the metrics registry, the rate limiter, the agent's tools and loop (driven by a fake client), and the MCP server (over a real in-memory client↔server session).

The honesty system — the thesis of the whole thing

One principle runs through every part: shipped work and in-progress work are always explicit, and nothing is claimed that can't be defended. It shows up everywhere — the corpus is audited before ingestion; the bot refuses rather than guesses; every metric names its window; the agent's prompt forbids calling building work "shipped"; the roadmap distinguishes three states; and tests fail if a claim outruns reality.

The module roadmap

The system was built in public, one module at a time. Where each stands today:

Plus hardening that isn't a numbered module: rate limiting (shipped) and an opt-in hosted MCP endpoint (deployed dormant behind a flag).

Glossary — say these correctly

RAG

Retrieval-Augmented Generation: retrieve relevant documents, then have the model answer using only them.

Embedding

A list of numbers (a vector) representing a piece of text's meaning. Here, 1536 numbers from OpenAI's text-embedding-3-small.

Vector / dimensions

Each text becomes a point in 1536-dimensional space; nearby points mean similar things.

Cosine similarity

How aligned two vectors' directions are. pgvector's <=> gives cosine distance; similarity is 1 − distance.

Chunk

A ~1000-character slice of a document that gets embedded and retrieved (with 150 chars of overlap).

pgvector

A Postgres extension adding a VECTOR type and similarity search.

HNSW

The index that makes nearest-vector search fast without scanning every row; builds incrementally, no training.

Grounding

Constraining the model to answer only from provided sources.

Hallucination

The model confidently making something up; grounding + a refusal threshold is the defense.

Top-k

Retrieving the k best matches (here, k = 5).

Threshold

The minimum similarity (0.35) below which the bot refuses.

Agent

An AI that loops — decides a tool, runs it, reads the result, repeats — up to 6 times here.

Tool

A specific action the AI can trigger; here four read-only lookups over the corpus and service list.

MCP

Model Context Protocol — a standard way to offer tools to any AI client.

stdio

Talking over a program's standard input/output pipes instead of a network port.

SSE

Server-Sent Events — a one-way stream of data: {…} messages, used to send tokens live.

Middleware

Code that wraps every request — here it ids, times, logs, and records each one.

CORS

A browser rule about which sites may call an API; only the portfolio's origin is allowed by default.

Rate limiting

Capping requests per client IP in a window (20 / 60s), returning 429 when exceeded.

Connection pool

Reusing warm database connections instead of reconnecting per request; here validated on checkout.

Continuous deployment

A push to main auto-deploys — no manual step. (CI/CD adds an automated test-gate, not yet claimed.)

Infrastructure-as-code

Describing servers/databases in text files (Terraform) instead of clicking dashboards.