The mental model, & lessons learned

This portfolio's mission is "show, don't tell": instead of listing AI/ML engineering, data engineering, and agentic-methods skills on a résumé, it runs them, live, in production. A recruiter reading a bullet point about "agentic AI" has to take it on faith; a recruiter watching a real chat agent cite live Postgres numbers, a real GPU inference backend answer a request on Hugging Face's free ZeroGPU tier, or a real tailoring pipeline attach a PDF to an application is watching engineering happen.

The constraint that makes that proof credible is that none of it costs anything to run, indefinitely. That's not a cost-cutting afterthought — it's the actual design requirement this whole platform is built against. Every layer runs on a free tier: GitHub is the data warehouse and logic engine (a GitHub Actions cron drives ingestion through a raw → staging → production lifecycle, with unlimited compute minutes on a public repo), Vercel is a thin presentation layer (Next.js 16, rendering pre-processed data rather than doing heavy compute), and Hugging Face is the inference engine (ZeroGPU today, Colab's free GPU/TPU tiers next). Staying inside those limits — Vercel's rolling 100-deploys/24h window, GitHub's once-a-day free cron cap, ZeroGPU's per-call time quota — is itself the engineering exercise, not a constraint worked around once and forgotten.

That's also why this project treats AI/ML engineering and data engineering as one discipline rather than two: the Job Board's Neon Postgres pipeline, the résumé-tailoring agent, and this site's own RAG chat agent all move through the same shape — ingest real data, reason over it under a bounded compute budget, and serve the result — whether the compute is a GitHub Action, a Vercel function, or a Hugging Face Space. Agentic methods are the mechanism that makes that shape work end-to-end without a human in the loop for every step.

Two channels feed the same funnel, and this site is the landing page for both.

Outbound is résumé-first: the apply-to-jobs pipeline (see the Job Board section below) scrapes real postings, tailors a résumé per role through a bounded-concurrency Gemini pipeline, checks every draft against a golden-dataset QA rubric, and renders it to a PDF that gets attached directly to the application. That PDF is the artifact a recruiter or an ATS sees first — this site is where they land next, to verify the claims on it.

Inbound is LinkedIn-first, and slower by design: the roadmap's content phase turns the same engineering arc — design decisions, trade-offs, lessons learned — into a YouTube and LinkedIn content stream, so the portfolio is discoverable by people who were never sent a résumé at all.

Both channels converge on the same three stakeholders in a recruiting pipeline, and each reads this site differently:

• Recruiters scan for role fit, availability, and work authorization fast — the résumé and the About Me section are built for that pass.
• Hiring managerswant outcomes and judgment — the pipeline board, the roadmap phases, and this changelog's lessons-learned are aimed at that read.
• The technical team wants depth — architecture diagrams, real trade-offs, and, when they ask, a chat agent that can go as deep as the résumé itself allows without fabricating a number.

The chat agent embedded on this site is built for exactly that range: instructed to answer "professionally, accurately, and persuasively" and to recommend contacting Thomas after every response, but also to reach for concrete tech-stack and engineering-depth detail the moment a technical question shows up — one agent has to satisfy a non-technical recruiter's first pass and a technical interviewer's follow-up, without switching tools.

Flagged: this section is newly-authored synthesis of real, separately-documented facts — not a verbatim quote from any single existing file.

Before the details — design, data, model, backend, frontend, ops; hardware up through distributed systems; the version history below — there's one mental model that organizes all of it, and it's worth drawing before explaining.

The compass has three axes from one origin, not two — it's not a 2D chart with an x and a y. End-to-end points right: the lifecycle a system moves through from design to data to model to backend to frontend to ops. Abstraction points up: the ladder from raw hardware up through distributed systems. Time points down-left: iteration — what shipped, what broke, what got learned, in that order, every release.

"Agent" gets used loosely enough industry-wide that it's worth defining by mechanism instead of adjective. On this site, something only gets called an agent if it does all four of these, observably:

1. It perceives real data.Not a hardcoded fixture — the apply-to-jobs pipeline scrapes live Apple and NVIDIA postings; this site's chat agent reads the actual résumé markdown and live Postgres pipeline counts at request time.
2. It reasons under a bounded constraint, through an LLM. apply-to-jobs tailors a résumé per role through a bounded-concurrency Gemini pipeline with quota-vs-rate-limit-aware backoff — deciding, per call, whether a failure means "back off" or "this model's daily quota is actually exhausted, fail over." The chat agent reasons over that same résumé under a fixed system prompt and a token budget, not an open-ended one.
3. It acts — it produces a real, shippable artifact. apply-to-jobs's output is a rendered, uploaded PDF attached to a real application, not a suggestion a human has to rewrite. linkedin-content-loop and agentic-writer — both extracted into standalone open-source repos out of this same lineage — close a similar loop for content generation and LinkedIn posting automation.
4. It gets checked before it ships.Every tailored résumé is auto-checked post-generation against a golden-dataset rubric — weak or missing quantifiable metrics, unsupported skill claims, missing hyperlinks, banned words, semicolons, a hard 2-page limit — before it's ever attached to an application. An agent that isn't checked before it acts isn't trusted enough to call one.

By that bar, this site's chat widget is a smalleragent than apply-to-jobs — it perceives and reasons, but its "action" is a streamed answer, not a shipped artifact — and that's fine; the definition is about mechanism, not about which one is more impressive.

Note the correction from the design pass: point 3 no longer asserts a specific internal "draft → review → validate → publish → archive" pipeline for agentic-writer/linkedin-content-loop — that detail isn't confirmed anywhere this repo can see. Point 4's rubric list restores "semicolons" to match GITHUB_CONTEXT §7 exactly.

Prompt engineering is the actual mechanism behind point 2 — how the reasoning step above gets steered, not just that it happens. The default template used across this project's agents is deliberately simple: state the objective, the steps to complete it, at least one explicit constraint, and a known example where one exists — with the balance shifting toward more constraints as a task gets more consequential (a résumé rubric check is constraint-heavy; a chat agent's tone guidance is not).

