# zxd60/jsonapidotnetcore1 architecture

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

- Interactive diagram: https://gitdiagram.com/zxd60/jsonapidotnetcore1
- Repository: https://github.com/zxd60/jsonapidotnetcore1

## Overview

##### Project type and purpose
- This is a .NET Core framework/library (JsonApiDotNetCore) for quickly building JSON:API–compliant REST APIs on top of ASP-NET Core and Entity Framework Core.

##### File-structure analysis
- Top-level directories
– src/JsonApiDotNetCore: the core library code divided into submodules (Configuration, Middleware, Controllers, Queries, Serialization, Resources, Services, Repositories, AtomicOperations).
– src/JsonApiDotNetCore.Annotations: attribute-based resource definitions and code-generation hooks.
– src/Examples: sample applications showing typical usage patterns (EF Core, Dapper, multi-tenant, No-EF, etc.).
– docs: static site content, markdown guidance and example HTTP scripts.
– test: extensive integration and unit tests for every module and extension point.
- Configuration files & build scripts
– Directory.Build.props, package-versions.props, CI workflows, PowerShell scripts for bootstrapping Postgres and building.

##### Architecture and data-flow overview
1. ASP-NET Core Web Host
2. JsonApi middleware pipeline (UseRouting → UseJsonApi)
3. Controllers (BaseJsonApiController, JsonApiController, JsonApiOperationsController)
4. Resource Graph & Configuration (built at startup by ResourceGraphBuilder, JsonApiOptions)
5. Service layer (JsonApiResourceService implementing IResourceQueryService, IResourceCommandService)
6. Repository layer (EntityFrameworkCoreRepository or custom repository)
7. EF Core DbContext(s) (AppDbContext)
8. Physical database (PostgreSQL, SQL Server, etc.)
9. Serialization/Deserialization adapters (JsonConverters, IRequest/IResponse adapters)
10. Atomic Operations pipeline (IOperationsProcessor → Processors → TransactionFactory)

b. Relationships & interactions
- HTTP request enters Web Host → passes through JsonApiMiddleware → routed to a JsonApiController
- Controller uses injected ResourceGraph to locate the correct ResourceDefinition and Service(s)
- Service orchestrates business logic, applying filters/pagination via QueryLayerComposer, then calls into the Repository
- Repository resolves a DbContext instance via IDbContextResolver, issues EF Core LINQ or raw SQL, and returns domain entities
- Service wraps entities into Identifiable wrappers, tracks changes, and returns to Controller
- Controller invokes the JSON:API writer (JsonApiWriter) to render the response
- In atomic operations: a JSON:API operations payload is parsed by JsonApiReader → routed to OperationsProcessor → individual processors (create, update, delete, set relationship) → persisted in a transaction
- On startup: Program.cs registers services via builder.Services.AddJsonApi<AppDbContext>(), triggering scanning of assemblies and building of the ResourceGraph

c. Architectural patterns & principles
- Layered/Clean/Onion architecture with a clear separation of concerns
- Dependency Injection as the primary extensibility mechanism
- Repository pattern + Unit of Work (EF Core DbContext)
- Pipeline pattern for middleware and atomic-operations processing
- Convention over configuration with attribute-based resource definitions
- Open/Closed principle: most modules are extensibility points (IResourceDefinition, IQueryLayerComposer, IResourceService, etc.)

