# m31coding/m31.fluentapi architecture

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

- Interactive diagram: https://gitdiagram.com/m31coding/m31.fluentapi
- Repository: https://github.com/m31coding/m31.fluentapi

## Overview

##### Project Type and Purpose
- This is an open‑source .NET library and toolset for automatically generating “fluent” builder APIs at compile time. It leverages Roslyn incremental source generators to inspect your annotated C# classes and emit builder code following the builder pattern (stepwise object construction).
- Key outcomes: consumer projects reference only the attribute library (`M31.FluentApi`), the generator (`M31.FluentApi.Generator`) integrates into the compiler, tests verify both analyzers and generated code, and example/storybook projects demonstrate usage.

##### Top‑Level Components
A. Attribute Library (“M31.FluentApi”)
- Contains all attribute definitions (`FluentApiAttribute`, `FluentMemberAttribute`, etc.)
- Referenced by consumer code, the generator, and storybook/demo apps.
B. Source Generator (“M31.FluentApi.Generator”)
- Implements Roslyn incremental source generation with three sub‑layers:
1. SourceAnalyzers: diagnostics and code fixes for attribute misuse.
2. CodeBuilding: building abstract code models (ICode, CodeBuilder, CodeFile).
3. CodeGeneration: orchestrates CodeBoardActors and CodeBoardElements to transform models into C# source files.
C. Test Suite (“M31.FluentApi.Tests”)
- AnalyzerAndCodeFixes: unit tests for diagnostics and code‑fix providers.
- CodeGeneration: tests that input classes produce correct output `.g.cs` files.
- Components: unit tests for core algorithms (e.g. Tarjan’s SCC).
D. Example and Storybook
- ExampleProject: a console app showing how to annotate POCOs and consume generated APIs.
- M31.FluentApi.Storybook: step‑by‑step code samples in C# guiding new users.
E. Build & CI
- `ci.yml` in `.github/workflows`: compiles all projects, runs tests, ensures generator runs under incremental compilation.
- Helper scripts (`find-generated-files.sh`, `delete-generated-files.sh`) for managing emitted code.

##### Data & Dependency Flows
- Consumer code (ExampleProject or any user project) references the attribute library and includes `[FluentApi]` annotations.
- During compilation MSBuild invokes `M31.FluentApi.Generator` as a Roslyn source generator.
- The generator’s SourceGenerator analyzes syntax trees → creates SymbolInfo → populates a CodeBoard (using CodeBoardActors) → CodeBuilder builds CodeFile representations → generator emits `.g.cs` into the compilation.
- The compiler picks up generated code, compiles both user and generated code into the final assembly.
- Tests drive both the analyzer stage (verifying diagnostics) and the generator stage (verifying emitted code matches expectations).
- Storybook and ExampleProject run as normal console apps, consuming the generated builder classes at runtime.

