# elzik/breef architecture

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

- Interactive diagram: https://gitdiagram.com/elzik/breef
- Repository: https://github.com/elzik/breef

## Overview

##### Project Type and Purpose
- This is a .NET-based backend microservice (“Elzik.Breef.Api”) built using a clean/layered (hexagonal) architecture.
- It exposes HTTP endpoints to generate “breef” summaries of arbitrary web pages and publishes them to Wallabag.
- No internal database; integrations are purely through external services (web pages, AI summariser, Wallabag API).

##### File-Structure Analysis
- Top-level solution (.sln) ties together four main projects under src/:
a. Elzik.Breef.Api (presentation layer / HTTP minimal API)
b. Elzik.Breef.Application (application layer / orchestration)
c. Elzik.Breef.Domain (domain/entities and interfaces)
d. Elzik.Breef.Infrastructure (infrastructure adapters: HTTP scraper, AI, Wallabag)
- build/ contains PowerShell scripts for CI/CD and Docker image builds.
- tests/ contain functional, integration, and unit tests organized by project.
- Dockerfile in src/Elzik.Breef.Api for containerization.
- Configuration via appsettings.json and DI extension methods across projects.

a. Main Components
- Client (e.g., Postman, Web UI)
- API Layer (Elzik.Breef.Api)
– Authentication (API key)
– Minimal HTTP endpoints (BreefEndpointsExtensions)
- Application Layer (Elzik.Breef.Application)
– BreefGenerator (implements IBreefGenerator)
- Domain Layer (Elzik.Breef.Domain)
– Interfaces: IWebPageDownloader, IContentExtractor, IContentSummariser, IBreefPublisher
– Entities: Breef, PublishedBreef
- Infrastructure Layer (Elzik.Breef.Infrastructure)
– WebPageDownloader (scrapes HTML)
– ContentExtractor (extract main article content)
– AiContentSummariser (calls external AI providers via HTTP)
– WallabagBreefPublisher (calls Wallabag API)
- External Services
– Web servers (target URLs)
– AI Service Providers (e.g., OpenAI)
– Wallabag API endpoint

b. Data Flow & Relationships
1. Client → HTTP Request (secured via API key) → API Layer
2. API Layer → calls BreefGenerator (DI-injected) in Application Layer
3. BreefGenerator orchestrates:
- IWebPageDownloader → fetch raw HTML
- IContentExtractor → extract text and metadata
- IContentSummariser → send content to AI provider, receive summary
- IBreefPublisher → push summary to Wallabag
4. Each adapter communicates over HTTP to its external target.
5. API Layer returns PublishedBreef response to client.

c. Architectural Patterns & Principles
- Clean/hexagonal architecture: strict layering and ports/adapters.
- Dependency Injection for loose coupling (seen in Infrastructure/DependencyInjection files).
- Single Responsibility: each component has one clear role.
- Infrastructure implemented as side-effecting adapters; domain logic remains pure.

d. Key Technologies & Frameworks
- .NET 6+ Minimal APIs (Program.cs, endpoint extensions)
- C# 10, System.Text.Json source-gen serializer
- Docker for containerization
- PowerShell scripts for build/test/deploy
- External HTTP calls to AI providers and Wallabag

