🚪 47 Doors: The Universal Front Door Support Agent

Eliminate the "47 Front Doors" Problem - A three-agent AI system that provides a single, intelligent entry point for university student support.

---

📖 Overview

The Universal Front Door Support Agent is a three-agent AI system that provides a single, intelligent entry point for all university student support requests. Instead of navigating multiple disconnected support channels, students interact with one interface that:

• 🎯 Detects intent from natural language queries
• 🔀 Routes requests to the correct department
• 🎫 Creates tickets automatically in ServiceNow
• 📚 Retrieves knowledge articles for self-service
• 👤 Escalates to humans for policy-related requests

🎯 Target Impact: Increase first-contact resolution from 40% to 65%

🏗️ Solution Architecture

---

🎓 Hackathon Labs Overview

Build this entire system in 8 hours using GitHub Codespaces! This repository includes a complete hackathon curriculum with 8 progressive labs. All labs run in GitHub Codespaces - no local installation required.

📋 Lab	📝 Title	⏱️ Duration	🔨 What You'll Build
00	🚀 Environment Setup	30 min	Launch GitHub Codespaces, configure CORS, test the chat interface
01	🤖 Understanding AI Agents	90 min	Learn multi-agent vs monolithic architectures, build an intent classifier with >90% accuracy
02	🔌 Azure MCP Setup	30 min	Configure Model Context Protocol for Azure OpenAI and AI Search integration
03	📝 Spec-Driven Development	45 min	Write feature specs and AI constitution before generating code with Claude/Copilot
04	🔍 Build RAG Pipeline	2 hrs	Implement hybrid search (vector + keyword) with Azure AI Search and 54 KB articles
05	🔗 Agent Orchestration	2 hrs	Wire up QueryAgent → RouterAgent → ActionAgent pipeline with session management
06	🚀 Deploy with azd	90 min	Containerize with Docker, deploy to Azure Container Apps with azd up
07	🔌 MCP Server	60 min	(Stretch) Expose your agent as an MCP server for Claude Desktop integration

📈 Learning Path

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  🚀 Lab 00  │     │  🤖 Lab 01  │     │  🔌 Lab 02  │     │  📝 Lab 03  │
│    Setup    │────▶│   Agents    │────▶│     MCP     │────▶│    Specs    │
│   30 min    │     │   90 min    │     │   30 min    │     │   45 min    │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                                                                   │
       ┌───────────────────────────────────────────────────────────┘
       ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  🔍 Lab 04  │     │  🔗 Lab 05  │     │  🚀 Lab 06  │     │  🔌 Lab 07  │
│     RAG     │────▶│  Pipeline   │────▶│   Deploy    │────▶│     MCP     │
│   2 hrs     │     │   2 hrs     │     │   90 min    │     │   60 min    │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

🛠️ Key Skills by Lab

💡 Skill	Lab 00	Lab 01	Lab 02	Lab 03	Lab 04	Lab 05	Lab 06	Lab 07
🐍 Python/FastAPI					●	●	●	●
🤖 Azure OpenAI		●	●		●	●
🔍 Azure AI Search			●		●	●
💬 Prompt Engineering		●		●	●	●
🐳 Docker/Containers							●
☁️ Azure Deployment							●
🔌 MCP Protocol			●					●

☁️ Azure Service Requirements

Labs 00-03 and 06 can run entirely in mock mode without Azure credentials. Labs 04, 05, and 07 require live Azure OpenAI for their core learning objectives.

📋 Requirement	Lab 00	Lab 01	Lab 02	Lab 03	Lab 04	Lab 05	Lab 06	Lab 07
✅ Mock Mode OK	✓	✓	✓	✓			✓
🤖 Azure OpenAI (GPT-4o)					Required	Required		Required
🔍 Azure AI Search					Required	Required

💡 Cost-Saving Tip: Run Labs 00-03 with USE_MOCK_MODE=true to validate your setup before provisioning Azure services. Switch to live Azure OpenAI starting in Lab 04 when you build the RAG pipeline.

📚 Coach Materials: coach-guide/ | 📖 Participant Guide: docs/hackathon/

---

⚡ Quick Start

