Architecture Documentation
This document provides a comprehensive overview of the DotnetGraphQL service architecture, covering every concept, layer, and data flow using Mermaid diagrams.
Table of Contents
- High-Level Architecture
- Request Lifecycle
- Project Structure
- Entity Relationship Model
- GraphQL Schema
- Dependency Injection & Service Registration
- Query Resolver Flow
- Mutation Resolver Flow
- Hot Chocolate Middleware Pipeline
- Data Access Layer
- Application Startup Sequence
- Testing Architecture
- Technology Stack
- GraphQL Operations Reference
High-Level Architecture
The service follows a layered architecture where HTTP requests enter through the ASP.NET Core pipeline, are routed to the Hot Chocolate GraphQL engine, resolved by query/mutation classes, and served data through Entity Framework Core.
Request Lifecycle
Every GraphQL request follows a deterministic pipeline from raw HTTP to JSON response.
Project Structure
The solution is organized into two projects: the API and the test suite.
Entity Relationship Model
The domain model consists of two entities with a one-to-many relationship.
Seed Data
The database is pre-populated with the following data on startup:
GraphQL Schema
The complete schema exposed by the Hot Chocolate engine.
Dependency Injection & Service Registration
All services are registered in Program.cs via the .NET DI container.
Query Resolver Flow
Detailed flow for each query operation showing how Hot Chocolate attributes modify the IQueryable pipeline.
Mutation Resolver Flow
Each mutation performs a write operation and returns the affected entity.
Hot Chocolate Middleware Pipeline
Hot Chocolate processes each GraphQL request through a series of middleware components.
Hot Chocolate Data Attributes Explained
Data Access Layer
How Entity Framework Core manages the data lifecycle with the in-memory provider.
Application Startup Sequence
The exact sequence of operations when the application starts.
Testing Architecture
The test project uses ASP.NET Core's WebApplicationFactory to spin up an in-memory test server.
Test Execution Flow
Technology Stack
All libraries, frameworks, and tools used in the project.
GraphQL Operations Reference
Queries
| Operation | Arguments | Returns | Attributes |
|---|---|---|---|
books | where, order (auto-generated) | [Book!]! | [UseProjection] [UseFiltering] [UseSorting] |
bookById | id: Int! | Book (nullable) | None |
authors | where, order (auto-generated) | [Author!]! | [UseProjection] [UseFiltering] [UseSorting] |
authorById | id: Int! | Author (nullable) | None |
Mutations
| Operation | Arguments | Returns | Description |
|---|---|---|---|
addBook | title: String!, genre: String, publishedYear: Int!, authorId: Int! | Book! | Creates a new book |
addAuthor | name: String!, bio: String | Author! | Creates a new author |
updateBook | id: Int!, title: String, genre: String, publishedYear: Int | Book | Updates book fields (null = no change) |
deleteBook | id: Int! | Boolean! | Deletes a book, returns success status |
Key Concepts
| Concept | Implementation | Purpose |
|---|---|---|
| [Service] Attribute | [Service] AppDbContext context | Injects a scoped service from DI into a resolver method |
| ObjectType<T> | BookType : ObjectType<Book> | Configures how a C# class maps to a GraphQL type with descriptions |
| IQueryable Return | GetBooks() returns IQueryable<Book> | Enables deferred execution so Hot Chocolate middleware can modify the query before it hits the database |
| Navigation Properties | Book.Author, Author.Books | EF Core relationships loaded via .Include() for GraphQL nested field resolution |
| Seed Data | HasData() in OnModelCreating | Pre-populates the in-memory database on EnsureCreated() |
| WebApplicationFactory | IClassFixture<WebApplicationFactory<Program>> | Spins up the full app pipeline in-memory for integration testing |