How elzik/breef works
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