AKS Architect AI

An AI advisor for designing Azure Kubernetes clusters. It blends official Well-Architected best practices and Microsoft docs with guidance personalized to your requirements. I aimed to digitize the version of me that only Microsoft's enterprise clients had access to.

Problem

Microsoft's official guidance is thorough, technically correct, and comprehensive by design. It has to be: it's written for enterprise clients in regulated, compliance-heavy industries. But comprehensive isn't the same as applicable. Many teams work with resource constraints and limited budgets, and need the parts that fit their situation, not the full catalog.

Closing that gap was my job. As a customer engineer, I tailored those best practices to where each customer actually was, against the constraints they were working with. That kind of help has usually come with an enterprise relationship. Plenty of teams never get it.

A chatbot over those same docs doesn't close the gap so much as widen it, answering faster but with the same generic, unpersonalized guidance. I wanted to build the tailoring in, not hand people a quicker version of advice that was never written for their reality.

Solution

The app is a digital version of the way I worked with my customers. It takes your requirements and decisions, grounds its guidance in curated Microsoft docs, and scores your design against the Well-Architected Framework (WAF), whether you answer in a form or in conversation.

RAG pipeline, retrieval API, and chat UI. Full data-flow diagrams are in the repo.

Features

• Personalized, not one-size-fits-all. Your requirements and decisions shape the guidance, so a lean startup and a regulated enterprise get different answers.
• Form or chat, same result. Make a decision in a form, or let the assistant propose one in conversation and save it through an LLM tool call. Both write to the same design.
• Grounded, cited answers. Responses use RAG over official Microsoft docs and cite the exact source chunks with inline [n] references, so nothing is taken on faith.
• Well-Architected scoring. Each design is scored across the five WAF pillars against a baseline set by your requirements, so a gap like security falling short shows at a glance.

The Design Framework

The piece I cared most about is how the knowledge is modeled. Every requirement and decision is structured markdown with YAML frontmatter, and that one source of truth drives the form UI, the retrieval tags, and the framework the LLM reasons over. As an architect I think in relationships, not database rows, so keeping domain knowledge as structured content, separate from the application code, let me work the way I always have.

How It Works

A small monorepo: a Nuxt 4 frontend and a Python FastAPI retrieval service over Postgres with pgvector.

• Retrieval reformulates each question for specificity (using chat history to resolve references), then re-ranks results with human-curated source priorities, so an authoritative reference architecture surfaces even when it isn't the closest vector match.
• Context engineering assembles the system prompt at runtime from modular knowledge sections plus the live design state, filtered to only the relevant domains to stay within token limits.

This is a three-week prototype: the WAF scoring weights were set by judgment and tuned until they read as directionally right, not derived from research.

Reference

• Source on GitHub: full architecture, data-flow diagrams, and per-component READMEs.
• Capstone for the ByteByteAI Engineering Bootcamp, built in three weeks (March 2026).
• Open source and currently runs locally (docker-compose, GitHub login); no hosted demo yet.
• Grounded in official Microsoft docs, but not official Microsoft guidance. Always verify recommendations against the source.

Screenshots