README.md

Architecture Documentation

This folder contains the canonical architecture, ADRs, component references, operational playbooks, and diagrams for Holiday Peak Hub — a reference implementation for Agentic Microservices on Microsoft's AI and cloud platform.

Canonical Documents

• Architecture Overview — Primary technical architecture narrative (context, interactions, deployment)
• Architecture Decision Records — Full ADR index and status (35 ADRs)
• Components — Library, app, and frontend component references
• Solution Architecture Diagrams — System context, container, per-domain, and data flow Mermaid diagrams
• MAF Integration Rationale — Why Microsoft Agent Framework is wrapped in holiday-peak-lib
• Standalone Deployment Guide — How to deploy a single agent service to AKS
• Test Coverage Gap Analysis — Coverage gaps, patterns, and wave-based remediation plan
• Architecture Compliance Review — Branch-level ADR and policy conformance assessment
• Event Hub Topology Matrix — Topic-level publisher/subscriber coverage contract and gap tracking
• Operational Playbooks — Incident runbooks aligned to governance policies
• Diagrams — Draw.io C4 diagrams and sequence flow documents
• Business Summary — Executive architecture summary

Agentic Microservices Reference

This repository positions Holiday Peak Hub as a reference for building agentic microservices on Azure. See Agentic Microservices Reference for the full positioning document.

Microsoft Technology Cross-References

Topic	Official Documentation
Microsoft Agent Framework (MAF)	MAF Python SDK
Azure AI Foundry Agents	Foundry Agents overview
Azure AI Search	AI Search overview
Azure Cosmos DB for NoSQL	Cosmos DB data modeling
Azure Kubernetes Service	AKS baseline
Microservices on Azure	Azure Architecture Center
Event-driven architecture	Event-driven patterns
Well-Architected Framework	WAF overview

Governance Alignment

• Governance Overview
• Frontend Governance
• Backend Governance
• Infrastructure Governance

Source of Truth Rules

• Use this folder as architecture source of truth for repo-level design.
• Use components/apps/*.md for service-level implementation details.
• Use ADRs for all non-trivial architecture decisions and updates.
• Keep deployment policy references aligned with deploy-azd-dev.yml, deploy-azd-prod.yml, and reusable deploy-azd.yml.
• Prefer diagrams in diagrams/*.drawio for C4 views and diagrams/sequence-*.md for runtime flows.