# serenity-is/serenity architecture

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

- Interactive diagram: https://gitdiagram.com/serenity-is/serenity
- Repository: https://github.com/serenity-is/serenity

## Overview

Serenity is an ASP.NET Core and TypeScript platform for building data-centric business applications. The principal workflow is a user working with a browser grid or form, which sends service requests for entity retrieval or updates backed by database queries. Distinct product branches also cover reports, uploads, authentication/user lookup, and user preferences; the Northwind and BasicSamples trees demonstrate these capabilities. The supplied source excerpts are partial, so links among unsampled application components are limited to the documented service-based architecture and visible module structure.

Main entry points: [`common-features/src/demo.northwind/Modules`](https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.northwind/Modules) (Grids and forms), [`common-features/src/demo.northwind/Modules/Customer/RequestHandlers`](https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.northwind/Modules/Customer/RequestHandlers) (Request handlers), [`src/services/RequestHandlers/Retrieve/RetrieveRequestHandlerBase.cs`](https://github.com/serenity-is/serenity/blob/master/src/services/RequestHandlers/Retrieve/RetrieveRequestHandlerBase.cs) (Retrieve query base), [`common-features/src/demo.northwind/Modules/Customer/CustomerEndpoint.cs`](https://github.com/serenity-is/serenity/blob/master/common-features/src/demo.northwind/Modules/Customer/CustomerEndpoint.cs) (Service endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application UI"]
  node_browser["Grids and forms<br/>[Modules]"]
  node_customer["Customer module<br/>[Customer]"]
  node_orders["Order modules<br/>[Order]"]
  node_products["Product and category<br/>[Product]"]
  node_samples["UI feature samples<br/>[Modules]"]
  node_grid["SleekGrid layout<br/>[layout-engine.ts]"]
end

subgraph group_services["Service layer"]
  node_endpoint["Service endpoints"]
  node_handlers["Request handlers<br/>[RequestHandlers]"]
  node_retrieve["Retrieve query base"]
  node_query["Query helpers"]
  node_preference_service["Preference service"]
end

subgraph group_framework["Framework services"]
  node_reports["Report retrieval"]
  node_auth["User lookup"]
  node_preferences["User preferences"]
end

subgraph group_integrations["Storage and integrations"]
  node_upload["Upload service"]
  node_disk["Disk storage"]
  node_uploadops["Upload operations"]
end

node_user(("Application user"))
node_database[("Application database")]
node_cache[("Two-level cache")]

node_user -->|"uses"| node_browser
node_browser -->|"sends requests"| node_endpoint
node_endpoint -->|"dispatches"| node_handlers
node_handlers -->|"retrieves via"| node_retrieve
node_retrieve -->|"builds queries"| node_query
node_handlers -->|"reads and writes"| node_database
node_retrieve -->|"queries"| node_database
node_browser -->|"renders grids"| node_grid
node_browser -->|"requests reports"| node_reports
node_auth -->|"caches users"| node_cache
node_preferences -->|"calls"| node_preference_service
node_upload -->|"combines storage"| node_disk
node_uploadops -->|"operates on files"| node_upload

click node_browser "https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.northwind/Modules"
click node_customer "https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.northwind/Modules/Customer"
click node_orders "https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.northwind/Modules/Order"
click node_products "https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.northwind/Modules/Product"
click node_samples "https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.basicsamples/Modules"
click node_endpoint "https://github.com/serenity-is/serenity/blob/master/common-features/src/demo.northwind/Modules/Customer/CustomerEndpoint.cs"
click node_handlers "https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.northwind/Modules/Customer/RequestHandlers"
click node_retrieve "https://github.com/serenity-is/serenity/blob/master/src/services/RequestHandlers/Retrieve/RetrieveRequestHandlerBase.cs"
click node_query "https://github.com/serenity-is/serenity/blob/master/src/services/RequestHandlers/Helpers/ServiceQueryHelper.cs"
click node_reports "https://github.com/serenity-is/serenity/blob/master/common-features/src/extensions/Modules/Reporting/Tree/DefaultReportRetrieveHandler.cs"
click node_auth "https://github.com/serenity-is/serenity/blob/master/common-features/src/extensions/Modules/Authorization/BaseUserRetrieveService.cs"
click node_preferences "https://github.com/serenity-is/serenity/blob/master/common-features/src/extensions/Modules/UserPreference/UserPreferenceStorage.ts"
click node_upload "https://github.com/serenity-is/serenity/blob/master/src/web/Upload/DefaultUploadStorage.cs"
click node_disk "https://github.com/serenity-is/serenity/blob/master/src/services/Upload/DiskUploadStorage.cs"
click node_uploadops "https://github.com/serenity-is/serenity/blob/master/src/services/Upload/UploadStorageExtensions.cs"
click node_preference_service "https://github.com/serenity-is/serenity/blob/master/common-features/src/extensions/Modules/UserPreference/UserPreferenceStorage.ts"
click node_grid "https://github.com/serenity-is/serenity/blob/master/packages/sleekgrid/src/layouts/layout-engine.ts"

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_browser,node_customer,node_orders,node_products,node_samples,node_grid,node_user toneBlue
class node_endpoint,node_handlers,node_retrieve,node_query,node_preference_service,node_database,node_cache toneAmber
class node_reports,node_auth,node_preferences toneMint
class node_upload,node_disk,node_uploadops toneRose
```

## Components

### Application UI

- [Grids and forms](https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.northwind/Modules): `common-features/src/demo.northwind/Modules`
- [Customer module](https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.northwind/Modules/Customer): `common-features/src/demo.northwind/Modules/Customer`
- [Order modules](https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.northwind/Modules/Order): `common-features/src/demo.northwind/Modules/Order`
- [Product and category](https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.northwind/Modules/Product): `common-features/src/demo.northwind/Modules/Product`
- [UI feature samples](https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.basicsamples/Modules): `common-features/src/demo.basicsamples/Modules`
- [SleekGrid layout](https://github.com/serenity-is/serenity/blob/master/packages/sleekgrid/src/layouts/layout-engine.ts): `packages/sleekgrid/src/layouts/layout-engine.ts`

### Service layer

- [Service endpoints](https://github.com/serenity-is/serenity/blob/master/common-features/src/demo.northwind/Modules/Customer/CustomerEndpoint.cs): `common-features/src/demo.northwind/Modules/Customer/CustomerEndpoint.cs`
- [Request handlers](https://github.com/serenity-is/serenity/tree/master/common-features/src/demo.northwind/Modules/Customer/RequestHandlers): `common-features/src/demo.northwind/Modules/Customer/RequestHandlers`
- [Retrieve query base](https://github.com/serenity-is/serenity/blob/master/src/services/RequestHandlers/Retrieve/RetrieveRequestHandlerBase.cs): `src/services/RequestHandlers/Retrieve/RetrieveRequestHandlerBase.cs`
- [Query helpers](https://github.com/serenity-is/serenity/blob/master/src/services/RequestHandlers/Helpers/ServiceQueryHelper.cs): `src/services/RequestHandlers/Helpers/ServiceQueryHelper.cs`
- [Preference service](https://github.com/serenity-is/serenity/blob/master/common-features/src/extensions/Modules/UserPreference/UserPreferenceStorage.ts): `common-features/src/extensions/Modules/UserPreference/UserPreferenceStorage.ts`

### Framework services

- [Report retrieval](https://github.com/serenity-is/serenity/blob/master/common-features/src/extensions/Modules/Reporting/Tree/DefaultReportRetrieveHandler.cs): `common-features/src/extensions/Modules/Reporting/Tree/DefaultReportRetrieveHandler.cs`
- [User lookup](https://github.com/serenity-is/serenity/blob/master/common-features/src/extensions/Modules/Authorization/BaseUserRetrieveService.cs): `common-features/src/extensions/Modules/Authorization/BaseUserRetrieveService.cs`
- [User preferences](https://github.com/serenity-is/serenity/blob/master/common-features/src/extensions/Modules/UserPreference/UserPreferenceStorage.ts): `common-features/src/extensions/Modules/UserPreference/UserPreferenceStorage.ts`

### Storage and integrations

- [Upload service](https://github.com/serenity-is/serenity/blob/master/src/web/Upload/DefaultUploadStorage.cs): `src/web/Upload/DefaultUploadStorage.cs`
- [Disk storage](https://github.com/serenity-is/serenity/blob/master/src/services/Upload/DiskUploadStorage.cs): `src/services/Upload/DiskUploadStorage.cs`
- [Upload operations](https://github.com/serenity-is/serenity/blob/master/src/services/Upload/UploadStorageExtensions.cs): `src/services/Upload/UploadStorageExtensions.cs`

### Other components

- **Application user**
- **Application database**
- **Two-level cache**

## Connections

- Application user → Grids and forms: uses
- Grids and forms → Service endpoints: sends requests
- Service endpoints → Request handlers: dispatches
- Request handlers → Retrieve query base: retrieves via
- Retrieve query base → Query helpers: builds queries
- Request handlers → Application database: reads and writes
- Retrieve query base → Application database: queries
- Grids and forms → SleekGrid layout: renders grids
- Grids and forms → Report retrieval: requests reports
- User lookup → Two-level cache: caches users
- User preferences → Preference service: calls
- Upload service → Disk storage: combines storage
- Upload operations → Upload service: operates on files