# michelmichels/bpostsharp architecture

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

- Interactive diagram: https://gitdiagram.com/michelmichels/bpostsharp
- Repository: https://github.com/michelmichels/bpostsharp

## Overview

##### Overall Structure and Components
- Core Component (MichelMichels.BpostSharp): This is where the core interfaces (ICacheBuilder, ICityDataService) and models (such as CityData) are defined.
- Cache Builder Implementations:
- Excel Cache Builder (MichelMichels.BpostSharp.Excel): Implements ICacheBuilder by reading .xls files (relying on an external dependency like NPOI).
- CSV Cache Builder (MichelMichels.BpostSharp.Csv): Implements ICacheBuilder by reading CSV files.
- Web Cache Builder (MichelMichels.BpostSharp.Web): Implements ICacheBuilder by fetching and parsing HTML content online.
- Demo Application (MichelMichels.BpostSharp.Demo): A sample WPF application (using XAML, ViewModels, and Services) showing how to integrate the library.
- Test Suites: There are unit test projects for each implementation (Excel, CSV, Web) that validate the functionality, completeness, and correctness of the service operations (e.g., retrieving Belgian city data).

##### Relationships and Data Flow
- The core service (BelgianCityDataService) depends on an implementation of ICacheBuilder (which is provided by one of the cache builders). This dependency is injected, as seen in the example code.
- The Demo application demonstrates the interaction between the UI, a service layer (ApplicationHostService, MainViewModel), and the core service for querying data.
- Each cache builder is used to “build” or refresh the internal cache based on the input data (Excel/CSV file or web endpoint), after which queries (filtering by postal code or city name) are executed.
- The test projects simulate these interactions with provided resource files to ensure the cache builders behave as expected.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The core functionality (data models and service interfaces) is separated from the cache building implementations.
- Dependency Injection: The service accepts an ICacheBuilder in its constructor, which allows different behaviors (Excel, CSV, Web) to be plugged in.
- Modular Design: Distinct NuGet packages (and project references) for Excel, CSV, and Web facilitate extensibility without overlapping responsibilities.
- Layered Architecture: At the top sits the demo/UI layer (for client interaction); the middle layer contains the service and caching logic; the data layer is abstracted by the cache builders.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer (Demo)
    subgraph "UI Layer (Demo)"
        D1["Demo Application"]:::demo
        D2["ApplicationHostService"]:::demo
        D3["MainViewModel"]:::demo
    end

    %% Core Library
    subgraph "Core Library (MichelMichels.BpostSharp)"
        C1["ICacheBuilder"]:::core
        C2["ICityDataService"]:::core
        C3["BelgianCityDataService"]:::core
        C4["CityData"]:::core
    end

    %% Cache Builders
    subgraph "Cache Builders"
        B1["CsvCacheBuilder"]:::cache
        B2["ExcelCacheBuilder"]:::cache
        B3["WebCacheBuilder"]:::cache
        B4["BpostWebConstants"]:::cache
    end

    %% Test Suites
    subgraph "Test Suites"
        T1["CSV Tests"]:::test
        T2["Excel Tests"]:::test
        T3["Web Tests"]:::test
    end

    %% Connections between Layers and Components
    %% UI Layer interactions
    D1 -->|"calls"| C3
    D1 -->|"comprises"| D2
    D1 -->|"comprises"| D3

    %% Core Layer interactions
    C3 -->|"injects"| C1
    C3 -->|"implements"| C2

    %% Cache Builder Implementation connections (dashed arrows)
    C1 -.->|"impl"| B1
    C1 -.->|"impl"| B2
    C1 -.->|"impl"| B3

    %% Test Suite interactions
    T1 -->|"tests"| B1
    T2 -->|"tests"| B2
    T3 -->|"tests"| B3

    %% Click Events for Core Library
    click C1 "https://github.com/michelmichels/bpostsharp/blob/main/src/MichelMichels.BpostSharp/Services/ICacheBuilder.cs"
    click C2 "https://github.com/michelmichels/bpostsharp/blob/main/src/MichelMichels.BpostSharp/Services/ICityDataService.cs"
    click C3 "https://github.com/michelmichels/bpostsharp/blob/main/src/MichelMichels.BpostSharp/Services/BelgianCityDataService.cs"
    click C4 "https://github.com/michelmichels/bpostsharp/blob/main/src/MichelMichels.BpostSharp/Models/CityData.cs"

    %% Click Events for Cache Builders
    click B1 "https://github.com/michelmichels/bpostsharp/blob/main/src/MichelMichels.BpostSharp.Csv/CsvCacheBuilder.cs"
    click B2 "https://github.com/michelmichels/bpostsharp/blob/main/src/MichelMichels.BpostSharp.Excel/ExcelCacheBuilder.cs"
    click B3 "https://github.com/michelmichels/bpostsharp/blob/main/src/MichelMichels.BpostSharp.Web/WebCacheBuilder.cs"
    click B4 "https://github.com/michelmichels/bpostsharp/blob/main/src/MichelMichels.BpostSharp.Web/BpostWebConstants.cs"

    %% Click Events for Demo Application
    click D1 "https://github.com/michelmichels/bpostsharp/blob/main/src/MichelMichels.BpostSharp.Demo"
    click D2 "https://github.com/michelmichels/bpostsharp/blob/main/src/MichelMichels.BpostSharp.Demo/Services/ApplicationHostService.cs"
    click D3 "https://github.com/michelmichels/bpostsharp/blob/main/src/MichelMichels.BpostSharp.Demo/ViewModels/MainViewModel.cs"

    %% Click Events for Test Suites
    click T1 "https://github.com/michelmichels/bpostsharp/blob/main/tests/MichelMichels.BpostSharp.CsvTests"
    click T2 "https://github.com/michelmichels/bpostsharp/blob/main/tests/MichelMichels.BpostSharp.ExcelTests"
    click T3 "https://github.com/michelmichels/bpostsharp/blob/main/tests/MichelMichels.BpostSharp.WebTests"

    %% Styles
    classDef core fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef cache fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef demo fill:#ffa500,stroke:#000,stroke-width:2px;
    classDef test fill:#ffff99,stroke:#000,stroke-width:2px;
```
