# ankan97dutta/profilis architecture

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

- Interactive diagram: https://gitdiagram.com/ankan97dutta/profilis
- Repository: https://github.com/ankan97dutta/profilis

## Overview

##### Project Type and Purpose
- Profilis is an open-source Python library (“tool”) for high-performance, non-blocking profiling of web applications and database operations.
- It’s framework-agnostic (Flask adapter built-in; FastAPI/Sanic planned) and provides decorators, instrumentation modules, asynchronous collection, multiple exporters, and a built-in UI dashboard.

##### File-Structure Analysis
- Top-level “src/profilis” folder contains:
- core (AsyncCollector, Emitter, StatsStore)
- decorators (profile_function)
- exporters (ConsoleExporter, JSONLExporter, BaseExporter)
- flask adapter (ProfilisFlask, UI blueprint)
- database instrumentation modules (sqlalchemy, pyodbc, mongo, neo4j)
- runtime (trace/span context management)
- “docs” and “examples” demonstrate usage and build processes.
- CI, docs, and packaging are driven by GitHub Workflows, mkdocs, pyproject.toml, requirements files.

##### README Insights
- Architecture documented under docs/architecture.
- Highlights: async batching, adapter pattern, decorator pattern, plugin-style instrumentation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Third-Party Application Layer
    subgraph "Third-Party Application" 
        direction TB
        App["Web Application"]:::app
        Decorator["@profile_function"]:::instr
        FlaskAdapter["ProfilisFlask Adapter"]:::instr
        App -->|"HTTP Request"| FlaskAdapter
        App -->|"Function Call"| Decorator
    end

    %% Profilis Library
    subgraph "Profilis Library"
        direction TB

        %% Instrumentation Layer
        subgraph "Instrumentation Layer"
            direction TB
            DB_SQLA["SQLAlchemy Instrumentation"]:::instr
            DB_PYODBC["PyODBC Instrumentation"]:::instr
            DB_MONGO["MongoDB Instrumentation"]:::instr
            DB_NEO4J["Neo4j Instrumentation"]:::instr
        end

        %% Core Collection Layer
        subgraph "Core Collection Layer"
            direction TB
            Emitter["Emitter"]:::core
            AsyncCollector["AsyncCollector"]:::core
            StatsStore["StatsStore"]:::core
        end

        %% Export Layer
        subgraph "Export Layer"
            direction TB
            JSONLExporter["JSONLExporter"]:::export
            ConsoleExporter["ConsoleExporter"]:::export
            BaseExporter["BaseExporter"]:::export
        end

        %% UI Layer
        subgraph "UI Layer"
            direction TB
            UIBlueprint["UI Blueprint (/ _profilis)"]:::ui
        end

    end

    %% External Storage / Services
    subgraph "External Storage & Services"
        direction TB
        FS["File System (JSONL files)"]:::external
        MetricsStore["Metrics Store (optional)"]:::external
    end

    %% Data Flows
    FlaskAdapter -->|"emit_req"| Emitter
    Decorator -->|"emit_fn"| Emitter
    DB_SQLA -->|"emit_db"| Emitter
    DB_PYODBC -->|"emit_db"| Emitter
    DB_MONGO -->|"emit_db"| Emitter
    DB_NEO4J -->|"emit_db"| Emitter

    Emitter -->|"enqueue"| AsyncCollector
    AsyncCollector -->|"batch_export"| JSONLExporter
    AsyncCollector -->|"batch_export"| ConsoleExporter
    AsyncCollector -->|"aggregate"| StatsStore

    JSONLExporter -->|"write"| FS
    ConsoleExporter -->|"write"| FS

    StatsStore -->|"serve_metrics"| UIBlueprint
    UIBlueprint -->|"render dashboard"| App

    %% Click Events
    click AsyncCollector "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/core/async_collector.py"
    click Emitter "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/core/emitter.py"
    click StatsStore "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/core/stats.py"
    click Decorator "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/decorators/profile.py"
    click ConsoleExporter "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/exporters/console.py"
    click JSONLExporter "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/exporters/jsonl.py"
    click BaseExporter "https://github.com/ankan97dutta/profilis/tree/main/src/profilis/exporters"
    click FlaskAdapter "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/flask/adapter.py"
    click UIBlueprint "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/flask/ui.py"
    click DB_SQLA "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/sqlalchemy/instrumentation.py"
    click DB_PYODBC "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/pyodbc/instrumentation.py"
    click DB_MONGO "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/mongo/instrumentation.py"
    click DB_NEO4J "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/neo4j/instrumentation.py"
    click Clock "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/runtime/clock.py"
    click Context "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/runtime/context.py"
    click IDs "https://github.com/ankan97dutta/profilis/blob/main/src/profilis/runtime/ids.py"

    %% Runtime components (supporting)
    subgraph "Runtime"
        direction TB
        Clock["Clock (timer)"]:::core
        Context["Context Management"]:::core
        IDs["ID Generation"]:::core
    end

    Context --> Emitter
    Clock --> AsyncCollector
    IDs --> StatsStore

    %% Styles
    classDef app fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef instr fill:#CCE5FF,stroke:#005BCC,color:#005BCC;
    classDef core fill:#D2F8D2,stroke:#28A745,color:#28A745;
    classDef export fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00;
    classDef ui fill:#E8D3FF,stroke:#6F42C1,color:#6F42C1;
    classDef external fill:#E0E0E0,stroke:#6C757D,color:#6C757D;
```
