<!-- Canonical: https://lucioduran.com/decisions
Language: en
Content-SHA256: 70b055c19548271fb2af34aaf400606fc851bd98d5a44645657cfedb054d10be
-->

# 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

- [ADR-001accepted

  ### 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 ...

  April 12, 2024](<https://lucioduran.com/decisions/ssg-over-ssr>)
- [ADR-002accepted

  ### 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...

  February 8, 2024](<https://lucioduran.com/decisions/mongodb-over-postgresql>)
- [ADR-003accepted

  ### 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...

  May 3, 2024](<https://lucioduran.com/decisions/styled-components-over-tailwind>)
- [ADR-004accepted

  ### 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...

  December 20, 2025](<https://lucioduran.com/decisions/single-accent-color-system>)
- [ADR-005accepted

  ### 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...

  January 15, 2024](<https://lucioduran.com/decisions/decoupled-api-architecture>)
- [ADR-006accepted

  ### 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...

  February 10, 2026](<https://lucioduran.com/decisions/agent-experience-first-class>)
- [ADR-007accepted

  ### 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: ...

  December 22, 2025](<https://lucioduran.com/decisions/css-grid-over-flexbox>)
- [ADR-008accepted

  ### 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...

  February 15, 2026](<https://lucioduran.com/decisions/static-json-over-cms>)
- [ADR-009accepted

  ### 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...

  November 28, 2025](<https://lucioduran.com/decisions/geist-font-system>)
- [ADR-010accepted

  ### 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...

  June 18, 2024](<https://lucioduran.com/decisions/isr-ready-architecture>)
- [ADR-011accepted

  ### 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...

  February 11, 2026](<https://lucioduran.com/decisions/multi-layer-structured-data>)
- [ADR-012accepted

  ### 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...

  February 12, 2026](<https://lucioduran.com/decisions/deliberate-ai-crawler-access-policy>)
- [ADR-013accepted

  ### 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...

  March 10, 2024](<https://lucioduran.com/decisions/zero-downtime-deploy-strategy>)
- [ADR-014accepted

  ### 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...

  April 28, 2024](<https://lucioduran.com/decisions/defensive-data-fetching>)
- [ADR-015accepted

  ### 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...

  July 15, 2024](<https://lucioduran.com/decisions/critical-rendering-path-optimization>)
- [ADR-016accepted

  ### 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...

  May 20, 2024](<https://lucioduran.com/decisions/scoped-remote-image-patterns>)
- [ADR-017accepted

  ### 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...

  March 25, 2024](<https://lucioduran.com/decisions/defense-in-depth-security-headers>)
- [ADR-018accepted

  ### 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...

  June 2, 2024](<https://lucioduran.com/decisions/monolithic-page-components>)
- [ADR-019accepted

  ### 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...

  May 15, 2024](<https://lucioduran.com/decisions/semantic-url-routing>)
- [ADR-020accepted

  ### 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...

  February 16, 2026](<https://lucioduran.com/decisions/calibrated-uncertainty-metadata>)
