# skarllot/expressions architecture

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

- Interactive diagram: https://gitdiagram.com/skarllot/expressions
- Repository: https://github.com/skarllot/expressions

## Overview

Based on our analysis of the file tree and README, this project is a modular library called Raiqub.Expressions. Its main purpose is to provide a set of abstractions for building specifications and query strategies using LINQ expressions, which enable flexible querying (reading) and writing on different kinds of database systems. It supports both relational (through Entity Framework Core) and NoSQL/document paradigms (through Marten).

##### Main Components
- Core Library (Expressions): Represent the heart of the library where the common classes, interfaces, and internal mechanisms (such as the Specification pattern and expression utilities) are defined. This includes the core “Expressions” directory and its support classes (e.g., ExpressionTreeExtensions, Specification, etc.).
- Reading Module (Expressions.Reading): This component encapsulates abstractions for querying. It defines query strategies, query sources, and the interfaces for a read session (IDbQuerySession, IDbQuerySessionFactory). Mark this as the module handling all read operations.
- Writing Module (Expressions.Writing): This represents the write-side abstractions, providing interfaces like IDbSession and IDbSessionFactory for write operations.
- Provider-Specific Implementations:
- Entity Framework Core (Expressions.EntityFrameworkCore): This submodule implements sessions and factories using EF Core. Emphasize its role in integrating with a relational database.
- Marten (Expressions.Marten): This submodule implements sessions and factories using the Marten library to support NoSQL/document databases.
- Samples and Documentation: Although not part of the “runtime” architecture, the samples (like Helpdesk.Relational) and docs directories demonstrate how the library is intended to be used and provide integration examples. It’s useful to include an “Example Application” or “Sample Consumer” node to show typical integration.
- Tests: There is a clearly defined test suite (in the tests folder) that covers the different modules. You might include a test component to indicate separation of concerns and quality verification.
- CI/CD & DevOps: Show that the project makes use of GitHub workflows (Workflows directory), configuration files (such as Docker and build configuration like Directory.Build.props), and other DevOps workflows (like mutation testing and dependency reviews). These highlight the maintenance and delivery infrastructure supporting the project.

##### Relationships and Interactions
- That external consumers (services or applications) interact with the library through its abstraction interfaces (IDbQuerySession for reading and IDbSession for writing).

##### Architectural Patterns and Design Principles
- Specification Pattern: Indicate how the library allows consumers to construct business rules in the form of specifications which can be composed.
- Layered Architecture: The separation between core abstractions and provider implementations should be clearly delineated.
- Dependency Injection: Indicate that sessions (query and write sessions) are registered in DI containers. This is shown in the README quickstart sections.
- Extensibility: Since the library supports multiple providers, highlight the abstraction boundary that lets the library be extended (for instance, new providers or query strategies).

##### Relevant Technologies, Frameworks, and Tools
- .NET Standard / .NET 6.0 as the target platforms.
- Entity Framework Core and Marten as key technologies that integrate with the library.
- Optionally, include configuration and build tools (like dotnet tools, GitHub Workflows, Docker) to demonstrate the DevOps practices supporting the project’s lifecycle.

##### Elements
- Clear Labels for Each Component:
- Business Logic and Abstraction Layers (e.g., core, reading, writing)
- Provider-Specific Implementations
- Supporting DevOps/Infrastructure components

##### Keep It Detailed Yet Clear
- Do not shy away from breaking down the project into as many small components as possible. The goal is to reflect every major aspect from specification definition to query execution, provider integration, and even testing/deployment pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Layer"
        CORE["Core Expressions"]:::core
    end

    subgraph "Abstraction Layer"
        READ["Expressions.Reading"]:::abstraction
        WRITE["Expressions.Writing"]:::abstraction
    end

    subgraph "Provider Implementations"
        EF["Entity Framework Core Implementation"]:::provider
        MARTEN["Marten Implementation"]:::provider
    end

    subgraph "External Components"
        SAMPLE["Sample Consumer"]:::external
    end

    subgraph "Supporting"
        DOC["Documentation"]:::infrastructure
        DEVOPS["CI/CD & DevOps"]:::infrastructure
        TESTS["Test Suite"]:::test
    end

    %% Relationships
    READ -->|"depends_on"| CORE
    WRITE -->|"depends_on"| CORE

    EF -->|"plugs_into"| READ
    EF -->|"plugs_into"| WRITE
    MARTEN -->|"plugs_into"| READ
    MARTEN -->|"plugs_into"| WRITE

    SAMPLE -->|"uses"| READ
    SAMPLE -->|"uses"| WRITE

    DOC -->|"guides"| SAMPLE
    DEVOPS -->|"supports"| SAMPLE

    TESTS -->|"validates"| CORE
    TESTS -->|"validates"| READ
    TESTS -->|"validates"| WRITE
    TESTS -->|"validates"| EF
    TESTS -->|"validates"| MARTEN

    %% Click Events
    click CORE "https://github.com/skarllot/expressions/tree/main/src/Expressions"
    click READ "https://github.com/skarllot/expressions/blob/main/src/Expressions.Reading"
    click WRITE "https://github.com/skarllot/expressions/blob/main/src/Expressions.Writing"
    click EF "https://github.com/skarllot/expressions/blob/main/src/Expressions.EntityFrameworkCore"
    click MARTEN "https://github.com/skarllot/expressions/blob/main/src/Expressions.Marten"
    click SAMPLE "https://github.com/skarllot/expressions/blob/main/samples/Helpdesk.Relational"
    click DOC "https://github.com/skarllot/expressions/tree/main/docs"
    click DEVOPS "https://github.com/skarllot/expressions/tree/main/.github/workflows"
    click TESTS "https://github.com/skarllot/expressions/tree/main/tests"

    %% Styles
    classDef core fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef abstraction fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef provider fill:#FFCDD2,stroke:#D32F2F,stroke-width:2px;
    classDef external fill:#E1BEE7,stroke:#7B1FA2,stroke-width:2px;
    classDef infrastructure fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef test fill:#CFD8DC,stroke:#607D8B,stroke-width:2px;
```
