# foxminchan/bookworm architecture

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

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

## Overview

BookWorm is a cloud-native bookstore application with a customer storefront, administrative backoffice, and domain services for catalog, basket, ordering, ratings, chat, and scheduling. The main customer workflow is browsing and filtering books, selecting a book, managing a basket, and completing checkout; the README documents these product capabilities but the sampled sources do not show the complete API or service call chain. The architecture also includes Keycloak authentication, AI-agent capabilities, and shared service infrastructure. Dashed edges indicate relationships not verified by the supplied excerpts.

Main entry points: [`src/Clients/apps/storefront`](https://github.com/foxminchan/bookworm/tree/main/src/Clients/apps/storefront) (Storefront), [`src/Services/Catalog/BookWorm.Catalog`](https://github.com/foxminchan/bookworm/tree/main/src/Services/Catalog/BookWorm.Catalog) (Catalog service), [`src/Clients/apps/backoffice`](https://github.com/foxminchan/bookworm/tree/main/src/Clients/apps/backoffice) (Admin backoffice), [`src/Aspire/BookWorm.AppHost/AppHost.cs`](https://github.com/foxminchan/bookworm/blob/main/src/Aspire/BookWorm.AppHost/AppHost.cs) (Aspire application host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client applications"]
  node_storefront["Storefront"]
  node_shop["Book browsing"]
  node_bookdetail["Book details"]
  node_basketui["Basket and checkout"]
  node_accountui["Customer orders"]
  node_backoffice["Admin backoffice"]
end

subgraph group_commerce["Commerce services"]
  node_catalog["Catalog service<br/>[BookWorm.Catalog]"]
  node_ingestion["Catalog ingestion"]
  node_basket["Basket service<br/>[BookWorm.Basket]"]
  node_ordering["Ordering service<br/>[BookWorm.Ordering]"]
  node_rating["Rating service<br/>[BookWorm.Rating]"]
  node_catalogdb[("Catalog database")]
end

subgraph group_ai["AI services"]
  node_chat["Chat agents"]
  node_copilot["Storefront AI entry<br/>[route.ts]"]
end

subgraph group_platform["Platform and identity"]
  node_scheduler["Scheduler<br/>[Program.cs]"]
  node_keycloak["Keycloak identity<br/>[keycloak]"]
  node_apphost["Aspire application host<br/>[AppHost.cs]"]
end

subgraph group_shared["Shared infrastructure"]
  node_chassis["Service chassis<br/>[BookWorm.Chassis]"]
  node_tokenexchange["Token exchange<br/>[TokenExchange.cs]"]
  node_specification["Query specifications<br/>[Specification.cs]"]
end

node_customer(("Customer"))

node_customer -->|"shops books"| node_storefront
node_storefront -->|"browses"| node_shop
node_shop -.->|"opens books"| node_bookdetail
node_bookdetail -.->|"adds to basket"| node_basketui
node_basketui -.->|"checks out"| node_accountui
node_customer -->|"administers"| node_backoffice
node_backoffice -.->|"manages catalog"| node_catalog
node_backoffice -.->|"manages orders"| node_ordering
node_backoffice -.->|"manages reviews"| node_rating
node_ingestion -.->|"ingests catalog"| node_catalog
node_catalog -->|"reads and writes"| node_catalogdb
node_storefront -.->|"uses basket"| node_basket
node_storefront -.->|"places orders"| node_ordering
node_storefront -.->|"uses ratings"| node_rating
node_customer -.->|"asks questions"| node_copilot
node_copilot -.->|"routes requests"| node_chat
node_chat -.->|"specialist agent"| node_rating
node_apphost -.->|"orchestrates services"| node_catalog
node_apphost -.->|"orchestrates services"| node_ordering
node_apphost -.->|"configures identity"| node_keycloak
node_storefront -.->|"authenticates"| node_keycloak
node_chassis -->|"provides security"| node_tokenexchange
node_tokenexchange -->|"exchanges tokens"| node_keycloak
node_catalog -->|"queries with"| node_specification

click node_storefront "https://github.com/foxminchan/bookworm/tree/main/src/Clients/apps/storefront"
click node_shop "https://github.com/foxminchan/bookworm/blob/main/src/Clients/apps/storefront/features/catalog/shop/shop-page-client.tsx"
click node_bookdetail "https://github.com/foxminchan/bookworm/blob/main/src/Clients/apps/storefront/features/catalog/product/book-detail-page-client.tsx"
click node_basketui "https://github.com/foxminchan/bookworm/tree/main/src/Clients/apps/storefront/app/(basket)"
click node_accountui "https://github.com/foxminchan/bookworm/tree/main/src/Clients/apps/storefront/app/(ordering)"
click node_backoffice "https://github.com/foxminchan/bookworm/tree/main/src/Clients/apps/backoffice"
click node_catalog "https://github.com/foxminchan/bookworm/tree/main/src/Services/Catalog/BookWorm.Catalog"
click node_ingestion "https://github.com/foxminchan/bookworm/tree/main/src/Services/Catalog/BookWorm.Catalog.Ingestion"
click node_basket "https://github.com/foxminchan/bookworm/tree/main/src/Services/Basket/BookWorm.Basket"
click node_ordering "https://github.com/foxminchan/bookworm/tree/main/src/Services/Ordering/BookWorm.Ordering"
click node_rating "https://github.com/foxminchan/bookworm/tree/main/src/Services/Rating/BookWorm.Rating"
click node_chat "https://github.com/foxminchan/bookworm/blob/main/src/Services/Chat/BookWorm.Chat/Agents/Routing/RouterAgentDefinition.cs"
click node_copilot "https://github.com/foxminchan/bookworm/blob/main/src/Clients/apps/storefront/app/api/copilotkit/route.ts"
click node_scheduler "https://github.com/foxminchan/bookworm/blob/main/src/Services/Scheduler/BookWorm.Scheduler/Program.cs"
click node_keycloak "https://github.com/foxminchan/bookworm/tree/main/src/Aspire/BookWorm.AppHost/Container/keycloak"
click node_apphost "https://github.com/foxminchan/bookworm/blob/main/src/Aspire/BookWorm.AppHost/AppHost.cs"
click node_chassis "https://github.com/foxminchan/bookworm/tree/main/src/BuildingBlocks/BookWorm.Chassis"
click node_tokenexchange "https://github.com/foxminchan/bookworm/blob/main/src/BuildingBlocks/BookWorm.Chassis/Security/TokenExchange/TokenExchange.cs"
click node_specification "https://github.com/foxminchan/bookworm/blob/main/src/BuildingBlocks/BookWorm.Chassis/Specification/Specification.cs"
click node_catalogdb "https://github.com/foxminchan/bookworm/blob/main/src/Services/Catalog/BookWorm.Catalog/Infrastructure/Repositories/AuthorRepository.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_storefront,node_shop,node_bookdetail,node_basketui,node_accountui,node_backoffice toneBlue
class node_catalog,node_ingestion,node_basket,node_ordering,node_rating,node_catalogdb toneAmber
class node_chat,node_copilot toneMint
class node_scheduler,node_keycloak,node_apphost toneRose
class node_chassis,node_tokenexchange,node_specification,node_customer toneIndigo
```

## Components

### Client applications

- [Storefront](https://github.com/foxminchan/bookworm/tree/main/src/Clients/apps/storefront): `src/Clients/apps/storefront`
- [Book browsing](https://github.com/foxminchan/bookworm/blob/main/src/Clients/apps/storefront/features/catalog/shop/shop-page-client.tsx): `src/Clients/apps/storefront/features/catalog/shop/shop-page-client.tsx`
- [Book details](https://github.com/foxminchan/bookworm/blob/main/src/Clients/apps/storefront/features/catalog/product/book-detail-page-client.tsx): `src/Clients/apps/storefront/features/catalog/product/book-detail-page-client.tsx`
- [Basket and checkout](https://github.com/foxminchan/bookworm/tree/main/src/Clients/apps/storefront/app/(basket)): `src/Clients/apps/storefront/app/(basket)`
- [Customer orders](https://github.com/foxminchan/bookworm/tree/main/src/Clients/apps/storefront/app/(ordering)): `src/Clients/apps/storefront/app/(ordering)`
- [Admin backoffice](https://github.com/foxminchan/bookworm/tree/main/src/Clients/apps/backoffice): `src/Clients/apps/backoffice`

### Commerce services

- [Catalog service](https://github.com/foxminchan/bookworm/tree/main/src/Services/Catalog/BookWorm.Catalog): `src/Services/Catalog/BookWorm.Catalog`
- [Catalog ingestion](https://github.com/foxminchan/bookworm/tree/main/src/Services/Catalog/BookWorm.Catalog.Ingestion): `src/Services/Catalog/BookWorm.Catalog.Ingestion`
- [Basket service](https://github.com/foxminchan/bookworm/tree/main/src/Services/Basket/BookWorm.Basket): `src/Services/Basket/BookWorm.Basket`
- [Ordering service](https://github.com/foxminchan/bookworm/tree/main/src/Services/Ordering/BookWorm.Ordering): `src/Services/Ordering/BookWorm.Ordering`
- [Rating service](https://github.com/foxminchan/bookworm/tree/main/src/Services/Rating/BookWorm.Rating): `src/Services/Rating/BookWorm.Rating`
- [Catalog database](https://github.com/foxminchan/bookworm/blob/main/src/Services/Catalog/BookWorm.Catalog/Infrastructure/Repositories/AuthorRepository.cs): `src/Services/Catalog/BookWorm.Catalog/Infrastructure/Repositories/AuthorRepository.cs`

### AI services

- [Chat agents](https://github.com/foxminchan/bookworm/blob/main/src/Services/Chat/BookWorm.Chat/Agents/Routing/RouterAgentDefinition.cs): `src/Services/Chat/BookWorm.Chat/Agents/Routing/RouterAgentDefinition.cs`
- [Storefront AI entry](https://github.com/foxminchan/bookworm/blob/main/src/Clients/apps/storefront/app/api/copilotkit/route.ts): `src/Clients/apps/storefront/app/api/copilotkit/route.ts`

### Platform and identity

- [Scheduler](https://github.com/foxminchan/bookworm/blob/main/src/Services/Scheduler/BookWorm.Scheduler/Program.cs): `src/Services/Scheduler/BookWorm.Scheduler/Program.cs`
- [Keycloak identity](https://github.com/foxminchan/bookworm/tree/main/src/Aspire/BookWorm.AppHost/Container/keycloak): `src/Aspire/BookWorm.AppHost/Container/keycloak`
- [Aspire application host](https://github.com/foxminchan/bookworm/blob/main/src/Aspire/BookWorm.AppHost/AppHost.cs): `src/Aspire/BookWorm.AppHost/AppHost.cs`

### Shared infrastructure

- [Service chassis](https://github.com/foxminchan/bookworm/tree/main/src/BuildingBlocks/BookWorm.Chassis): `src/BuildingBlocks/BookWorm.Chassis`
- [Token exchange](https://github.com/foxminchan/bookworm/blob/main/src/BuildingBlocks/BookWorm.Chassis/Security/TokenExchange/TokenExchange.cs): `src/BuildingBlocks/BookWorm.Chassis/Security/TokenExchange/TokenExchange.cs`
- [Query specifications](https://github.com/foxminchan/bookworm/blob/main/src/BuildingBlocks/BookWorm.Chassis/Specification/Specification.cs): `src/BuildingBlocks/BookWorm.Chassis/Specification/Specification.cs`

### Other components

- **Customer**

## Connections

- Customer → Storefront: shops books (evidence: `README.md`)
- Storefront → Book browsing: browses (evidence: `src/Clients/apps/storefront/features/catalog/shop/shop-page-client.tsx`)
- Book browsing → Book details: opens books
- Book details → Basket and checkout: adds to basket
- Basket and checkout → Customer orders: checks out
- Customer → Admin backoffice: administers (evidence: `README.md`)
- Admin backoffice → Catalog service: manages catalog
- Admin backoffice → Ordering service: manages orders
- Admin backoffice → Rating service: manages reviews
- Catalog ingestion → Catalog service: ingests catalog
- Catalog service → Catalog database: reads and writes (evidence: `src/Services/Catalog/BookWorm.Catalog/Infrastructure/Repositories/AuthorRepository.cs`)
- Storefront → Basket service: uses basket
- Storefront → Ordering service: places orders
- Storefront → Rating service: uses ratings
- Customer → Storefront AI entry: asks questions
- Storefront AI entry → Chat agents: routes requests
- Chat agents → Rating service: specialist agent
- Aspire application host → Catalog service: orchestrates services
- Aspire application host → Ordering service: orchestrates services
- Aspire application host → Keycloak identity: configures identity
- Storefront → Keycloak identity: authenticates
- Service chassis → Token exchange: provides security (evidence: `src/BuildingBlocks/BookWorm.Chassis/Security/TokenExchange/TokenExchange.cs`)
- Token exchange → Keycloak identity: exchanges tokens (evidence: `src/BuildingBlocks/BookWorm.Chassis/Security/TokenExchange/TokenExchange.cs`)
- Catalog service → Query specifications: queries with (evidence: `src/Services/Catalog/BookWorm.Catalog/Infrastructure/Repositories/AuthorRepository.cs`)