CAP theorem is the textbook reflex the moment "distributed systems" comes up: pick two of consistency, availability, and partition tolerance. It's not wrong, but it's the wrong first question for a system whose binding constraint isn't a distributed-consensus trade-off — it's a $0 budget. That budget rules out an entire axis CAP doesn't talk about: this system cannot vertically scale its way out of a problem. There's no bigger Vercel plan, no bigger compute instance, no upgrade path that costs money, by design. So the axes that actually drive design decisions here are reliability, maintainability, adaptability, and resilience — and the concrete recommendation that falls out of that constraint is to scale horizontally, by partitioning work across several free-tier providers, rather than vertically within any one of them.

That four-axis list isn't invented from scratch — it's a deliberate adaptation of Chip Huyen's canonical four characteristics of a well-designed system: reliability, scalability, maintainability, and adaptability, from Designing Machine Learning Systems (O'Reilly, 2022). Three of her four carry over here unchanged: reliability, maintainability, adaptability. The fourth — scalability — is deliberately swapped for resilience, and not as a hedge: a system that structurally cannot vertically scale (the $0-budget constraint named above) doesn't get to claim scalability as a real, honest axis of its own design. What it can still be judged on is whether it survives a provider outage or a policy change without going down, which is what resilience measures here. Textbook version: reliability, scalability, maintainability, adaptability. Applied version: reliability, maintainability, adaptability, resilience. The swap isn't an oversight — it's the constraint talking.