📋 Prerequisites

• 🐍 Python 3.11+
• 📦 Node.js 18+
• 🐳 Docker (optional)

🌐 Option 1: GitHub Codespaces (Recommended for Quick Testing)

The easiest way to get started is using GitHub Codespaces:

# 🔧 Backend setup
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

# ⚠️ IMPORTANT: Configure CORS for Codespaces
# Edit backend/.env and update CORS_ORIGINS with your Codespaces URLs:
# CORS_ORIGINS=["http://localhost:5173","http://localhost:3000","https://<your-codespace-name>-5173.app.github.dev"]

# 🚀 Start backend (bind to all interfaces for Codespaces)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 🎨 Frontend setup (new terminal)
cd frontend
npm install
cp .env.example .env

# 📝 Update frontend/.env with your backend Codespaces URL:
# VITE_API_BASE_URL=https://<your-codespace-name>-8000.app.github.dev

npm run dev

⚠️ Important Codespaces Configuration:

1. 🔓 Make port 8000 public for external access:

   gh codespace ports visibility 8000:public -c $CODESPACE_NAME

2. 🔗 Get your Codespaces URLs from the Ports tab in VS Code, or construct them:

   • 🎨 Frontend: https://<codespace-name>-5173.app.github.dev
   • 🔧 Backend: https://<codespace-name>-8000.app.github.dev
   • Your codespace name is in the environment variable $CODESPACE_NAME

3. ⚙️ Update CORS configuration in backend/.env:

   CORS_ORIGINS=["http://localhost:5173","http://localhost:3000","https://<your-codespace-name>-5173.app.github.dev"]

   Note: The backend config uses validation_alias to map CORS_ORIGINS from .env to the allowed_origins setting.

4. 🔄 Restart the backend after updating CORS settings to clear the settings cache.

🌐 Service	🔗 URL
🎨 Frontend	https://<codespace>-5173.app.github.dev
🔧 Backend API	https://<codespace>-8000.app.github.dev
📚 API Docs	https://<codespace>-8000.app.github.dev/api/docs
💚 Health Check	https://<codespace>-8000.app.github.dev/api/health

💻 Option 2: Local Development

# 📂 Clone repository
git clone https://github.com/msftsean/hiedcab_frontdoor_agent.git
cd hiedcab_frontdoor_agent

# 🔧 Backend setup
cd backend
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload --port 8000

# 🎨 Frontend setup (new terminal)
cd frontend
npm install
cp .env.example .env
npm run dev

🌐 Service	🔗 URL
🎨 Frontend	http://localhost:5173
🔧 Backend API	http://localhost:8000
📚 API Docs	http://localhost:8000/docs
💚 Health Check	http://localhost:8000/api/health

🐳 Option 3: Docker Compose

docker-compose up --build

🌐 Service	🔗 URL
🎨 Frontend	http://localhost:3000
🔧 Backend	http://localhost:8000

---

🏗️ Architecture

🔄 Three-Agent Conversation Flow

The three-agent system processes each user query through a coordinated pipeline:

1. 🎯 QueryAgent - Classifies intent (financial aid, registration, housing, technical support, general)
2. 🔀 RouterAgent - Searches Azure AI Search for relevant KB articles
3. ⚡ ActionAgent - Generates contextual responses and determines if a support ticket is needed

☁️ Azure Infrastructure

🔧 Service	📝 Purpose
🤖 Azure OpenAI	Intent classification, response generation
📦 Container Apps	Backend API hosting
🌐 Static Web Apps	Frontend hosting
💾 Cosmos DB	Session and audit storage
🔍 AI Search	Knowledge base search
🔐 Key Vault	Secrets management

---

☁️ Azure Deployment

🌍 Supported Regions

Deploy to regions with GPT-4o availability:

🌐 Region	🤖 GPT-4o	🤖 GPT-4o-mini
🇺🇸 East US	✅	✅
🇺🇸 East US 2	✅	✅
🇺🇸 West US 3	✅	✅
🇬🇧 UK South	✅	✅
🇸🇪 Sweden Central	✅	✅

🚀 Deploy with Azure Developer CLI

# 🔐 Login to Azure
azd auth login

