# akshatdalton/sherlock architecture

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

- Interactive diagram: https://gitdiagram.com/akshatdalton/sherlock
- Repository: https://github.com/akshatdalton/sherlock

## Overview

##### Project type and purpose
- This is an open-source Python instrumentation library whose goal is to observe incoming and outgoing requests and ensure every HTTP request carries a correlation ID header.
- The README calls it “Your Sherlock to observe and add the missing correlation ID in the request headers,” confirming it’s a middleware/utility rather than a standalone service.

##### File structure
- Top-level config: .gitignore, pre-commit, pyproject.toml, README.md
- Main package “sherlock/”
- constants.py – shared names, defaults
- sleuth.py & instrumentation.py – core engine that generates/injects IDs
- logging_filters.py – hooks into Python logging to append correlation IDs to logs
- utils.py – helper functions (e.g., ID generator)
- integrations/ – adapters for specific frameworks and libraries (AWS Lambda, FastAPI, HTTPX, urllib3)
- plugins/ – extension points (base_plugin.py) and built-in Sentry plugin
- tests/ – unit tests for each integration and core component

##### README for additional insights
- Encourages you to infer architecture from file structure and naming.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Host Applications"
        FastAPIApp["FastAPI App"]:::external
        LambdaHandler["AWS Lambda Handler"]:::external
    end

    subgraph "Integrations"
        IntegrationInterface["Integration Interface"]:::integration
        AWSLambdaAdapter["AWS Lambda Adapter"]:::integration
        FastAPIIntegration["FastAPI Middleware"]:::integration
        HTTPXHook["HTTPX Hook"]:::integration
        Urllib3Patch["urllib3 Patch"]:::integration
    end

    subgraph "Core Engine"
        Sleuth["sleuth.py"]:::core
        Instrumentation["instrumentation.py"]:::core
        Constants["constants.py"]:::core
        Utils["utils.py"]:::core
        LoggingFilters["logging_filters.py"]:::core
    end

    subgraph "Plugin Framework"
        BasePlugin["base_plugin.py"]:::plugin
        SentryPlugin["sentry.py"]:::plugin
    end

    subgraph "External Systems"
        DownstreamService["Downstream HTTP Service"]:::external
        ObservabilityBackend["Observability Backend"]:::external
    end

    FastAPIApp -->|"incoming request"| FastAPIIntegration
    LambdaHandler -->|"invoke"| AWSLambdaAdapter
    FastAPIIntegration -->|"calls"| Instrumentation
    AWSLambdaAdapter -->|"calls"| Instrumentation
    Instrumentation -->|"uses core logic"| Sleuth
    Sleuth -->|"reads/propagates ID"| Constants
    Sleuth -->|"helper functions"| Utils
    Sleuth -->|"attach to logs"| LoggingFilters
    Instrumentation -->|"outbound HTTP"| HTTPXHook
    Instrumentation -->|"outbound HTTP"| Urllib3Patch
    HTTPXHook -->|"sends request"| DownstreamService
    Urllib3Patch -->|"sends request"| DownstreamService
    Sleuth -->|"lifecycle events"| BasePlugin
    BasePlugin -->|"extension point"| SentryPlugin
    SentryPlugin -->|"reports"| ObservabilityBackend

    click Sleuth "https://github.com/akshatdalton/sherlock/blob/develop/sherlock/sleuth.py"
    click Instrumentation "https://github.com/akshatdalton/sherlock/blob/develop/sherlock/instrumentation.py"
    click Constants "https://github.com/akshatdalton/sherlock/blob/develop/sherlock/constants.py"
    click Utils "https://github.com/akshatdalton/sherlock/blob/develop/sherlock/utils.py"
    click LoggingFilters "https://github.com/akshatdalton/sherlock/blob/develop/sherlock/logging_filters.py"
    click IntegrationInterface "https://github.com/akshatdalton/sherlock/blob/develop/sherlock/integrations/integration.py"
    click AWSLambdaAdapter "https://github.com/akshatdalton/sherlock/blob/develop/sherlock/integrations/aws_lambda.py"
    click FastAPIIntegration "https://github.com/akshatdalton/sherlock/blob/develop/sherlock/integrations/fastapi.py"
    click HTTPXHook "https://github.com/akshatdalton/sherlock/blob/develop/sherlock/integrations/httpx.py"
    click Urllib3Patch "https://github.com/akshatdalton/sherlock/blob/develop/sherlock/integrations/urllib3.py"
    click BasePlugin "https://github.com/akshatdalton/sherlock/blob/develop/sherlock/plugins/base_plugin.py"
    click SentryPlugin "https://github.com/akshatdalton/sherlock/blob/develop/sherlock/plugins/sentry.py"

    classDef core fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef integration fill:#CFFFD3,stroke:#333,stroke-width:1px
    classDef plugin fill:#FFD8A8,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