That's what the "GitHub Monolith" architecture actually is: GitHub does the ETL/compute (a public repo gets unlimited CI minutes and a full, multi-hour-runtime VM per job, not a serverless function's 10–60 second cap), Vercel does the thin presentation layer (built to receive pre-processed data, not to compute it), and Hugging Face does inference (offloaded so it never competes with the page's own budget). Each provider's free-tier limit resets on its own schedule — Vercel on a rolling 24-hour/30-day window, GitHub on a fixed monthly billing date — and the "Vercel-Pinger" pattern (a GitHub Action cron commits data, and that commit itself triggers a Vercel deploy) exists specifically to route around Vercel's free-tier cron cap without paying for a better one. The system-design docs calculate a concrete safe operating point from this: at 100 deploys/24h with a 20% buffer reserved for manual hotfixes, hourly automation (24 deploys/day) is the recommended safe maximum — going past roughly 15-minute intervals risks a lockout window that neither more money nor more cleverness gets you out of early. As the roadmap docs put it, this "Code Monolith" architecture hosted on GitHub exists to guarantee infrastructure resilience — the same codebase can redeploy to Hugging Face, Vercel, AWS, or GCP, so no single provider's outage or policy change is a single point of failure for the whole system.

The lessons-learned entries in this changelog are what reliability and resilience look like in practice here, not abstractions. The Job Board's schema-drift bug — a posted_datecolumn that changed type out from under a live read path — is a maintainability failure: two services (a writer and a reader) drifted out of shared understanding of a schema neither one fully owned. The ZeroGPU 402 paid-tier-gate bug is an adaptability failure: even a "free" tier hides paid-tier assumptions inside its own API surface, and the fix was adapting the deploy path around a constraint that wasn't documented anywhere. The CSS theme-cascade bug that shipped unreadable text to a production page that built cleanly locally is a reliability gap in verification, not in code — it only surfaced by checking the actual deployed page. None of these are CAP-theorem trade-offs; they're the four axes above, showing up as real incidents, at zero infrastructure cost, on a system built to survive them without a bigger budget to fall back on.

Business-driven, not academic.None of the axes above — reliability, maintainability, adaptability, resilience — are chosen because they sound better in a systems-design interview than "pick two of three." They're the axes that matter here because this project runs against a rubric borrowed from business, not research: does a design decision drive revenue, reduce risk, save time, or streamline a process? A vertically-scaled, paid Postgres tier doesn't do any of those four things better than the current $0 architecture does — it just spends money to be marginally more elegant, which is optimizing for the wrong thing. It's the same rubric that makes the schema-drift, 402-gate, and CSS-cascade bugs above worth writing up at all: each one cost real time to diagnose, and documenting the fix is what keeps the next incident from costing that same time twice. Technology chosen for its own sake — because it's new, or because a textbook covers it — is research. Technology chosen because it moves one of those four levers is engineering.

The lesson generalizes past any one system: scale is a hypothesis until real users adopt it, and grassroots trust is earned before headroom is spent building for a user count that may never show up. That's why this site treats adoption — a résumé PDF a recruiter actually opens, a chat agent a hiring manager actually trusts enough to ask a follow-up question — as the metric that comes before throughput, not after it.

Benchmark the existing process before automating it, not after. Any operational process improvement that replaces a manually-run workflow with an automated one starts by measuring the process as it already performs — cost, turnaround time, error rate — before a line of automation code exists, so the "after" number has a real "before" to be checked against. Skip that step and the risk isn't just a worse process; it's a process nobody can prove is better, which is the same trust gap the "AI Growth & Adoption" pull-quote above is about, one layer down.

Finance and time are the default success criteria — not the only ones. Cost saved and hours reclaimed map straight onto the business-driven-development rubric above and read clearly to a recruiter or hiring manager without translation. But quality or another qualitative measure is the honest criterion when the task calls for it — the tailored-résumé rubric check described under "What 'agent' means" is graded on whether the output passes, not on how fast it runs, because a faster résumé that fails the rubric is a regression wearing a KPI, not an improvement. Once a metric is picked, the discipline is in what doesn't get measured: instrumenting every available signal "just in case" produces test-fatigue nobody actually looks at, and it invites optimizing for a number the process was never scoped to move — scope creep, chasing a metric outside the original design's intent instead of the one that was actually the point.

The benchmark is also the gate on scale.A process proven against a narrow benchmark hasn't earned the right to run at ten times that scope just because the math says it could — the same grassroots-trust-before-headroom argument the pull-quote above makes about users, applied to the process itself. Rolling automation out past its established benchmark before addressing that hesitation — a team's or a stakeholder's fear of an automated process replacing one they trusted by hand — repeats the exact mistake the pull-quote warns against: capacity spent on scale nobody asked for yet, instead of on earning the trust scale depends on.

Designing for today's problem, not a guessed-at tomorrow. The harder half of applying reliability, maintainability, adaptability, and resilience isn't knowing the four axes exist — it's navigating the ambiguity of which one a given problem actually needs, right now, and building only that much of it. A system over-built for failure modes today's traffic will never hit, or scale today's budget will never reach, isn't more resilient than one sized to what's real — it's slower to ship and harder to reason about, which is its own reliability and maintainability cost. The version that adapts tomorrow is the one built honestly for what's true today, with room left to change, not the one pre-built for a future that was only ever a guess. None of this is really about the code; it's about architecting the system the code has to live inside.

A systems-design interview at Apple raised this directly, through two related prompts in the same conversation. The first: design a system that translates English into another language. The obvious move is to pick a target language and start on the architecture — but the choice of target isn't a neutral technical default. "Chinese" isn't one language or one dialect; picking it without picking which variety, region, and political context it represents is itself a bias decision, made before a single API gets designed.

That gets sharper the moment the system does more than move text around. Text-to-text translation and text-to-voice translation aren't the same problem — voice has to carry dialect and regional accent, which flat text never surfaces. English → Japanese makes it concrete: Kyoto's dialect (Kansai-ben) and Tokyo's standard dialect are differing regional and contextual representations of the same language, not interchangeable defaults. A system that doesn't account for that risks a real mistranslation, not a cosmetic one — and shipping without accounting for that risk is a decision with consequences, not a neutral technical default someone else is responsible for.

The same interview's second prompt was two-way translation — English → Portuguese and Portuguese → English. The design question wasn't the algorithm; it was the launch market. Shipping that service targeted only at Brazil — one Portuguese-speaking market, not Portugal or the rest of the Lusophone world — looks like an ordinary "which market ships first" product call. It isn't just that: it carries geopolitical, historical, and public-relations weight for the company's reputation, far outside anything in the codebase.

The system design doesn't have to change — the engineer's awareness does. Generalized past translation specifically: an engineer can be asked to design a system — "build a translator" — and the system design itself may not need to change at all to account for any of this. What has to change is whether the engineer stays mindful of the real-world business, geopolitical, and reputational realities sitting around that design decision. Skip that awareness and the system still ships, still works, still passes review — and still produces unintended real-world consequences anyway. That awareness is a distinct discipline from the system design itself: business acumen and real-world judgment, layered on top of the technical design, not a substitute for it.

It's the same instinct as Not just what you say — how you say it — know who's actually in the room — taken to its most extreme, highest-stakes version. There, the room is one reader or one interviewer; here, the "room" is an entire user population, and the same audience-first calibration decides whether a design represents their dialect, region, or nationality faithfully, or doesn't.

It also compounds the exact risk the AI Growth & Adoption pull-quote raises about scaling to users who aren't there yet. A translation or localization choice that misrepresents or alienates a dialect, region, or nationality doesn't just ship a worse product — it erodes the grassroots trust adoption actually depends on. It's the same "users afraid of the technology" failure mode, except the fear here is earned by cultural or geopolitical insensitivity baked into a language or market decision, not unfamiliarity with the technology itself.

Flagged: this section is newly-authored synthesis distilling a real, specific interview experience — not a verbatim transcript or quote.

Every explanation on this site — this essay included — assumes a specific reader. Knowing who's actually in the room decides more than word choice: it decides how much can be assumed. A staff engineer doesn't need "GitHub Actions" defined; a non-technical hiring manager doesn't need it left undefined either — they need it translated into what it does ("a free, scheduled job runner") instead of what it's called. Reading the audience first, then picking the vocabulary, is the same discipline as reading a job description before tailoring a résumé to it — the content doesn't change, the framing does.

Chronological — background, scope, reasons, solution — is the default. For a lay or mixed audience, the order that lands is the order a story would use: what problem existed before this (background), how big or specific that problem actually was (scope), why the available options narrowed to this one, introduced only after the business problem is clear (reasons), and only then the built thing itself, backed by a live demonstration (solution). That's deliberately the same order this changelog uses project by project — problem, then what shipped, then what broke, then what was learned — because most readers arriving at any one entry haven't already internalized the context a technical peer would bring.

Reverse-chronological flips it for a technical room. Lead with the real, data-driven demonstration — a chat agent citing a live Postgres number, a résumé PDF that actually renders — and let the audience pull the background out with questions, instead of pushing it at them up front. A picture is a thousand words: a demonstration that actually works communicates the unspoken narrative — the debugging, the trade-offs, the constraint that shaped the design — without spelling any of it out first. A technical audience that watches something work will ask "how," and that question is a better entry point into the architecture than a slide ever is.

The same chronological/reverse-chronological split governs jargon and humor, not just structure. A lay audience gets plain language first and technical vocabulary only once a concept has already landed; a technical audience gets the term up front, because withholding it reads as padding, not clarity. Humor works the same way — save it for after a technical point lands with a technical room, open with it to lower the stakes for a non-technical one. Neither is more "correct" than the other; both are the same audience-first instinct applied to a different lever.

Every choice above — order, jargon, humor, which experience to share — is the same instinct pointed at a different lever: read the room first, then decide how to say the thing that's true anyway.

For a reusable version of this — stakeholder archetypes and a step-by-step framework for navigating any conversation — see Effective Communication.