# nguyenbaohuy/bookworm architecture

> Architecture diagram of the GitHub repository nguyenbaohuy/bookworm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nguyenbaohuy/bookworm
- Repository: https://github.com/nguyenbaohuy/bookworm

## Overview

##### Project Type & Purpose
- The project is a cloud-native application built using .NET Aspire.
- It employs Domain-Driven Design (DDD), Vertical Slice Architecture, and CQRS via MediatR.
- It is organized into multiple bounded contexts (“services”) such as Catalog, Shopping Cart (Basket), Order, Identity, Notification, and Rating.
- It also uses external integrations like RabbitMQ/MassTransit for messaging, gRPC for inter-service communication, and Duende IdentityServer for authentication/authorization.

##### Main Components to be Shown
- Core Application Host (BookWorm.AppHost): This is the overall entry point and orchestrator.
- Bounded Context Services:
- BookWorm.Catalog: Manages book inventory, authors, categories, publishers.
- BookWorm.Basket: Implements the shopping cart functionality.
- BookWorm.Ordering: Handles orders, buyers, and order processing.
- BookWorm.Identity: Manages user registration, login, and profile management.
- BookWorm.Notification: Sends email notifications and integrates with MailDev.
- BookWorm.Rating: Manages feedback and product ratings.
- Gateway Service (BookWorm.Gateway): Acts as an API gateway with rate limiting, serving static assets (wwwroot) and likely routing traffic to the backend services.
- Health Check Hosting (BookWorm.HealthCheck.Hosting): Responsible for health checks and monitoring.
- Supporting/Shared Libraries:
- BookWorm.Core and BookWorm.Shared: Core domain abstractions, shared infrastructure, pipelines (logging, metrics, validation), and DDD building blocks.
- BookWorm.ServiceDefaults: Provides standard configurations (authentication extensions, Swagger/OpenAPI) across services.
- Infrastructure components such as:
- Databases: PostgreSQL (or similar, visible from appsettings and deployment YAML files).
- Cache: Redis (with deployment YAML for caching components).
- Messaging Infrastructure: RabbitMQ (via MassTransit) and event bus for integration events.
- gRPC endpoints between services (e.g., defined in the “Grpc” folders across bounded contexts).
- External Tools:
- Aspirate configurations (YAML files) for Kubernetes deployment.
- Duende IdentityServer for AuthN/AuthZ.
- Tools for CI/CD and testing (even if still to be fully implemented).

##### Relationships & Interactions
- The AppHost initializes or coordinates communications between services.
- The Gateway serves as an entrypoint for clients and routes requests to underlying services.
- Bounded context services communicate via well-defined APIs (HTTP/REST) and/or gRPC for internal interactions.
- Messaging queues and integration events (using RabbitMQ/MassTransit) facilitate asynchronous communication between services.
- Each bounded context exposes endpoints implementing the CQRS pattern (separating command and query responsibilities).
- Shared libraries provide cross-cutting concerns (logging, exception handling with global exception handlers, telemetry, and OpenTelemetry integration).

##### Architectural Patterns and Principles
- Vertical Slice Architecture: Each feature, along with its handlers, commands, queries, validators, etc., is self-contained.
- Domain-Driven Design (DDD): Domain models, aggregates, and repositories are clearly defined (note the “Domain”, “Infrastructure/Data”, and “SeedWork” folders).
- CQRS with MediatR: Segregates command/query responsibilities within each service.
- Event-Driven Architecture (EDA): Integration events are used across bounded contexts, as seen in “IntegrationEvents” directories.
- Microservices or Modular Monolith: Although the codebase is split into projects (Catalog, Basket, etc.), they represent bounded contexts that can scale independently.
- Deployment via Aspirate: YAML configurations indicate container deployments (managed via Docker/k3d).

##### Technology, Frameworks, and Libraries to Highlight
- .NET 8.0 SDK for application development.
- gRPC for inter-service communication.
- RabbitMQ + MassTransit for messaging.
- MediatR for CQRS.
- Duende IdentityServer for authentication/authorization.
- Redis for caching.
- OpenAPI/Swagger for API documentation.
- Docker and Kubernetes (k3d) for deployment.
- GitHub Codespaces integration (visible in the README).
- Unit and Integration testing frameworks (as indicated in tests folders).

##### Specific Elements to be Included
- How databases (Postgres, Redis) and other external dependencies (MailDev, RabbitMQ, gRPC endpoints) integrate into the overall system.
- A section for “Shared Infrastructure” (logging, monitoring, OpenTelemetry, CI/CD tooling).

