# pirsch-analytics/pirsch architecture

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

- Interactive diagram: https://gitdiagram.com/pirsch-analytics/pirsch
- Repository: https://github.com/pirsch-analytics/pirsch

## Overview

##### Main Components

a. Tracker Package (/pkg/tracker)
- Represents the data collection layer
- Handles user agent parsing, IP processing, and geolocation
- Manages session handling
- Contains referrer processing
- Should be shown as the entry point for analytics data

b. Analyzer Package (/pkg/analyzer)
- Represents the analytics processing layer
- Handles various types of analysis:
- Demographics
- Device information
- Events
- Funnels
- Page views
- Sessions
- UTM parameters
- Visitors

c. Database Layer (/pkg/db)
- ClickHouse database integration
- Schema management
- Data storage and retrieval

**[Client/Website] → [Tracker Layer] → [Analyzer Layer] → [Database Layer]**

##### Detailed Component Breakdown

For each major component, include these subcomponents:

Tracker Layer:
- IP Processing (pkg/tracker/ip)
- Geolocation (pkg/tracker/geodb)
- User Agent Parser (pkg/tracker/ua)
- Session Management (pkg/tracker/session)
- Referrer Processing (pkg/tracker/referrer)
- Channel Processing (pkg/tracker/channel)

Analyzer Layer:
- Visitor Analytics
- Event Processing
- Funnel Analysis
- Page Analytics
- Session Analysis
- Filter System
- Query Builder

Database Layer:
- ClickHouse Connection
- Migration System
- Data Store Interface

##### Important Flows to Highlight

- Fingerprint Generation Flow:
- [IP + UserAgent + Date + Salt] → [Fingerprint Hash]
- Data Processing Pipeline:
- [Raw Request] → [Preprocessing] → [Analysis] → [Storage]

##### Technical Details

Notes about:
- ClickHouse as the database
- Redis/Memory cache options for sessions
- GeoIP2 database integration
- Referrer processing rules
- Migration system

Remember to highlight the system's unique selling points:
- Server-side tracking
- Privacy-first design
- No cookies required
- Ad-blocker resistance (when used server-side)

This will create a comprehensive system design that accurately represents Pirsch Analytics' architecture while emphasizing its privacy-focused nature and technical capabilities.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and classes
    classDef frontend fill:#e1f5fe,stroke:#01579b
    classDef tracker fill:#e8f5e9,stroke:#2e7d32
    classDef analyzer fill:#fff3e0,stroke:#ef6c00
    classDef database fill:#fce4ec,stroke:#c2185b
    classDef model fill:#f3e5f5,stroke:#7b1fa2

    %% Legend
    subgraph Legend
        F[Frontend Component]:::frontend
        T[Tracker Component]:::tracker
        A[Analyzer Component]:::analyzer
        D[Database Component]:::database
        M[Model Component]:::model
    end

    %% Client Layer
    Client[Client Website]:::frontend

    %% Tracker Layer
    subgraph Tracker
        TrackerMain["Tracker Package"]:::tracker
        IP["IP Processing"]:::tracker
        Geo["Geolocation"]:::tracker
        UA["User Agent Parser"]:::tracker
        Session["Session Management"]:::tracker
        Referrer["Referrer Processing"]:::tracker
        Channel["Channel Processing"]:::tracker
    end

    %% Models Layer
    subgraph Models
        PageViewModel["Page View Model"]:::model
        SessionModel["Session Model"]:::model
        EventModel["Event Model"]:::model
    end

    %% Analyzer Layer
    subgraph Analyzer
        AnalyzerMain["Analyzer Package"]:::analyzer
        Demographics["Demographics Analysis"]:::analyzer
        Device["Device Analysis"]:::analyzer
        Events["Events Analysis"]:::analyzer
        Funnel["Funnel Analysis"]:::analyzer
        Pages["Page Analysis"]:::analyzer
        Sessions["Sessions Analysis"]:::analyzer
        UTM["UTM Analysis"]:::analyzer
        Visitors["Visitors Analysis"]:::analyzer
        Filter["Filter System"]:::analyzer
        Query["Query Builder"]:::analyzer
    end

    %% Database Layer
    subgraph Database
        DBClient["ClickHouse Client"]:::database
        Migration["Migration System"]:::database
        Schema["Database Schema"]:::database
        Store["Data Store Interface"]:::database
    end

    %% Relationships
    Client --> TrackerMain
    TrackerMain --> IP
    TrackerMain --> Geo
    TrackerMain --> UA
    TrackerMain --> Session
    TrackerMain --> Referrer
    TrackerMain --> Channel

    TrackerMain --> Models
    Models --> AnalyzerMain
    
    AnalyzerMain --> Demographics
    AnalyzerMain --> Device
    AnalyzerMain --> Events
    AnalyzerMain --> Funnel
    AnalyzerMain --> Pages
    AnalyzerMain --> Sessions
    AnalyzerMain --> UTM
    AnalyzerMain --> Visitors
    AnalyzerMain --> Filter
    AnalyzerMain --> Query

    Query --> DBClient
    DBClient --> Migration
    DBClient --> Schema
    DBClient --> Store

    %% Click Events
    click TrackerMain "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/tracker/tracker.go"
    click IP "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/tracker/ip/ip.go"
    click Geo "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/tracker/geodb/geodb.go"
    click UA "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/tracker/ua/parser.go"
    click Session "https://github.com/pirsch-analytics/pirsch/tree/master/pkg/tracker/session/"
    click Referrer "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/tracker/referrer/referrer.go"
    click Channel "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/tracker/channel/channel.go"
    
    click AnalyzerMain "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/analyzer/analyzer.go"
    click Demographics "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/analyzer/demographics.go"
    click Device "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/analyzer/device.go"
    click Events "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/analyzer/events.go"
    click Funnel "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/analyzer/funnel.go"
    click Pages "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/analyzer/pages.go"
    click Sessions "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/analyzer/sessions.go"
    click UTM "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/analyzer/utm.go"
    click Visitors "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/analyzer/visitors.go"
    click Filter "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/analyzer/filter.go"
    click Query "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/analyzer/query.go"
    
    click DBClient "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/db/client.go"
    click Migration "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/db/migrate.go"
    click Schema "https://github.com/pirsch-analytics/pirsch/tree/master/pkg/db/schema/"
    click Store "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/db/store.go"
    
    click Models "https://github.com/pirsch-analytics/pirsch/tree/master/pkg/model/"
    click PageViewModel "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/model/page_view.go"
    click SessionModel "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/model/session.go"
    click EventModel "https://github.com/pirsch-analytics/pirsch/blob/master/pkg/model/event.go"
```
