# cirfmf/ksef-client-csharp architecture

> Architecture diagram of the GitHub repository cirfmf/ksef-client-csharp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cirfmf/ksef-client-csharp
- Repository: https://github.com/cirfmf/ksef-client-csharp

## Overview

##### Project type and purpose
- This is a .NET-based SDK and demonstration suite for interacting with the Polish KSeF electronic invoicing API (REST).
- It consists of:
· A core library (KSeF.Client.Core) defining models, interfaces, and exceptions.
· A client library (KSeF.Client) implementing API-call logic, DI registration, HTTP transport, and cryptography coordination.
· A demo ASP.NET WebApp (KSeF.DemoWebApp) to showcase usage.
· A set of unit, functional, and E2E tests in several test projects.

##### File structure
Top-level directories:
- KSeF.Client.Core: shared models/interfaces/exceptions (.NET Standard 2.0)
- KSeF.Client: main library
· Api/Builders – builder objects for each API endpoint
· Api/Services – service classes (AuthCoordinator, CryptographyService, SignatureService, QrCodeService, VerificationLinkService)
· Clients – low-level HTTP client wrappers (CryptographyClient, KSeFClient, LimitsClient, TestDataClient)
· DI – extension methods & options for Microsoft.Extensions.DependencyInjection
· Http – RestClient, JsonUtil, HTTP-helper extensions
- KSeF.DemoWebApp: ASP.NET controllers and example XAdES certificate services
- KSeF.Client.Tests*, KSeF.Client.Tests.Utils: unit/E2E/integration/spec-style tests
- CertTestApp: console app demo for certificate creation

##### README for insights
- Confirms layered structure and technologies: .NET 8/9, DI, RestClient, builder pattern
- Shows registration snippets for AddKSeFClient and AddCryptographyClient
- Indicates test organization (E2E, unit, utility classes)

##### Main components & their interactions
A. Presentation layer (DemoWebApp)
· Controllers (InvoiceController, AuthController, etc.) inject IKSeFClient, ICryptographyService, etc.
B. Service layer (KSeF.Client.Api.Services)
· Implements business orchestration: builds requests via Builders, calls low-level Clients, handles responses, coordinates crypto.
C. Client transport (KSeF.Client.Clients & Http)
· RestClient wraps HttpClient
· Builders produce RestRequest objects (URL, headers, body)
· Clients send requests, parse JSON, handle errors (ApiException, rate-limit)
D. Core abstractions (KSeF.Client.Core)
· Interfaces define contracts (IKSeFClient, IRestClient, ICryptographyService…)
· Models define all request/response DTOs for: Authorization, Certificates, Invoices, Sessions, Permissions, QRCode, Peppol, Token
· Exceptions capture API and validation errors
E. External systems
· KSeF REST API endpoints (Test, Demo, Production URLs)
· XAdES cryptography (local key store / certificate fetcher)

##### Architectural patterns & principles
- Layered architecture (Presentation → Business Services → Transport → Core)
- Dependency Injection for all services/clients
- Builder pattern for request construction
- Separation of concerns: Models/Interfaces in Core, Implementation in Client
- Async I/O with HttpClient abstraction
- Test pyramid: unit tests, integration/E2E tests, demo app

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Presentation Layer"
        Controllers["DemoWebApp Controllers\n(.NET 8/9, ASP.NET Core)"]:::presentation
        Xades["XAdES Certificate Service Stub"]:::presentation
        Startup["DemoWebApp Startup Config"]:::presentation
    end

    subgraph "Business Services"
        ApiServices["API Services\n(AuthCoordinator, CryptographyService,\nSignatureService, QrCodeService,\nVerificationLinkService, PersonTokenService)"]:::services
    end

    subgraph "Transport Layer"
        Builders["API Builders\n(Builder Pattern)"]:::transport
        ClientsLow["Low-Level HTTP Clients\n(CryptographyClient, KSeFClient,\nLimitsClient, TestDataClient)"]:::transport
        DIExt["Dependency Injection Extensions\n(AddKSeFClient, AddCryptographyClient)"]:::transport
        HttpHelpers["HTTP Transport Helpers\n(RestClient, JsonUtil,\nHttpResponseMessageExtensions)"]:::transport
    end

    subgraph "Core Library"
        Models["Core Models\n(Authorization, Certificates,\nInvoices, Permissions, QRCode,\nSessions, Token)"]:::core
        Interfaces["Core Interfaces\n(IKSeFClient, IRestClient,\nICryptographyService)"]:::core
        Infrastructure["Core Rest Infrastructure\n(RouteBuilder, RestRequest)"]:::core
        Exceptions["Core Exceptions"]:::core
    end

    subgraph "External Systems"
        API["KSeF REST API"]:::external
        CertStore["Certificate Store/\nCrypto Provider"]:::external
    end

    subgraph "Test Suites"
        CertApp["CertTestApp\n(Certificate Demo)"]
        E2E["Core E2E & Functional Tests"]
        TestUtils["Test Utilities"]
        UnitTests["Unit Tests"]
    end

    Controllers -->|"injects/uses"| ApiServices
    ApiServices -->|"builds requests"| Builders
    Builders -->|"calls"| ClientsLow
    ClientsLow -->|"wraps via RestClient"| HttpHelpers
    HttpHelpers -->|HTTP/HTTPS| API
    ApiServices -->|"crypto operations"| ClientsLow
    ClientsLow -->|"fetches certificates"| CertStore

    CertApp -->|"demos cert creation"| API
    E2E -->|"tests API flows"| API
    TestUtils -->|"provides utils"| E2E
    UnitTests -->|"tests core logic"| Models

    click Controllers "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.DemoWebApp/Controllers"
    click Xades "https://github.com/cirfmf/ksef-client-csharp/blob/main/KSeF.DemoWebApp/Services/XadeSDummy.cs"
    click Startup "https://github.com/cirfmf/ksef-client-csharp/blob/main/KSeF.DemoWebApp/Program.cs"
    click ApiServices "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.Client/Api/Services"
    click Builders "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.Client/Api/Builders"
    click ClientsLow "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.Client/Clients"
    click DIExt "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.Client/DI"
    click HttpHelpers "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.Client/Http"
    click Models "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.Client.Core/Models"
    click Interfaces "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.Client.Core/Interfaces"
    click Infrastructure "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.Client.Core/Infrastructure/Rest"
    click Exceptions "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.Client.Core/Exceptions"
    click CertApp "https://github.com/cirfmf/ksef-client-csharp/blob/main/KSeF.Client.Tests.CertTestApp"
    click E2E "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.Client.Tests.Core/E2E"
    click TestUtils "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.Client.Tests.Core/Utils"
    click UnitTests "https://github.com/cirfmf/ksef-client-csharp/tree/main/KSeF.Client.Tests.Core/UnitTests"

    classDef presentation fill:#AED6F1,stroke:#333,stroke-width:1px
    classDef services fill:#A9DFBF,stroke:#333,stroke-width:1px
    classDef transport fill:#F5CBA7,stroke:#333,stroke-width:1px
    classDef core fill:#D7DBDD,stroke:#333,stroke-width:1px
    classDef external fill:#D2B4DE,stroke:#333,stroke-width:1px
    classDef tests fill:#fff,stroke:#333,stroke-dasharray: 5 5,stroke-width:1px
    class Controllers,Xades,Startup presentation
    class ApiServices services
    class Builders,ClientsLow,DIExt,HttpHelpers transport
    class Models,Interfaces,Infrastructure,Exceptions core
    class API,CertStore external
    class CertApp,E2E,TestUtils,UnitTests tests
```