##### Architectural Patterns and Principles
- Roslyn Incremental Generator: separation of syntax analysis, symbol analysis, and code emission for performance.
- Builder Design Pattern: each generated API is a stepwise builder interface.
- Modularity: generator is split into clear functional areas (analyzers, code building, code generation).
- Test‑Driven Approach: every feature of the generator and analyzer has corresponding unit tests.
- Low coupling: consumer projects need only attribute definitions and get code via the generator automatically.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Layer
    subgraph "Runtime (Demos & Consumer)" 
        direction TB
        EP["ExampleProject"]:::demos
        SB["M31.FluentApi.Storybook"]:::demos
    end

    %% Compile-Time Layer
    subgraph "Compile-Time"
        direction TB
        AL["M31.FluentApi (Attribute Library)"]:::lib
        subgraph "M31.FluentApi.Generator (Roslyn Source Generator)" 
            direction TB
            SA["SourceAnalyzers"]:::generator
            CB["CodeBuilding"]:::generator
            subgraph "CodeGeneration"
                direction TB
                CBA["CodeBoardActors"]:::generator
                CBE["CodeBoardElements"]:::generator
                ORC["CodeGenerator (Orchestrator)"]:::generator
            end
            CM["Commons"]:::generator
            SG["SourceGenerator (Entry Point)"]:::generator
        end
        GC["Generated .g.cs Files"]:::compile
        COMP["C# Compiler"]:::compile
    end

    %% Tests & CI Layer
    subgraph "Tests & CI"
        direction TB
        TS["M31.FluentApi.Tests"]:::tests
        subgraph "Test Suites"
            direction TB
            T1["AnalyzerAndCodeFixes Tests"]:::tests
            T2["CodeGeneration Tests"]:::tests
            T3["Components Tests"]:::tests
        end
        CI["CI Workflow & Scripts"]:::ci
    end

    %% Connections
    EP -->|"references"| AL
    SB -->|"references"| AL
    AL -->|"dependency"| SG
    SG -->|"invokes"| SA
    SA -->|"analyzes"| CB
    CB -->|"builds models"| CBA
    CBA -->|"affects"| CBE
    CBE -->|"feeds"| ORC
    ORC -->|"emits"| GC
    GC -->|"compiled by"| COMP

    TS -->|"tests generator"| SG
    TS -->|"tests analyzers"| SA
    CI -->|"runs build & tests"| COMP

    %% Click Events - Attribute Library
    click AL "https://github.com/m31coding/m31.fluentapi/blob/main/src/M31.FluentApi"
    click AL "https://github.com/m31coding/m31.fluentapi/blob/main/src/M31.FluentApi/M31.FluentApi.csproj"
    click AL "https://github.com/m31coding/m31.fluentapi/tree/main/src/M31.FluentApi/Attributes"

    %% Click Events - Generator
    click SG "https://github.com/m31coding/m31.fluentapi/blob/main/src/M31.FluentApi.Generator/SourceGenerators/SourceGenerator.cs"
    click SA "https://github.com/m31coding/m31.fluentapi/tree/main/src/M31.FluentApi.Generator/SourceAnalyzers"
    click CB "https://github.com/m31coding/m31.fluentapi/tree/main/src/M31.FluentApi.Generator/CodeBuilding"
    click CBA "https://github.com/m31coding/m31.fluentapi/tree/main/src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors"
    click CBE "https://github.com/m31coding/m31.fluentapi/tree/main/src/M31.FluentApi.Generator/CodeGeneration/CodeBoardElements"
    click ORC "https://github.com/m31coding/m31.fluentapi/blob/main/src/M31.FluentApi.Generator/CodeGeneration/CodeGenerator.cs"
    click CM "https://github.com/m31coding/m31.fluentapi/tree/main/src/M31.FluentApi.Generator/Commons"
    click SG "https://github.com/m31coding/m31.fluentapi/blob/main/src/M31.FluentApi.Generator/M31.FluentApi.Generator.csproj"

    %% Click Events - Tests
    click TS "https://github.com/m31coding/m31.fluentapi/blob/main/src/M31.FluentApi.Tests"
    click T1 "https://github.com/m31coding/m31.fluentapi/tree/main/src/M31.FluentApi.Tests/AnalyzerAndCodeFixes"
    click T2 "https://github.com/m31coding/m31.fluentapi/tree/main/src/M31.FluentApi.Tests/CodeGeneration"
    click T3 "https://github.com/m31coding/m31.fluentapi/tree/main/src/M31.FluentApi.Tests/Components"
    click TS "https://github.com/m31coding/m31.fluentapi/blob/main/src/M31.FluentApi.Tests/M31.FluentApi.Tests.csproj"

    %% Click Events - Demos
    click EP "https://github.com/m31coding/m31.fluentapi/tree/main/src/ExampleProject"
    click EP "https://github.com/m31coding/m31.fluentapi/blob/main/src/ExampleProject/ExampleProject.csproj"
    click EP "https://github.com/m31coding/m31.fluentapi/blob/main/src/ExampleProject/Program.cs"
    click SB "https://github.com/m31coding/m31.fluentapi/blob/main/src/M31.FluentApi.Storybook"
    click SB "https://github.com/m31coding/m31.fluentapi/blob/main/src/M31.FluentApi.Storybook/M31.FluentApi.Storybook.csproj"
    click SB "https://github.com/m31coding/m31.fluentapi/blob/main/src/M31.FluentApi.Storybook/Program.cs"

    %% Click Events - CI
    click CI "https://github.com/m31coding/m31.fluentapi/blob/main/.github/workflows/ci.yml"
    click CI "https://github.com/m31coding/m31.fluentapi/blob/main/src/find-generated-files.sh"
    click CI "https://github.com/m31coding/m31.fluentapi/blob/main/src/delete-generated-files.sh"

    %% Styles
    classDef lib fill:#ADD8E6,stroke:#000,color:#000
    classDef generator fill:#90EE90,stroke:#000,color:#000
    classDef tests fill:#FFD580,stroke:#000,color:#000
    classDef demos fill:#DDA0DD,stroke:#000,color:#000
    classDef ci fill:#D3D3D3,stroke:#000,color:#000
    classDef compile fill:#F0F0F0,stroke:#000,color:#000
```
