Glassbox Overall System

Overview Diagram

The container diagram above shows the high-level decomposition of the BookWorm Store system into its main building blocks and their relationships.

Contained Building Blocks

Name	Responsibility
Application Layer	Contains all business services and API gateway
Infrastructure Layer	Provides cross-cutting concerns like messaging and data persistence
External Systems	Third-party services for authentication and email

Important Interfaces

Interface	Protocol	Description
HTTP REST APIs	HTTPS	Synchronous communication between gateway and services
gRPC	gRPC/HTTP2	High-performance inter-service communication
Event Bus	AMQP	Asynchronous messaging for domain events
Database Connections	TCP	Data persistence layer connections

Building Block Descriptions

Application Layer

Purpose/Responsibility The application layer contains all business services and the API gateway that orchestrates requests. It implements the core business logic of the BookWorm store system.

Interface(s)

• HTTP REST APIs for external client communication
• gRPC for internal service-to-service communication
• Event publishing/subscribing via AMQP

Quality/Performance Characteristics

• High availability through service redundancy
• Horizontal scalability for individual services
• Fault tolerance with circuit breaker patterns
• Performance optimization through caching and async processing

Directory/File Location

• src/Services/ - Contains all microservices
• src/Aspire/BookWorm.AppHost/ - Application orchestration
• src/BuildingBlocks/ - Shared components

API Gateway Proxy

Purpose/Responsibility Custom ASP.NET Core proxy using YARP (Yet Another Reverse Proxy) that serves as the single entry point for frontend applications. Routes requests to appropriate microservices (Chat, Rating, Ordering, Basket, Catalog) and handles Keycloak authentication.

Interface(s)

• HTTPS REST API endpoints for frontend clients (Storefront and Backoffice)
• Keycloak token introspection middleware for JWT validation
• Internal HTTP calls to downstream services
• Service discovery integration with Aspire

Quality/Performance Characteristics

• High throughput with async request processing
• Load balancing to backend services
• CORS policy management for frontend origins
• Circuit breaker for service resilience
• Health check aggregation

Catalog Service

Purpose/Responsibility Manages the product catalog with advanced AI capabilities including vector search, file storage, and AI-powered recommendations. Integrates with Azure Blob Storage, Qdrant vector database, and Azure OpenAI for semantic search and content enrichment.

Interface(s)

• REST API for catalog management
• Azure OpenAI integration (GPT-4o-mini for content, text-embedding-3-large for embeddings)
• Vector embedding services for semantic search via Qdrant
• Azure Blob Storage integration for file management
• Microsoft.Extensions.Caching.Hybrid for L1/L2 caching
• Event publishing for catalog changes

Directory/File Location src/Services/Catalog/

Quality/Performance Characteristics

• AI-powered semantic search with Azure OpenAI embeddings
• Azure Blob Storage for scalable file management
• Hybrid caching (in-memory + Redis) for performance
• Real-time vector index updates
• Event-driven architecture with RabbitMQ

Order Service

Purpose/Responsibility Handles complete order lifecycle management with event-driven architecture. Manages order entities, buyer information, and publishes domain events for order state changes.

Interface(s)

• REST API for order and buyer management
• Event publishing for order lifecycle events
• gRPC integration for external service calls
• Real-time order streaming capabilities

Directory/File Location src/Services/Ordering/

Quality/Performance Characteristics

• Event sourcing for complete audit trail
• CQRS pattern implementation
• PostgreSQL for order persistence
• Real-time notifications via events

Basket Service

Purpose/Responsibility Manages shopping cart functionality with Redis-based storage. Handles basket lifecycle from creation to checkout with event publishing.

Interface(s)

• REST API for basket operations
• gRPC integration for product validation
• Event publishing for basket state changes
• Redis Protocol for data persistence

Directory/File Location src/Services/Basket/

Quality/Performance Characteristics

• Redis-based session storage with TTL
• Real-time cart synchronization
• Event-driven basket state management

Finance Service

Purpose/Responsibility Implements saga orchestration pattern for distributed transaction coordination. Manages order processing workflow with state machine implementation.

Interface(s)

• Saga orchestration for distributed transactions
• State machine queries and status endpoints
• Event-driven coordination with other services
• PostgreSQL for financial records and transaction state

Directory/File Location src/Services/Finance/

Quality/Performance Characteristics

• Saga pattern for distributed transaction management
• State machine for order workflow coordination
• Compensation logic for transaction rollbacks
• Event-driven architecture for service coordination

Rating Service

Purpose/Responsibility Manages product ratings and reviews with event-driven architecture. Handles feedback collection, storage, and aggregation.

Interface(s)

• REST API for rating operations
• Event publishing for rating changes
• PostgreSQL for rating data persistence

Directory/File Location src/Services/Rating/

Quality/Performance Characteristics

• Event-driven rating updates
• PostgreSQL for reliable data storage
• Real-time feedback processing

Chat Service

Purpose/Responsibility Provides AI-powered conversational capabilities using Azure OpenAI (GPT-4o-mini) with Microsoft Agents AI Framework integration. Supports Model Context Protocol (MCP) for tool exposure and A2A Protocol for agent-to-agent communication.

Interface(s)

• REST API for chat operations
• Azure OpenAI integration with GPT-4o-mini model
• Microsoft Semantic Kernel for AI orchestration
• Model Context Protocol (MCP) server integration for tool calls
• A2A Protocol for agent-to-agent communication with Rating service
• Real-time chat capabilities
• Dev UI available at /dev/agent endpoint for agent debugging

Directory/File Location src/Services/Chat/

Quality/Performance Characteristics

• AI-powered conversations with Azure OpenAI GPT-4o-mini
• Microsoft Agents AI Framework for agent orchestration
• MCP integration for standardized tool usage
• A2A Protocol for multi-agent workflows
• Real-time chat processing
• PostgreSQL for chat session persistence

Notification Service

Purpose/Responsibility Handles email notifications with template engine and multiple provider support. Processes events from other services to send transactional emails.

Interface(s)

• Event subscription for notification triggers
• SMTP/API integration with SendGrid
• Template engine for email composition
• Azure Table Storage for notification records

Directory/File Location src/Services/Notification/

Quality/Performance Characteristics

• Reliable email delivery with SendGrid integration
• Template-based email composition
• Event-driven notification processing
• Azure Table Storage for audit trails

Scheduler Service

Purpose/Responsibility Manages scheduled tasks and background jobs across the system. Handles recurring operations like data cleanup and report generation.

Interface(s)

• Internal APIs for job scheduling
• Background job processing
• Health monitoring for scheduled tasks

Directory/File Location src/Services/Scheduler/

Infrastructure Layer

Purpose/Responsibility Provides foundational services including messaging, data persistence, and cross-cutting concerns that support the application layer.

Interface(s)

• Event Bus (AMQP) for asynchronous messaging
• Database connections (TCP) for data persistence
• Monitoring and logging endpoints

Quality/Performance Characteristics

• High availability data storage
• Message durability and ordering
• Distributed caching capabilities
• Comprehensive monitoring and alerting