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

Purpose/Responsibility Single entry point that routes client requests to appropriate microservices. Handles cross-cutting concerns like authentication, rate limiting, and request/response transformation.

Interface(s)

• HTTPS REST API endpoints for external clients
• Internal HTTP/gRPC calls to downstream services
• Integration with Identity Provider for authentication

Quality/Performance Characteristics

• High throughput with async request processing
• Load balancing to backend services
• Request/response caching
• Circuit breaker for service resilience

Catalog Service

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

Interface(s)

• REST API for catalog management
• Vector embedding services for semantic search
• Azure Blob Storage integration for file management
• AI model integration (Ollama with Gemma 3 and Nomic Embed Text)
• Event publishing for catalog changes

Directory/File Location src/Services/Catalog/

Quality/Performance Characteristics

• AI-powered semantic search with vector embeddings
• Azure Blob Storage for scalable file management
• 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 LLM integration with Model Context Protocol (MCP) support and Ollama model management.

Interface(s)

• REST API for chat operations
• LLM integration with Ollama and Gemma 3 model
• Model Context Protocol (MCP) for tool integration
• Real-time chat capabilities

Directory/File Location src/Services/Chat/

Quality/Performance Characteristics

• AI-powered conversations with Gemma 3 model
• MCP integration for advanced tool usage
• 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