How this site is built

how this site is built

This portfolio is a small backend, built with the same care I put into production systems. There is no database: every word on the site lives in JSON files under /content. Visitor messages are delivered server-side — emailed to me over SMTP and, where the host has a persistent disk, also appended to a JSON file.

Pages are composed from configuration: content/routes.json maps a URL to a page template, and each template is a list of sections made of typed components. Every file is validated against a strict schema at build time (the build fails on a typo) and again at runtime (a bad edit on the server keeps serving the last known good version).

proxyEvery request gets a request id and a fresh CSP nonce. Only scripts carrying the nonce can run.
routingURL segments are checked against a strict pattern, then matched exactly against routes.json. Anything else is a 404.
content storePath allow-list + containment check, size cap, JSON parse, schema validation, deep-freeze, mtime-keyed cache, in-flight de-duplication, last-known-good fallback.
renderingEach component type in the JSON maps to exactly one React component through an exhaustively typed registry. React escapes all text; links pass an allow-list.
apiOne response envelope, request ids, strong ETags with 304s, rate-limit headers, generic error messages, and logs with PII redacted.

live health

GET /api/health

Overall: ok · rendered server-side at 2026-11-11T18:25:59.408Z · uptime 931s

check	status	detail
content	ok	11 files validated & cached
storage	ok	writable: false (not required: email delivery is configured) · probe 5ms · ENOENT
email	ok	SMTP configured (server-side only)
contact form	ok	accepting messages: true via email
admin api	yes	enabled (bearer token)

GET /api/health · liveness: /api/health?probe=liveness

public api

GET /api/v1

method	path	returns
GET	/api/v1	Index of endpoints and API conventions
GET	/api/v1/content/profile	Identity, summary, avatar config and public contact links
GET	/api/v1/content/experience	Roles, dates, highlights and stack
GET	/api/v1/content/systems	Case studies: problem, design, safeguards, outcome
GET	/api/v1/content/skills	Grouped skills
GET	/api/v1/content/education	Education
GET	/api/v1/content/achievements	Awards and recognition
GET	/api/v1/content/threat-model	Threats considered for this site and how each is mitigated
POST	/api/v1/contact	Store a message (same-origin, signed form token, rate-limited)
GET	/api/v1/admin/messages	Read messages (bearer token; 404 when not configured)

# conditional GET: the second request returns 304 Not Modified
curl -si https://your-project.vercel.app/api/v1/content/experience | grep -i etag
curl -si https://your-project.vercel.app/api/v1/content/experience -H 'If-None-Match: "<etag>"'

# every response carries a request id for log correlation
curl -si https://your-project.vercel.app/api/health -H 'X-Request-Id: my-trace-123456'

threat model

GET /api/v1/content/threat-model

