Felipe Tavares — brain glyph brand mark Felipe Tavares

Engineering

How this site is actually built

This site itself is a proof point: the decisions behind it, the stack it runs on, and a changelog distilled from its real commit history. Not marketing copy about engineering discipline. The discipline itself.

Decisions

Decisions

Six calls that shaped the build

Context, the call made, and what it cost or bought. Rewritten from this repo's own ADRs and design specs.

  • Astro over Next.js

    The site is mostly static, SEO-critical content read by recruiters and peers on commutes, not an app that needs client-side routing state.

    Astro 5 with React islands only where interactivity is real (chat, forms, theme toggle), instead of Next.js.

  • Git-based CMS over a hosted one

    No evidence yet that a plain git-plus-editor workflow can't keep up with actual publishing cadence, before paying for a hosted CMS to solve a problem that might not exist.

    Content lives as git-versioned MDX/JSON, read through one ContentRepository port, edited three equivalent ways — direct file, Claude Code, or a local Keystatic UI.

  • Workers AI first, Anthropic as fallback

    The chatbot needs a model provider, and a paid API as the default breaks the $0/month budget the moment the site gets any real traffic.

    A provider router tries Cloudflare Workers AI first, free and colocated with the rest of the stack, and falls back to Anthropic only if that call errors — never the other way around.

  • Cloudflare's free tier as the ceiling, not a starting point

    Domain already owned; every other cost (hosting, embeddings, rate-limit storage, email) had to fit inside a tier that won't get bumped by a personal site's real traffic, not just look cheap on a demo.

    Pages/Workers for hosting, KV for rate limiting, Vectorize for embeddings, Workers AI for the chatbot — one provider, one free tier, for everything that isn't the domain itself.

  • The hero moved from decorative to data-true

    An early hero concept was a generic animated gradient mesh with an optional pointer-parallax dot grid: motion for its own sake, no connection to what the site is actually about.

    Replaced it with a living-blueprint diagram generated at build time from the real competency matrix — nodes are skill domains weighted by real depth, edges are roles that touched them. Not decorative randomness.

  • A hand-written fetch transport over the MCP SDK's own

    The MCP server's Cloudflare Worker transport needed to implement the protocol's Transport interface, and the SDK ships one, StreamableHTTPServerTransport, for exactly this.

    Traced that class into node_modules and found it's typed and implemented directly against Node's IncomingMessage/ServerResponse, which don't exist in the Workers runtime. Wrote FetchTransport instead: the same interface, implemented directly over the standard Fetch API.

Why this stack

Why this stack

Every piece, one honest reason