d. Key technologies & frameworks
- ASP-NET Core (Middleware, Controllers, DI)
- Entity Framework Core (DbContext, LINQ, Migrations)
- C# Attributes & Reflection (Resource annotations, assembly scanning)
- JSON:API v1.0 specification

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Web Host & Middleware
    subgraph "Web Host & Middleware"
        WebHost["ASP-NET Core Web Host"]:::webHost
        Middleware["JsonApiMiddleware\n(UseRouting → UseJsonApi)"]:::middleware
    end
    WebHost -->|"HTTP Request"| Middleware

    %% Controllers Layer
    subgraph "Controllers"
        BaseController["BaseJsonApiController"]:::controller
        ApiController["JsonApiController"]:::controller
        OpsController["JsonApiOperationsController"]:::controller
    end
    Middleware -->|routes to| BaseController
    Middleware -->|routes to| ApiController
    Middleware -->|routes to| OpsController

    %% Resource Graph & Configuration
    subgraph "Resource Graph & Configuration"
        Options["JsonApiOptions"]:::config
        GraphBuilder["ResourceGraphBuilder"]:::config
    end
    BaseController -->|uses| GraphBuilder
    BaseController -->|uses| Options
    ApiController -->|uses| GraphBuilder
    ApiController -->|uses| Options
    OpsController -->|uses| GraphBuilder
    OpsController -->|uses| Options

    %% Service Layer
    subgraph "Service Layer"
        ResourceService["JsonApiResourceService"]:::service
        QuerySvc["IResourceQueryService"]:::service
        CommandSvc["IResourceCommandService"]:::service
    end
    ApiController -->|calls| ResourceService
    BaseController -->|calls| ResourceService
    OpsController -->|calls| ResourceService
    ResourceService -->|implements| QuerySvc
    ResourceService -->|implements| CommandSvc

    %% Repository Layer & DbContext
    subgraph "Repository Layer & DbContext"
        Repo["EntityFrameworkCoreRepository"]:::repository
        DbResolver["IDbContextResolver"]:::repository
        DbResolverImpl["DbContextResolver"]:::repository
        AppDb["AppDbContext"]:::dbcontext
    end
    ResourceService -->|uses| Repo
    Repo -->|resolves via| DbResolver
    Repo -->|resolves via| DbResolverImpl
    DbResolver -->|provides| AppDb
    DbResolverImpl -->|provides| AppDb

    %% Physical Database
    Database["PostgreSQL / SQL Server"]:::database
    AppDb -->|executes SQL| Database

    %% Serialization & Deserialization
    subgraph "Serialization / Deserialization"
        Reader["JsonApiReader"]:::serialization
        Writer["JsonApiWriter"]:::serialization
        Converter["ResourceObjectConverter"]:::serialization
    end
    BaseController -->|reads payload via| Reader
    OpsController -->|reads payload via| Reader
    ApiController -->|writes response via| Writer
    Converter -->|used by| Reader
    Converter -->|used by| Writer
    Writer -->|sends JSON| Client["Client"]:::external
    Client -->|sends HTTP| WebHost

    %% Atomic Operations Pipeline
    subgraph "Atomic Operations Pipeline"
        IOps["IOperationsProcessor"]:::atomic
        OpsProc["OperationsProcessor"]:::atomic
        TxFactory["EntityFrameworkCoreTransactionFactory"]:::atomic
    end
    Reader -->|parses operations| OpsProc
    OpsProc -->|implements| IOps
    OpsProc -->|uses| TxFactory
    TxFactory -->|wraps| Repo
    OpsProc -->|calls| Repo
    OpsProc -->|commits to| Database

    %% Click Events
    click WebHost "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/Examples/JsonApiDotNetCoreExample/Program.cs"
    click Middleware "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Middleware/JsonApiMiddleware.cs"
    click BaseController "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Controllers/BaseJsonApiController.cs"
    click ApiController "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Controllers/JsonApiController.cs"
    click OpsController "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Controllers/JsonApiOperationsController.cs"
    click Options "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Configuration/JsonApiOptions.cs"
    click GraphBuilder "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Configuration/ResourceGraphBuilder.cs"
    click ResourceService "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Services/JsonApiResourceService.cs"
    click QuerySvc "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Services/IResourceQueryService.cs"
    click CommandSvc "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Services/IResourceCommandService.cs"
    click Repo "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Repositories/EntityFrameworkCoreRepository.cs"
    click DbResolver "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Repositories/IDbContextResolver.cs"
    click DbResolverImpl "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Repositories/DbContextResolver.cs"
    click AppDb "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/Examples/GettingStarted/Data/SampleDbContext.cs"
    click Reader "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Serialization/Request/JsonApiReader.cs"
    click Writer "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Serialization/Response/JsonApiWriter.cs"
    click Converter "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/Serialization/JsonConverters/ResourceObjectConverter.cs"
    click OpsProc "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/AtomicOperations/OperationsProcessor.cs"
    click IOps "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/AtomicOperations/IOperationsProcessor.cs"
    click TxFactory "https://github.com/zxd60/jsonapidotnetcore1/blob/master/src/JsonApiDotNetCore/AtomicOperations/EntityFrameworkCoreTransactionFactory.cs"

    %% Styles
    classDef webHost fill:#e0f7fa,stroke:#006064,color:#004d40;
    classDef middleware fill:#e0f2f1,stroke:#004d40,color:#00695c;
    classDef controller fill:#fff3e0,stroke:#e65100,color:#bf360c;
    classDef service fill:#fff9c4,stroke:#f9a825,color:#f57f17;
    classDef repository fill:#ede7f6,stroke:#5e35b1,color:#311b92;
    classDef dbcontext fill:#e8eaf6,stroke:#3949ab,color:#1a237e;
    classDef database fill:#efebe9,stroke:#6d4c41,color:#3e2723;
    classDef serialization fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20;
    classDef atomic fill:#f1f8e9,stroke:#afb42b,color:#827717;
    classDef external fill:#ffffff,stroke:#000000,color:#000000;
```
