# gigachad80/mailansh architecture

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

- Interactive diagram: https://gitdiagram.com/gigachad80/mailansh
- Repository: https://github.com/gigachad80/mailansh

## Overview

##### Project Type and Purpose
- Mailansh is a Go-based command-line OSINT utility for extracting contributor emails from Git repositories across multiple hosting platforms (GitHub, GitLab, Gitea, Bitbucket).
- It emphasizes high performance via concurrent processing, advanced filtering, smart deduplication, and multiple output formats.

##### File Structure Analysis
- cmd/mailansh/main.go: CLI entrypoint—parses flags, loads configuration, initializes components, orchestrates workflow.
- internal/config: Flag and configuration parsing.
- pkg/platform: Abstraction over multiple Git hosting platforms (URL patterns, platform-specific filters).
- pkg/git: Wrappers around the Git CLI for cloning and repository operations.
- pkg/extractor: Core extraction engine, split into:
- commit.go (linear git-log extraction)
- patch.go   (patch scanning, uses worker pool)
- pkg/contributor: Thread-safe manager for deduplicating, filtering, and categorizing emails.
- pkg/output: Formatting and writing results (table, CSV, text).
- pkg/progress: Real-time progress reporting.

##### Key Architectural Patterns
- Worker Pool Pattern: Eight goroutines process patch data concurrently.
- Dual Extraction Pipeline:
- Pipeline A: Serial commit-history scanning.
- Pipeline B: Parallel patch content analysis.
- Thread Safety: Contributor manager uses mutexes to avoid race conditions.
- Streaming & Cleanup: Intermediate data is streamed and cleaned up to minimize memory footprint.
- Context-Aware Execution: Cancellation and timeouts propagate through extractors.

##### Main Components
- CLI Layer
- Flag Parser (internal/config)
- Configuration Loader
- Platform Resolver (pkg/platform)
- Determines repository URL patterns & any platform-specific logic.
- Git Layer (pkg/git)
- Clone or fetch repository via Git CLI.
- Extraction Engine (pkg/extractor)
- CommitLog Extractor (sequential)
- Patch Extractor with Worker Pool (concurrent)
- Coordination component that fans out commit IDs to patch workers.
- Contributor Manager (pkg/contributor)
- Central aggregator, deduplicator, filter engine.
- Progress Reporter (pkg/progress)
- Subscribes to both extraction pipelines for real-time updates.
- Renders final results to stdout or writes to CSV/text file.