##### Essential Elements to Capture
- Layer boundaries and names
- Ports (interfaces) vs. adapters (implementations)
- External services as separate nodes
- Authentication filter in the API layer
- Build/deploy pipeline as side note

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client (Postman/Web UI)"]:::external
    subgraph "Docker Container"
        direction TB
        subgraph "API Layer (Elzik.Breef.Api)" 
            direction TB
            API_Program["Program.cs"]:::api
            API_Endpoints["BreefEndpointsExtensions"]:::api
            API_AuthExt["AuthExtensions"]:::api
        end
        subgraph "Application Layer (Elzik.Breef.Application)"
            direction TB
            IBreefGen["IBreefGenerator"]:::app
            BreefGen["BreefGenerator"]:::app
        end
        subgraph "Domain Layer (Elzik.Breef.Domain)"
            direction TB
            IWebDL["IWebPageDownloader"]:::domain
            IContentExt["IContentExtractor"]:::domain
            IContentSum["IContentSummariser"]:::domain
            IBreefPub["IBreefPublisher"]:::domain
            BreefEnt["Breef, PublishedBreef"]:::domain
        end
        subgraph "Infrastructure Layer (Elzik.Breef.Infrastructure)"
            direction TB
            WebDL["WebPageDownloader"]:::infra
            ContentExt["ContentExtractor"]:::infra
            AIContentSum["AiContentSummariser"]:::infra
            WallabagPub["WallabagBreefPublisher"]:::infra
            HttpLog["HttpMessageDebugLoggingHandler"]:::infra
        end
    end

    Client -->|HTTP + API Key| API_Program
    API_Program --> API_AuthExt
    API_AuthExt --> API_Endpoints
    API_Endpoints -->|calls| BreefGen
    BreefGen -->|implements| IBreefGen
    BreefGen -->|calls| IWebDL
    BreefGen -->|calls| IContentExt
    BreefGen -->|calls| IContentSum
    BreefGen -->|calls| IBreefPub

    IWebDL -->|adapter| WebDL
    IContentExt -->|adapter| ContentExt
    IContentSum -->|adapter| AIContentSum
    IBreefPub -->|adapter| WallabagPub

    WebDL -->|HTTP scrape| WebServer["Web Servers"]:::external
    ContentExt -->|process HTML| WebDL
    AIContentSum -->|HTTP| AIService["AI Service Providers"]:::external
    WallabagPub -->|HTTP| WallabagAPI["Wallabag API"]:::external

    API_Endpoints -->|returns PublishedBreef| Client

    %% CI/CD and Docker
    subgraph "CI/CD Pipeline" 
        direction TB
        Restore["restore.ps1"]:::cidc
        Build["build.ps1"]:::cidc
        Test["test.ps1"]:::cidc
        DockerBuild["build-docker.ps1"]:::cidc
    end
    CI[".github/workflows/continuous-delivery.yml"]:::cidc
    CI --> Restore --> Build --> Test --> DockerBuild --> Client

    classDef api fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef app fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef domain fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef infra fill:#ffe5b4,stroke:#333,stroke-width:1px;
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px;
    classDef cidc fill:#e1bee7,stroke:#333,stroke-width:1px;

    click API_Program "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Api/Program.cs"
    click API_Endpoints "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Api/Presentation/BreefEndpointsExtensions.cs"
    click API_AuthExt "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Api/Auth/AuthExtensions.cs"
    click IBreefGen "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Application/IBreefGenerator.cs"
    click BreefGen "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Application/BreefGenerator.cs"
    click IWebDL "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Domain/IWebPageDownloader.cs"
    click IContentExt "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Domain/IContentExtractor.cs"
    click IContentSum "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Domain/IContentSummariser.cs"
    click IBreefPub "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Domain/IBreefPublisher.cs"
    click WebDL "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Infrastructure/WebPageDownloader.cs"
    click ContentExt "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Infrastructure/ContentExtractor.cs"
    click AIContentSum "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Infrastructure/AI/AiContentSummariser.cs"
    click WallabagPub "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Infrastructure/Wallabag/WallabagBreefPublisher.cs"
    click HttpLog "https://github.com/elzik/breef/blob/main/src/Elzik.Breef.Infrastructure/HttpMessageDebugLoggingHandler.cs"
    click Restore "https://github.com/elzik/breef/blob/main/build/api/restore.ps1"
    click Build "https://github.com/elzik/breef/blob/main/build/api/build.ps1"
    click Test "https://github.com/elzik/breef/blob/main/build/api/test.ps1"
    click DockerBuild "https://github.com/elzik/breef/blob/main/build/api/build-docker.ps1"
    click CI "https://github.com/elzik/breef/blob/main/.github/workflows/continuous-delivery.yml"
```