threat	vector	mitigations	code
Cross-site scripting	Script injected through content/config (e.g. a javascript: link) or through a visitor's message.	React escapes all rendered text; the only raw HTML is JSON-LD, serialised with <, >, & and line separators escaped. Every href passes an allow-list: #anchor, /path, https://, mailto:, tel: — javascript:, data: and //host are rejected by the schema. Nonce-based Content-Security-Policy with 'strict-dynamic': injected markup cannot execute script. Visitor messages are never rendered on the site; the admin API returns them as JSON.	`src/server/content/schemas.tssrc/proxy.tssrc/app/layout.tsx`
Cross-site request forgery	Another site makes a visitor's browser POST to the contact endpoint.	Origin must exactly match the configured site URL or the request's own host; Sec-Fetch-Site: cross-site is rejected. Only application/json is accepted, which forces a CORS preflight this app never approves. A signed form token issued by this server is required.	`src/server/security/origin.tssrc/server/http/body.tssrc/server/security/form-token.ts`
Spam and automated submissions	Bots posting the contact form, replaying captured requests, or resubmitting the same message.	Off-screen honeypot field; bots that fill it get a convincing 201 and nothing is stored. HMAC-signed form token enforces a minimum fill time and maximum age, using server time only. Token nonces are single-use (checked inside the write transaction); identical messages within 24h are de-duplicated. Per-client token-bucket rate limit with RateLimit and Retry-After headers.	`src/server/contact/service.tssrc/server/security/form-token.tssrc/server/security/rate-limit.ts`
Admin token brute force	Guessing the bearer token for the admin messages endpoint.	Endpoint returns 404 unless ADMIN_TOKEN (≥ 32 chars) is configured. Constant-time comparison over SHA-256 digests (no length or prefix timing leak). Failed attempts are rate-limited per client, and even a correct token is refused during lockout.	`src/app/api/v1/admin/messages/route.tssrc/server/security/crypto.ts`
Email abuse and credential exposure	Using the contact form to inject email headers, send HTML/phishing content to the owner, spoof senders, or leak SMTP credentials and the owner's address.	SMTP host, credentials and recipient exist only in server environment variables; the browser only ever sees "received" and a reference id. Plain-text body only; name and subject reject newlines before they reach headers, and nodemailer encodes headers as well. The visitor is set as Reply-To, never as From, so nothing is sent pretending to be them. STARTTLS is required on non-TLS ports; TLS 1.2 minimum; file and URL access disabled in the mailer; hard timeouts. Provider errors are logged server-side and never returned; health shows only whether email is configured.	`src/server/contact/mailer.tssrc/server/config/env.tssrc/server/contact/service.ts`
Resource exhaustion (DoS)	Huge bodies, chunked bodies with a lying Content-Length, many source IPs, or filling the disk.	Body size enforced while streaming; the stream is cancelled as soon as the cap is crossed. Checks run cheapest-first: rate limit before reading the body, schema before any I/O. Rate-limit state has a hard key cap with LRU eviction; IPv6 is bucketed per /64. Mailbox has a configurable maximum size; content files have a size cap.	`src/server/http/body.tssrc/server/security/rate-limit.tssrc/server/security/client-ip.ts`
Path traversal	A crafted URL or config value reading files outside /content.	The public API maps collection names through a fixed registry; user input never becomes a path. Template paths must match pages/<slug>.json, and every resolved path is checked to stay inside the content root. URL segments must match [a-z0-9-] before routing.	`src/server/content/paths.tssrc/server/content/manifest.tssrc/server/content/store.ts`
Lost or corrupted data	Concurrent writes, crashes mid-write, or a damaged storage file.	Read-modify-write is serialized through an in-process queue. Temp file (O_EXCL, 0600) → fsync → atomic rename → directory fsync. Data is schema-validated before it is written and when it is read; a corrupt file is quarantined, never deleted.	`src/server/storage/json-file-store.ts`
Broken or unsafe configuration	A typo in JSON content, or a limit set so high it disables protection.	Strict schemas reject unknown keys; the build runs validate:content and fails with every error listed. Abuse limits are configurable only within safe bounds (e.g. contact maxRequests ≤ 20). At runtime, an invalid edit keeps the last known good version live and marks health as degraded.	`scripts/validate-content.tssrc/server/content/integrity.tssrc/server/content/store.ts`
Personal data leakage	Logs, error messages, API responses or stored data revealing visitor or owner details.	IPs are stored only as an HMAC with a derived key; logs redact email, name, message, IP and credentials by key. Errors returned to clients are generic and carry a request id; stack traces stay in server logs (and only outside production). Links marked public: false (e.g. phone) are never rendered or returned by the API. Admin responses are Cache-Control: no-store, private. /api/health never includes the SMTP host, user or recipient address.	`src/server/http/logger.tssrc/server/content/manifest.tssrc/server/http/handler.ts`
Header spoofing and log injection	Forged X-Forwarded-For to dodge rate limits, or a crafted X-Request-Id to inject log lines.	X-Forwarded-For is read from the right, trusting only the configured number of proxy hops. Incoming request ids are accepted only if they match a short safe pattern; otherwise a UUID is generated.	`src/server/security/client-ip.tssrc/server/http/request-id.ts`
Unicode tricks	Bidi overrides, zero-width or control characters hiding content, or newlines used for header injection.	Input is NFC-normalized; control, zero-width and bidi-override characters are stripped before length checks. Single-line fields (name, subject) reject newlines.	`src/server/contact/schema.ts`
Clickjacking and browser-level leaks	Framing the site, or leaking referrers and capabilities.	frame-ancestors 'none' and X-Frame-Options: DENY. Referrer-Policy, Permissions-Policy, COOP/CORP, nosniff and HSTS on every response; X-Powered-By removed.	`next.config.tssrc/proxy.ts`

failure modes considered

A content file is edited into invalid JSON on the serverThe previous valid version keeps being served, the error is logged, and /api/health reports content as degraded until it is fixed.
Invalid content is committednpm run build runs validate:content first; the build fails with every schema and cross-reference error listed.
Two messages are submitted at the same momentWrites are serialized through a queue, so neither read-modify-write can overwrite the other.
The process crashes mid-writeWrites go to a temp file that is fsync'd and atomically renamed; the store is either the old file or the new one, never half of each.
The email provider is down, slow or rejects the loginSending has hard timeouts and a 12s overall budget. If the message was also saved to disk, the visitor still gets a 201 and the failure is logged; if email was the only channel, the visitor gets a generic 503 and can retry the same form — nothing is reported as received unless it was actually delivered.
SMTP settings are incomplete or mistypedEmail is disabled (the site keeps running) and /api/health names the missing or invalid variables — by name only, never by value.
The messages file gets corruptedIt is moved aside with a timestamp (not deleted) and the store starts fresh, so the form keeps working and nothing is lost.
The disk is read-only (e.g. serverless hosting)A writability probe detects it and messages are delivered by email only. If neither email nor storage is available, the form is replaced by a notice instead of accepting messages it cannot deliver.
A visitor double-clicks submit, or the network retriesThe button locks while sending, the form token is single-use, and an identical message within 24h returns the original id instead of a duplicate.
Someone floods the endpoint from many addressesRate-limit state has a hard key cap with LRU eviction, so memory stays bounded; the mailbox also has a size cap.
The secret is missing in productionThe app refuses to invent one (it would break on restart and across instances) and disables the form instead.

known limitations

Single instance by designRate limits, the write queue and the replay guard live in process memory. Several instances (or many serverless invocations) need a shared store such as Redis for these — the interfaces are already isolated for that swap.
Email-only mode is best-effort against replaysWithout a disk, single-use tokens and duplicate detection are tracked in memory per instance, so a replay that lands on a different serverless instance within the token lifetime could send a second email. Signature, fill-time and expiry checks still apply everywhere.
Message history needs a persistent diskOn serverless hosts messages exist only as emails; the admin API lists stored messages only where data/ is on a persistent volume.