##### Relationships and Data Flows
- User ⇒ CLI Layer: starts process with flags and repo URL.
- CLI Layer ⇒ Platform Resolver ⇒ Git Layer: clones repo to local workspace.
- Git Layer ⇒ Extraction Engine: scans commits ⇒ emits commit IDs and diffs.
- Extraction Engine ⇒ Contributor Manager: pushes discovered emails.
- Extraction Engine & Contributor Manager ⇒ Progress Reporter: updates are published.
- Contributor Manager ⇒ Output Formatter ⇒ User: final formatted output.
- Errors and cancellation signals propagate back through context.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    GitCLI(["Git CLI"]):::external
    Network(["Network"]):::external
    FS(["File System"]):::external
    User(["User"]):::user

    %% CLI Layer
    subgraph "CLI Layer"
        CLIEntrypoint["CLI Entrypoint\n(cmd/mailansh/main.go)"]:::blue
        FlagParser["Flag Parser\n(internal/config/flags.go)"]:::blue
        ConfigLoader["Configuration Loader\n(internal/config)"]:::blue
    end

    %% Ingestion Layer
    subgraph "Ingestion Layer"
        PlatformResolver["Platform Resolver\n(pkg/platform/platform.go)"]:::green
        GitClone["Git Clone\n(pkg/git/clone.go)"]:::green
        GitUtils["Git Utils\n(pkg/git/utils.go)"]:::green
    end

    %% Processing Layer
    subgraph "Processing Layer"
        ExtractionCoord["Extraction Coordinator\n(pkg/extractor/extractor.go)"]:::green
        CommitExtractor["CommitLog Extractor\n(pkg/extractor/commit.go)"]:::green
        PatchExtractor["Patch Extractor\n(pkg/extractor/patch.go)\nWorker Pool N=8"]:::green
    end

    %% Aggregation Layer
    subgraph "Aggregation Layer"
        ContributorMgr["Contributor Manager\n(pkg/contributor/manager.go)"]:::orange
        ContributorCore["Contributor Core\n(pkg/contributor/contributor.go)"]:::orange
        Filters["Filters\n(pkg/contributor/filter.go)"]:::orange
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        Formatter["Output Formatter\n(pkg/output/formatter.go)"]:::yellow
        ColorUtil["Color Utils\n(pkg/color/color.go)"]:::yellow
        Progress["Progress Reporter\n(pkg/progress/reporter.go)"]:::yellow
    end

    %% Flows
    User -->|"start with flags & repo URL"| CLIEntrypoint
    CLIEntrypoint -->|"parse flags"| FlagParser
    CLIEntrypoint -->|"load config"| ConfigLoader
    CLIEntrypoint -->|"resolve platform"| PlatformResolver
    CLIEntrypoint -.->|"context"| ExtractionCoord

    PlatformResolver -->|"determine URL"| GitClone
    GitClone -->|"invoke"| GitCLI
    GitClone -->|"fetch repo"| Network
    GitClone -->|"write repo"| FS
    GitClone -->|"provide workspace"| ExtractionCoord
    GitClone --> GitUtils

    ExtractionCoord -->|"scan commits"| CommitExtractor
    ExtractionCoord -->|"dispatch commit IDs"| PatchExtractor

    CommitExtractor -->|"emit emails"| ContributorMgr
    PatchExtractor -->|"emit emails"| ContributorMgr

    ExtractionCoord -->|"publish updates"| Progress
    CommitExtractor -->|"publish updates"| Progress
    PatchExtractor -->|"publish updates"| Progress

    ContributorMgr -->|"/ deduplicate & filter"| Filters
    Filters -->|"final data"| Formatter
    Formatter -->|"use colors"| ColorUtil
    Formatter -->|"output results"| User
    Progress -->|"real-time updates"| User

    %% Click Events
    click CLIEntrypoint "https://github.com/gigachad80/mailansh/blob/main/cmd/mailansh/main.go"
    click FlagParser "https://github.com/gigachad80/mailansh/blob/main/internal/config/flags.go"
    click PlatformResolver "https://github.com/gigachad80/mailansh/blob/main/pkg/platform/platform.go"
    click GitClone "https://github.com/gigachad80/mailansh/blob/main/pkg/git/clone.go"
    click GitUtils "https://github.com/gigachad80/mailansh/blob/main/pkg/git/utils.go"
    click ExtractionCoord "https://github.com/gigachad80/mailansh/blob/main/pkg/extractor/extractor.go"
    click CommitExtractor "https://github.com/gigachad80/mailansh/blob/main/pkg/extractor/commit.go"
    click PatchExtractor "https://github.com/gigachad80/mailansh/blob/main/pkg/extractor/patch.go"
    click ContributorMgr "https://github.com/gigachad80/mailansh/blob/main/pkg/contributor/manager.go"
    click ContributorCore "https://github.com/gigachad80/mailansh/blob/main/pkg/contributor/contributor.go"
    click Filters "https://github.com/gigachad80/mailansh/blob/main/pkg/contributor/filter.go"
    click Progress "https://github.com/gigachad80/mailansh/blob/main/pkg/progress/reporter.go"
    click Formatter "https://github.com/gigachad80/mailansh/blob/main/pkg/output/formatter.go"
    click ColorUtil "https://github.com/gigachad80/mailansh/blob/main/pkg/color/color.go"

    %% Styles
    classDef blue fill:#D0E4F5,stroke:#0366D6,stroke-width:2px;
    classDef green fill:#DFF5E1,stroke:#28A745,stroke-width:2px;
    classDef orange fill:#FFE5B4,stroke:#E36209,stroke-width:2px;
    classDef yellow fill:#FFF8C6,stroke:#F1C40F,stroke-width:2px;
    classDef external fill:#EEEEEE,stroke:#AAAAAA,stroke-width:1px,stroke-dasharray: 5 5;
    classDef user fill:#F0F0F0,stroke:#888888,stroke-width:1px;
```
