How this site is observed
This page is meant to stay accurate, not aspirational — it's updated as each piece actually ships, not before.
Production architecture
How a commit becomes a live page, end to end.
Local Development
Code is written, tested, and built locally before anything ships.
YOUR MACHINEGitHub
Every commit is pushed to a public, version-controlled repository.
SOURCE OF TRUTHCloudflare Pages
Builds the static export and deploys it to production automatically.
CI/CD • DEPLOYCloudflare Edge
Static assets are cached and served from Cloudflare's global network.
GLOBAL DELIVERYCloudflare DNS
Resolves aldhairmartinez.com to the nearest edge location.
DNS → PAGESVisitor
The site loads over HTTPS on desktop and mobile alike.
WEB & MOBILEPipeline
Current status of each stage in the long-term telemetry architecture.
Browser
liveNext.js / TypeScript / React, statically exported
Grafana Faro
liveFrontend instrumentation SDK, connected in dev and production
FastAPI backend
live — localOpenTelemetry-instrumented (FastAPI + httpx auto-instrumentation), running in Docker Desktop
Grafana Alloy
live — localLocal OTLP relay — receives backend traces, exports to Grafana Cloud. Running in Docker Desktop
PostgreSQL
live — localContact history, resume/project analytics, deployment history — running in Docker Desktop, queries appear as spans in the same traces
Redis / Kafka
plannedCaching and async/event processing — not needed yet, added when a real use case exists
Grafana Cloud
liveTempo / Application Observability — receives Faro and Alloy-relayed backend traces, correlated via W3C trace context
Implemented today
The site itself is statically exported and served from Cloudflare Pages' CDN.
The Grafana Faro Web SDK, in components/analytics/FaroInit.tsx, is connected to a real Grafana Cloud Frontend Observability collector — live in both local development and production, gated behind NEXT_PUBLIC_FARO_URL. Errors, Web Vitals, and session data are collected at 100% sampling for V1. Session Replay isn't enabled yet.
A FastAPI backend (backend/), instrumented with OpenTelemetry (FastAPI + httpx auto-instrumentation), running locally in Docker Desktop — not yet hosted in production.
Grafana Alloy, also running locally in Docker Desktop, relays the backend's traces over OTLP to Grafana Cloud Tempo / Application Observability.
Browser-to-backend distributed trace correlation: Faro attaches a W3C trace context header to the contact form's request, and FastAPI continues that same trace rather than starting a new one — a contact form submission produces one continuous trace across both.
The contact form sends real email through Resend to hello@aldhairmartinez.com, via the same local FastAPI backend.
PostgreSQL, running locally alongside the backend, persists contact submissions, resume-download and project-view analytics, and deployment history — plain psycopg with a connection pool, no ORM. Every query appears as its own span in the same traces as the request that triggered it. See the data layer below.
Data layer
Read live from the local PostgreSQL database — empty or absent entirely in production, same as everything else backend-dependent on this page.
Planned
- Enable Grafana Faro Session Replay once it's available on this stack.
- Redis — next/later, only once there's a real caching, performance, or shared-state need.
- Kafka — later, only once there's a real asynchronous/event-processing need.
- AWS — future production phase: move FastAPI, Alloy, and PostgreSQL into real production infrastructure. Also brings GitHub Actions deployment recording, production secrets management, a real production backend URL, and production frontend → backend connectivity.
- Google Workspace — future: turn hello@aldhairmartinez.com from a forwarding address into a full mailbox.
- Add synthetic monitoring for availability and deployment health.
- Add k6 load testing against the FastAPI backend.
Why build it this way
Most portfolio sites either skip observability entirely or fake it with a screenshot of someone else's dashboard. Neither is interesting. This page exists so the site's own telemetry story is something a visitor — or another engineer — can actually verify against the code, not just take on faith. No credentials or collector endpoints are hardcoded anywhere in this repository; everything above is configured through environment variables, and this page will be updated as each stage moves from planned to real.