Loading...
Architecture Decision Records
Architecture Decision Records documenting the key technical choices made when building this portfolio — a production Next.js 16 app on Azure. Each ADR captures the context, options evaluated, the decision made, and the real-world outcome.
Click any card to see the full context, options I considered, the decision, rationale, trade-offs, and real-world outcome.
Needed a hosting target for a Next.js 16 standalone Node.js app that integrates with Azure AI Foundry via Managed Identity. The app requires server-side rendering, API routes, and a persistent process (not serverless cold-starts per-request). As a Cloud Solution Architect at Microsoft, choosing Azure was a given — but which Azure service?
Azure App Service zip-deploy works by uploading a zip and letting the process run. The default Next.js build produces a `.next/` folder that still requires a full `node_modules/` (~300MB) at runtime. This made the deploy zip large and slow, and required `npm install` post-deploy or bundling all dependencies.
The portfolio has an admin panel (`/admin`) for managing all content. Only one person (Saurav) needs access. Authentication was required to protect CRUD APIs and prevent public access to the editor.
Starting a new Next.js project in late 2025, Tailwind CSS v4 was available as a release candidate. v4 introduces a CSS-first configuration model using `@theme` in `globals.css`, replacing the JavaScript `tailwind.config.js` file. The choice was to adopt v4 early or stay on the stable v3.
The portfolio needed an AI chatbot grounded on portfolio content, and an AI Writer that can draft blog posts, case studies, and other content types. The choice was between calling the Azure OpenAI chat completions API directly, or using the Azure AI Foundry Agent API which wraps a model with persistent tools.
The chatbot needs to answer questions about Saurav's portfolio content (projects, case studies, blog posts, events, talks). A RAG pipeline was needed to ground the model on real content rather than hallucinating. Options ranged from building a custom embedding + vector database pipeline to using managed services.
The admin panel allows uploading cover images for blog posts, case studies, events, and certifications. These images need to be stored somewhere accessible to both the Next.js app and public visitors. Options were to store them in the git repo, or an external blob store.
The portfolio needed an automated build and deploy pipeline. As a Microsoft employee, Azure DevOps was the obvious enterprise choice. However, the portfolio is on a personal GitHub repository, not an Azure DevOps organization.
The portfolio calls Azure AI Foundry from the App Service backend for chatbot responses and AI Writer generation. Azure services support two authentication patterns: API keys (static secrets stored in environment variables) or Managed Identity (token-based, no secrets).
Monitoring was needed for the portfolio — page views, performance metrics, and exceptions. Azure Application Insights supports both a browser JavaScript SDK and a Node.js server SDK. The choice was which to instrument.
The admin panel has CRUD API routes for 6 content types. Each route receives JSON payloads from the admin UI. Without validation, malformed payloads could cause unhandled exceptions, corrupt content files, or open injection vectors.
Events data (32 speaking engagements) is auto-generated from DOCX source files via `scripts/generate-events.mjs`. The generator produces correct IDs and dates but cannot extract professional summaries, curated highlights, or correct topic tags. Manual corrections were needed, but direct edits to `events.json` would be overwritten on the next generation run.