Architecture Decision Records
Formal records documenting the context, rationale, and trade-offs behind every significant technical decision in this system.
Decision Log
20 recorded decisions
Static Site Generation over Server-Side Rendering
The portfolio site serves content that changes infrequently, work experience, education records, technology stack, and biographical data. The API backing these ...
MongoDB over PostgreSQL for Content API
The portfolio's content model is inherently heterogeneous. Work experiences carry arrays of technologies, nested duty descriptions, and optional media reference...
styled-components over Tailwind CSS
The portfolio requires a theming system that supports runtime switching between dark and light modes without page reload. The design language demands precise co...
Single Accent Color System over Category-Based Palette
The original design assigned unique neon colors to each technology category and content type, 12 distinct hues mapped to categories like Frontend, Backend, DevO...
Decoupled API Architecture
The portfolio's data layer could be co-located with the Next.js frontend using API routes (pages/api/*), which would simplify deployment to a single Vercel proj...
AI agent readability as First-Class Concern
The portfolio exists in an era where content is consumed not only by humans via browsers but increasingly by AI agents, LLMs, and automated systems that parse w...
CSS Grid over Flexbox for Layout System
The original layout system used Flexbox with calc()-based percentage widths for multi-column arrangements. Technology grids used `flex-wrap: wrap` with `width: ...
Static JSON over CMS for Decision Records
Architecture Decision Records are a new content type being added to the portfolio. The existing content model uses a MongoDB-backed API for all data. Adding ADR...
Geist Font Family as Design System Foundation
Typography selection for a portfolio site is a high-leverage decision that affects perceived quality across every page. The previous font stack used system font...
ISR-Ready Architecture with Full Static Fallback
Incremental Static Regeneration (ISR) is a Next.js feature that allows static pages to be revalidated after deployment without a full rebuild. For a portfolio w...
Multi-Layer Structured Data Strategy for Semantic Discoverability
The portfolio's AI agent readability layer established the principle of treating AI agents as first-class consumers (ADR-006). But the implementation of that pr...
Deliberate AI Crawler Access Policy over Default Blocking
The default posture for most websites toward AI crawlers is either passive (no explicit policy, relying on robots.txt default Allow) or hostile (blocking GPTBot...
Zero-Downtime Deploy Strategy with Atomic Rollouts
The portfolio site and its API are deployed independently (ADR-005) with different deployment mechanisms. The frontend deploys to Vercel via git push, which tri...
Defensive Data Fetching with Graceful Degradation
The portfolio's SSG build process (ADR-001) fetches data from the API (api.lucioduran.com) during build time. If the API is unavailable, slow, or returns malfor...
Critical Rendering Path Optimization Strategy
The portfolio's target audience, technical hiring managers and VPs of Engineering, often evaluate sites on mobile devices during commutes or between meetings, o...
Scoped Remote Image Patterns over Generic CDN Proxy
The portfolio displays images from multiple origins: profile photos and social cards from statics.lucioduran.com, dynamic content images from api.lucioduran.com...
Defense-in-Depth HTTP Security Headers
HTTP security headers are the first layer of defense against common web attacks: XSS (Cross-Site Scripting), clickjacking, MIME-type sniffing, and information l...
Monolithic Page Components over Micro-Component Architecture
The portfolio's component architecture faces a fundamental trade-off: should pages be built from small, reusable atomic components (buttons, cards, badges, labe...
Semantic URL Routing with Explicit Path Mapping
Next.js Pages Router uses file-system-based routing: pages/technologies/[id].js creates routes at /technologies/:id. The portfolio has three dynamic route types...
Calibrated Uncertainty as Architectural Metadata
Architecture Decision Records traditionally document three things: the context (why a decision was needed), the decision (what was chosen), and the consequences...