# 🏗️ Initialize and deploy
azd init
azd up

💰 Cost Estimates

📊 Scale	👥 Users	💵 Monthly Cost
🧪 Development	1-10	$50-100
🚀 Small Pilot	100-500	$160-305
📈 Medium	500-2,000	$400-700
🏢 Production	2,000-10,000	$1,000-2,500

See Cost Estimation Guide for details.

---

📡 API Reference

🔧 Method	🔗 Endpoint	📝 Description
POST	/api/chat	💬 Submit support query
GET	/api/health	💚 Health check
GET	/api/session/{id}	📋 Get session
DELETE	/api/session/{id}	🗑️ End session

📤 POST /api/chat

📥 Request:

{
  "message": "I forgot my password",
  "session_id": null
}

📤 Response:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "ticket_id": "TKT-IT-20260121-0001",
  "department": "IT",
  "status": "created",
  "message": "I've created a ticket for IT Support...",
  "knowledge_articles": [
    {
      "title": "How to Reset Your Password",
      "url": "https://kb.university.edu/password-reset",
      "relevance_score": 0.94
    }
  ],
  "escalated": false,
  "estimated_response_time": "2 hours"
}

---

🧪 Testing

🔧 Backend

cd backend
source .venv/bin/activate
pytest                           # 🧪 Run all tests
pytest --cov=app --cov-report=html  # 📊 With coverage

🎨 Frontend

cd frontend
npm test          # 🧪 Unit tests
npm run test:e2e  # 🎭 E2E tests

---

📚 Documentation

📄 Document	📝 Description
📋 Feature Spec	Detailed requirements
💾 Data Model	Schema definitions
🗺️ Implementation Plan	Development roadmap
⚙️ Customization Guide	Hands-on customization lab
📦 Sample Customizations	Ready-to-use examples
💰 Cost Estimation	Detailed pricing

---

📁 Project Structure

47doors/
├── 🔧 backend/           # FastAPI Python backend
│   ├── app/
│   │   ├── agents/      # 🤖 QueryAgent, RouterAgent, ActionAgent
│   │   ├── api/         # 📡 REST endpoints
│   │   ├── models/      # 📋 Pydantic schemas
│   │   └── services/    # ☁️ Azure integrations
│   └── tests/
├── 🎨 frontend/          # React TypeScript frontend
│   ├── src/
│   │   ├── components/
│   │   └── services/
│   └── tests/
├── 🎓 labs/              # Hackathon curriculum (8 labs)
│   ├── 00-setup/
│   ├── 01-understanding-agents/
│   ├── 02-azure-mcp-setup/
│   ├── 03-spec-driven-development/
│   ├── 04-build-rag-pipeline/
│   ├── 05-agent-orchestration/
│   ├── 06-deploy-with-azd/
│   └── 07-mcp-server/
├── 👨‍🏫 coach-guide/       # Facilitation materials
├── 📦 shared/            # Common resources (constitution, schemas)
├── 📚 docs/              # Documentation
│   ├── architecture/    # 🏗️ Diagrams
│   ├── customization/
│   ├── deployment/
│   ├── hackathon/       # 📖 Participant guides
│   └── specs/           # 📋 Feature specifications
├── ☁️ infra/             # Azure Bicep templates
├── 🐳 docker-compose.yml
└── 📄 azure.yaml

---

🤝 Contributing

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/amazing-feature)
3. 💾 Commit your changes (git commit -m 'Add amazing feature')
4. 📤 Push to the branch (git push origin feature/amazing-feature)
5. 🔀 Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

📊 Version Matrix

🔧 Component	📋 Required Version	✅ Tested Version
🐍 Python	3.11+	3.11.9
⚡ FastAPI	0.100+	0.109.0
📦 Node.js	18+	20.11.0
⚛️ React	18+	18.2.0
📘 TypeScript	5.0+	5.3.3
🐳 Docker	20.10+	24.0.7
☁️ Azure CLI	2.50+	2.56.0
🚀 azd	1.5+	1.7.0

---

🏗️ Built with Azure AI for Higher Education

📅 Last Updated: 2026-02-04 | 📝 Version: 1.0.0