# pkolano/freeme architecture

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

- Interactive diagram: https://gitdiagram.com/pkolano/freeme
- Repository: https://github.com/pkolano/freeme

## Overview

##### Main Components
- Input Handler: Represent the module that accepts incoming e-mails – either as they are received live (procmail-like) or from existing mailboxes.
- Filtering Engine: This core component applies regular expression matching for filtering e-mails. It is responsible for determining if an e-mail should be ignored, resent, or aggregated.
- Output Processors:
- Direct Resend/Forwarding Module: For on-demand or immediate notification.
- Digest Generator: Aggregates similar messages into a consolidated format.
- Historical Archive: A module/service responsible for storing original e-mails and supporting on-demand queries.
- Configuration Loader: Using files like "freemerc" (likely configuration) and possibly "freeme_relay.sample" for relay settings, this component initializes system parameters.

##### Relationships and Interactions
- A link from the Configuration Loader to all other components, showing that initial configuration parameters influence behavior system-wide.

##### Architectural Patterns and Technologies
- Modularity: Clearly separate the processing pipeline from configuration and output generation.
- Inter-component Communication: Although this is a single-tool, it is beneficial to denote clear data flow—representing sequential stages (Input → Filtering → Output/Archive).
- Reliance on Regular Expressions: Mark the Filtering Engine with a note that it leverages full regex capabilities for matching e-mail fields.

## Diagram (Mermaid)

```mermaid
graph TD
    Environment["Environment Layer: Command-Line/Documentation"]:::environment
    Config["Configuration Loader: App Config"]:::config
    Input["Input Handler: E-mail Ingestion"]:::input
    Mode["Mode Selector: Real-time/Post-processing"]:::decision
    Engine["Filtering Engine: Regex Matching"]:::engine
    Subscription["Subscription Management: Admin Subscriptions"]:::config
    Direct["Direct Resend/Forwarding Module"]:::output
    Digest["Digest Generator: Aggregates similar messages"]:::output
    Archive["Historical Archive: Store & Query"]:::archive

    %% External influences
    Environment -->|"docInfluence"| Config

    %% Configuration influence on components
    Config -->|"cfg"| Input
    Config -->|"cfg"| Engine
    Config -->|"cfg"| Subscription
    Config -->|"cfg"| Direct
    Config -->|"cfg"| Digest
    Config -->|"cfg"| Archive

    %% Processing pipeline flow
    Input -->|"chooseMode"| Mode
    Mode -->|"processMode"| Engine
    Engine -->|"matchSubs"| Subscription
    Engine -->|"sendDirect"| Direct
    Engine -->|"generateDigest"| Digest
    Engine <-->|"archiveQuery"| Archive
    Direct -->|"storeEmail"| Archive
    Digest -->|"storeEmail"| Archive

    %% Styles
    classDef environment fill:#FFC0CB,stroke:#333,stroke-width:2px;
    classDef config fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef input fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef engine fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef output fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef archive fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef decision fill:#EEE,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;

    %% Click Events
    click Input "https://github.com/pkolano/freeme/tree/master/freeme"
    click Engine "https://github.com/pkolano/freeme/tree/master/freeme"
    click Subscription "https://github.com/pkolano/freeme/tree/master/freemerc"
    click Direct "https://github.com/pkolano/freeme/blob/master/freeme_relay.sample"
    click Config "https://github.com/pkolano/freeme/tree/master/freemerc"
    click Environment "https://github.com/pkolano/freeme/blob/master/freeme.1"
```
