# odygrd/quill architecture

> Architecture diagram of the GitHub repository odygrd/quill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/odygrd/quill
- Repository: https://github.com/odygrd/quill

## Overview

##### Main Components Overview
The system should be divided into two primary components:

a) Frontend (Caller Thread):
- Logger Management
- Queue Management
- Metadata Handling
- Type-safe Formatting Interface

b) Backend (Worker Thread):
- Message Processing
- Sink Management
- Formatting Engine
- File/Console Output

##### Key Architectural Elements

a) Core Components:
**Frontend Layer:**
- Logger Interface
- SPSC Queue (Bounded/Unbounded)
- Metadata System
- Type Codec System

**Backend Layer:**
- Backend Worker
- Sink Manager
- Pattern Formatter
- Transit Event System

b) Sink Types:
- Console Sink
- File Sink
- Rotating File Sink
- JSON Sink
- Custom Sinks

**Top Layer (User Interface):**
**[Logging Macros] --> [Logger Interface]**

**Middle Layer (Frontend):**
**[Logger Manager] <--> [Queue System]**
**[Metadata Store] --> [Type Codec]**

**Bottom Layer (Backend):**
**[Backend Worker] --> [Sink Manager]**
**[Format Engine] <--> [Output Sinks]**

##### Important Relationships

a) Data Flow:
**Log Call -> Metadata Creation -> Queue Insertion -> Backend Processing -> Sink Output**

b) Component Interactions:
- Frontend/Backend communication via SPSC queues
- Logger/Sink management relationships
- Formatting pipeline flow

##### Special Features to Highlight

a) Performance Features:
- Lock-free queues
- Static metadata
- Compile-time optimizations
- RDTSC clock support

b) Architectural Features:
- Asynchronous processing
- Multiple sink support
- Custom formatter support
- Signal handler integration

##### Implementation Details

Following critical paths:
**Hot Path:**
**[LOG_Macro] -> [Static Metadata] -> [SPSC Queue] -> [Backend Worker]**

**Sink Path:**
**[Backend Worker] -> [Formatter] -> [Multiple Sinks]**

**Configuration Path:**
**[Frontend Config] -> [Logger Manager] -> [Sink Manager]**

##### Additional Notes

- Timing indicators for critical paths
- Queue boundaries and buffer limits
- Thread boundaries clearly
- Compile-time vs. runtime components

- Ultra-low latency design
- Asynchronous processing
- Type-safe interface
- Flexible sink system

Remember to maintain a balance between detail and clarity, focusing on the architectural elements that contribute to Quill's performance and flexibility.

This design accurately represents Quill's architecture while highlighting its unique features and performance characteristics.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style Definitions
    classDef frontend fill:#a8d1f0,stroke:#000
    classDef backend fill:#90EE90,stroke:#000
    classDef sink fill:#FFA07A,stroke:#000
    classDef queue fill:#FFE4B5,stroke:#000
    classDef critical fill:#FFB6C1,stroke:#000

    %% Frontend Layer
    subgraph Frontend
        LogMacros["Logging Macros"]
        FrontendInterface["Frontend Interface"]:::frontend
        LoggerInterface["Logger Interface"]:::frontend
        LoggerManager["Logger Manager"]:::frontend
        MetadataStore["Metadata System"]:::frontend
        TypeCodec["Type Codec System"]:::frontend
        QueueSystem["SPSC Queue System"]:::queue
    end

    %% Backend Layer
    subgraph Backend
        BackendInterface["Backend Interface"]:::backend
        BackendWorker["Backend Worker"]:::backend
        SinkManager["Sink Manager"]:::backend
        FormatEngine["Pattern Formatter"]:::backend
        TransitSystem["Transit Event System"]:::backend
    end

    %% Sink Layer
    subgraph Sinks
        ConsoleSink["Console Sink"]:::sink
        FileSink["File Sink"]:::sink
        RotatingFileSink["Rotating File Sink"]:::sink
        JsonSink["JSON Sink"]:::sink
    end

    %% Relationships
    LogMacros --> FrontendInterface
    FrontendInterface --> LoggerInterface
    LoggerInterface --> LoggerManager
    LoggerManager --> MetadataStore
    MetadataStore --> TypeCodec
    TypeCodec --> QueueSystem
    QueueSystem --> BackendInterface
    BackendInterface --> BackendWorker
    BackendWorker --> TransitSystem
    TransitSystem --> SinkManager
    SinkManager --> FormatEngine
    FormatEngine --> ConsoleSink
    FormatEngine --> FileSink
    FormatEngine --> RotatingFileSink
    FormatEngine --> JsonSink

    %% Click Events
    click LoggerInterface "https://github.com/odygrd/quill/blob/master/include/quill/Logger.h"
    click QueueSystem "https://github.com/odygrd/quill/blob/master/include/quill/core/BoundedSPSCQueue.h"
    click MetadataStore "https://github.com/odygrd/quill/blob/master/include/quill/core/MacroMetadata.h"
    click TypeCodec "https://github.com/odygrd/quill/blob/master/include/quill/TriviallyCopyableCodec.h"
    click BackendWorker "https://github.com/odygrd/quill/blob/master/include/quill/backend/BackendWorker.h"
    click SinkManager "https://github.com/odygrd/quill/blob/master/include/quill/core/SinkManager.h"
    click FormatEngine "https://github.com/odygrd/quill/blob/master/include/quill/backend/PatternFormatter.h"
    click TransitSystem "https://github.com/odygrd/quill/blob/master/include/quill/backend/TransitEvent.h"
    click ConsoleSink "https://github.com/odygrd/quill/blob/master/include/quill/sinks/ConsoleSink.h"
    click FileSink "https://github.com/odygrd/quill/blob/master/include/quill/sinks/FileSink.h"
    click RotatingFileSink "https://github.com/odygrd/quill/blob/master/include/quill/sinks/RotatingFileSink.h"
    click JsonSink "https://github.com/odygrd/quill/blob/master/include/quill/sinks/JsonConsoleSink.h"
    click LoggerManager "https://github.com/odygrd/quill/blob/master/include/quill/core/LoggerManager.h"
    click FrontendInterface "https://github.com/odygrd/quill/blob/master/include/quill/Frontend.h"
    click BackendInterface "https://github.com/odygrd/quill/blob/master/include/quill/Backend.h"

    %% Legend
    subgraph Legend
        Frontend_L["Frontend Component"]:::frontend
        Backend_L["Backend Component"]:::backend
        Queue_L["Queue System"]:::queue
        Sink_L["Sink Component"]:::sink
    end
```