No component here is the default choice. Each earned its place against the $0/month constraint.

  • Astro 5

    Islands architecture ships near-zero client JS on static content by default.

  • React (islands only)

    Used only where a component genuinely needs client-side state — chat, forms, toggles.

  • TypeScript, hexagonal ports & adapters

    core stays framework-free; swapping an adapter never touches a page.

  • Tailwind CSS v4

    Token-driven styling; every color and spacing value traces to one CSS custom-property file.

  • Cloudflare Pages + Workers

    Hybrid output: pages prerender to the CDN, /api/* runs as Workers functions.

  • Cloudflare Workers AI + Vectorize

    Free-tier chatbot provider and embedding index, with Anthropic as a config-swappable fallback.

  • Astro content collections (git-based CMS)

    content/ is the CMS — MDX/JSON, versioned in git, edited three equivalent ways.

  • Keystatic

    Local content-editing UI mirroring the same zod schemas Astro's collections already validate.

  • Cloudflare KV

    Rate-limit storage for /api/contact and /api/chat, free tier, no separate database.

  • GSAP, Lenis, OGL (motion stack)

    MIT-licensed; loaded lazily per page so content pages never pay for motion they don't use.

  • Model Context Protocol (packages/mcp)

    Publishes the same content and chatbot to AI agents as typed tools, not scraped HTML.

Changelog

Changelog

Milestones, not commit noise

Distilled from real git history: dated, narrative, no hashes to chase.

Last updated 2026-07-10

  1. 2026-07-10 fix

    Pre-launch polish and voice pass

    Em-dash sweep across all published prose; section spacing unified site-wide via a shared Section.astro scale; hero kinetic type reserves minimum height on mobile to prevent layout jumps; contact copy, credibility framing, and writing subtitle all revised against the voice guide.

  2. 2026-07-10 infra

    PT-BR archived for v1 launch

    All /pt/* routes removed from the build by renaming the directory to _pt/ (Astro ignores underscore-prefixed directories). Files stay versioned; the language switcher is removed. Bilingual v2 restores them once the English content is fully QA'd and stable.

  3. 2026-07-10 content

    Experience content revamp

    All seven roles rewritten from an owner interview: AI/GenAI leadership added across roles, titles corrected (Finance Consultant/Business Architect; Order-to-Cash Solution Lead), PwC location updated to Amsterdam NL, Siemens dual-city display (Lisbon PT + Munich DE).

  4. 2026-07-10 feature

    Chat launcher redesigned as avatar

    The chat entry point changed from a pill button to a 56px circle showing the owner's brand glyph with a green online-status dot — consistent with the brand identity throughout the site.

  5. 2026-07-09 content

    Projects page reframed around delivered value

    Each project card now leads with its north star and concrete outcomes before exposing technical detail. Selfwright and felipetavares-dev entries gain expandable deep-dives.

Earlier milestones (14)
  1. 2026-07-09 feature

    /reading section launches

    A public log of books, articles, and papers, each with the owner's verdict and rationale. Filter chips by type and domain; four verdict levels (foundational / worth your hours / situational / skip unless) with per-entry reasoning.

  2. 2026-07-09 feature

    Galaxy backdrop and brand glyph ship

    A site-wide WebGL galaxy layer lands behind all page content, tuned for both themes: dense glowing stars in dark mode, near-invisible ink specks in light. The owner's raster brain glyph replaces the generated SVG mark throughout — favicon, OG image, and chat launcher.

  3. 2026-07-06 content

    Repo made AI-agent-legible

    AGENTS.md, the architecture map, and a shared voice guide land so any AI coding agent, not just the one that built it, can pick up this repo and follow its own rules.

  4. 2026-07-06 feature

    The MCP server ships

    The site's content and chatbot become callable as typed Model Context Protocol tools — both a local stdio package and a Cloudflare Worker transport, with a layered rate-limit and abuse-prevention shell in front of every tool call.

  5. 2026-07-06 infra

    Cross-engine E2E and CI quality gates land

    A Playwright suite covering Chromium, WebKit, and mobile-WebKit, plus a GitHub Actions workflow running check, test, redaction-gate, and build on every push — no more relying on manual verification before merge.

  6. 2026-07-05 content

    AI-ready surfaces added

    Markdown twins, an llms.txt file, and a JSON Resume endpoint ship — so an AI agent can read this site as cleanly as a human does, without scraping rendered HTML.

  7. 2026-07-05 feature

    Site goes bilingual

    Portuguese routing, i18n foundation, and localized pages ship under /pt/, with English-only content (articles, project deep-dives) clearly marked rather than machine-translated.

  8. 2026-07-05 fix

    Architecture audit closes 13 duplication findings

    A full pass over every content-loading path, locale touchpoint, and formula in the codebase found 13 duplicated or divergent pieces of logic. Most got a single shared implementation; the rest were kept as documented, deliberate exceptions — turned into two ADRs and a permanent test guard against regression.

  9. 2026-07-05 feature

    Accessibility becomes a visible, first-class control

    A floating control center ships — reduce motion, high contrast, larger text — backed by a documented accessibility statement, not just a compliance checkbox in a footer.

  10. 2026-07-05 feature

    The hero rebuilt as a living blueprint

    Replaced an early decorative gradient-mesh concept with a data-true diagram generated from the real competency matrix, then reworked twice more for full graph connectivity and a three-tier renderer.

  11. 2026-07-05 infra

    Redaction gate becomes CI-enforced

    What started as a hand-checked rule — no employer-tied financial figures or headcounts on the public site — became an automated script scanning content, the chat index, and the built site on every commit.

  12. 2026-07-05 feature

    Projects, Writing, and the chatbot land in one push

    Project deep-dives, the writing engine with RSS and publish-kits, and a RAG chatbot with a multi-provider router all ship.

  13. 2026-07-04 feature

    Journey and Dossier ship

    The scroll-driven career narrative and the recruiter-scannable executive dossier land as the first two real content pages.

  14. 2026-07-04 feature

    Site scaffolded on Astro 5

    Design system, layout shell, and Home page stood up from an approved spec — hexagonal core, adapters, and a content-collection CMS from day one, not bolted on later.