##### Execution Recommendations
- That each component is clearly labeled and annotated with the technologies it uses (e.g., “BookWorm.Gateway: API Gateway with rate limiting, static file serving”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client & Gateway Layer
    subgraph "Client & Gateway Layer"
        Gateway["BookWorm.Gateway: API Gateway with rate limiting and static file serving"]:::gateway
        AppHost["BookWorm.AppHost: Core Application Host (Orchestrator)"]:::apphost
    end

    %% Bounded Context Services
    subgraph "Bounded Context Services"
        Cat["Catalog Service"]:::service
        Bas["Basket Service"]:::service
        Ord["Ordering Service"]:::service
        Id["Identity Service"]:::service
        Not["Notification Service"]:::service
        Rat["Rating Service"]:::service
    end

    %% Supporting & Shared Libraries
    subgraph "Supporting & Shared Libraries"
        Core["Shared Domain & Infrastructure"]:::shared
        Shared["Shared Cross-Cutting Concerns"]:::shared
        Defaults["Service Defaults (Configuration & Swagger)"]:::shared
    end

    %% Infrastructure & External Dependencies
    subgraph "Infrastructure & External Dependencies"
        DB["PostgreSQL Database"]:::database
        Cache["Redis Cache"]:::database
        Msg["RabbitMQ / MassTransit (Messaging)"]:::external
        Grpc["gRPC Endpoints"]:::external
        IdentityServer["Duende IdentityServer"]:::external
        MailDev["MailDev (Email Testing)"]:::external
    end

    %% Health & Monitoring
    subgraph "Health & Monitoring"
        Health["BookWorm.HealthCheck.Hosting"]:::health
    end

    %% Connections: Gateway Routing to Bounded Contexts
    Gateway -->|"routes_requests"| Cat
    Gateway -->|"routes_requests"| Bas
    Gateway -->|"routes_requests"| Ord
    Gateway -->|"routes_requests"| Id
    Gateway -->|"routes_requests"| Not
    Gateway -->|"routes_requests"| Rat

    %% Connections: AppHost orchestrates services
    AppHost -->|"orchestrates"| Cat
    AppHost -->|"orchestrates"| Bas
    AppHost -->|"orchestrates"| Ord
    AppHost -->|"orchestrates"| Id
    AppHost -->|"orchestrates"| Not
    AppHost -->|"orchestrates"| Rat

    %% Bounded services use Shared Infrastructure
    Cat -->|"uses"| Core
    Cat -->|"uses"| Shared
    Cat -->|"configured_by"| Defaults

    Bas -->|"uses"| Core
    Bas -->|"uses"| Shared
    Bas -->|"configured_by"| Defaults

    Ord -->|"uses"| Core
    Ord -->|"uses"| Shared
    Ord -->|"configured_by"| Defaults

    Id -->|"uses"| Core
    Id -->|"uses"| Shared
    Id -->|"configured_by"| Defaults

    Not -->|"uses"| Core
    Not -->|"uses"| Shared
    Not -->|"configured_by"| Defaults

    Rat -->|"uses"| Core
    Rat -->|"uses"| Shared
    Rat -->|"configured_by"| Defaults

    %% External communications from services
    Not -->|"sends_notifications_to"| MailDev
    Cat -->|"publishes_events_via"| Msg
    Bas -->|"publishes_events_via"| Msg
    Ord -->|"publishes_events_via"| Msg

    %% Inter-service communication via gRPC
    Cat -->|"calls_grpc"| Grpc
    Bas -->|"calls_grpc"| Grpc
    Ord -->|"calls_grpc"| Grpc
    Id -->|"calls_grpc"| Grpc
    Not -->|"calls_grpc"| Grpc
    Rat -->|"calls_grpc"| Grpc

    %% Gateway Authentication via IdentityServer
    Gateway -->|"authenticates_via"| IdentityServer

    %% Health monitoring connections
    AppHost -->|"reports_health_to"| Health
    Health -->|"monitors"| DB
    Health -->|"monitors"| Cache
    Health -->|"monitors"| Msg

    %% Click Events for Components
    click AppHost "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.AppHost"
    click Cat "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.Catalog"
    click Bas "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.Basket"
    click Ord "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.Ordering"
    click Id "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.Identity"
    click Not "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.Notification"
    click Rat "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.Rating"
    click Gateway "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.Gateway"
    click Health "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.HealthCheck.Hosting"
    click MailDev "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.MailDev.Hosting"
    click Core "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.Core"
    click Shared "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.Shared"
    click Defaults "https://github.com/nguyenbaohuy/bookworm/blob/main/src/BookWorm.ServiceDefaults"

    %% Style definitions
    classDef gateway fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef apphost fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef service fill:#d5f5e3,stroke:#28b463,stroke-width:2px;
    classDef shared fill:#f5b7b1,stroke:#cb4335,stroke-width:2px;
    classDef database fill:#f5eef8,stroke:#8e44ad,stroke-width:2px;
    classDef external fill:#fce5cd,stroke:#d35400,stroke-width:2px;
    classDef health fill:#e8daef,stroke:#6c3483,stroke-width:2px;
```
