# medama-io/medama architecture

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

- Interactive diagram: https://gitdiagram.com/medama-io/medama
- Repository: https://github.com/medama-io/medama

## Overview

##### Main Components Identification
The system consists of three major components that should be prominently featured:

a) Tracker Component (/tracker)
- As a lightweight JavaScript module
- Integration with client websites
- Cookie-free nature
- Event capture functionality

b) Core Component (/core)
- Main server architecture
- Two database systems:
- DuckDB for analytics data
- SQLite for user management
- API endpoints (OpenAPI-based)
- Authentication system

c) Dashboard Component (/dashboard)
- React-based frontend
- Routing system
- Stats visualization components
- Settings management

##### Relationships and Data Flow

**Website Visitors -> Tracker -> Core API -> DuckDB**
- > SQLite
**Dashboard UI <-> Core API (OpenAPI)**

##### Detailed Component Breakdown

For each major component, include these elements:

Tracker:
- Event Collectors (page events, click events)
- Data API interface
- History tracking module

Core:
- API Layer (OpenAPI)
- Service Layer
- Database Layer
- DuckDB for analytics
- SQLite for user management
- Middleware (auth, CORS, error handling)
- Migration system

Dashboard:
- React Components
- API Client
- Stats Visualization
- Settings Management

##### Technical Stack Indicators

Technology labels:
- JavaScript/TypeScript (Tracker & Dashboard)
- Go (Core)
- DuckDB & SQLite (Databases)
- React (Dashboard)
- OpenAPI (API specification)

##### Deployment Context

Optional deployment scenarios:
- Single binary deployment
- Minimal resource requirements (256MB RAM)
- Container-based deployment (Docker)

Remember to include version information and any relevant notes about scaling considerations, as this appears to be a system that can handle both small websites and larger deployments.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Visitors
        WebVisitors[Website Visitors]
    end

    subgraph "Tracker Layer"
        Tracker["Tracker (<1KB)"]:::tracker
        EventCollectors["Event Collectors"]:::tracker
        HistoryTrack["History Tracking"]:::tracker
        DataAPI["Data API Interface"]:::tracker
    end

    subgraph "Core Layer"
        APILayer["API Layer (OpenAPI)"]:::core
        ServiceLayer["Service Layer"]:::core
        AuthSystem["Authentication System"]:::core
        DBLayer["Database Layer"]:::core
        
        subgraph "Databases"
            DuckDB[(DuckDB Analytics)]:::db
            SQLite[(SQLite Users)]:::db
        end
        
        subgraph "Middleware"
            AuthMW["Auth Middleware"]:::core
            CORS["CORS"]:::core
            ErrorHandler["Error Handling"]:::core
        end
    end

    subgraph "Dashboard Layer"
        ReactUI["React UI"]:::dashboard
        APIClient["API Client"]:::dashboard
        StatsViz["Stats Visualization"]:::dashboard
        Settings["Settings Management"]:::dashboard
    end

    %% Relationships
    WebVisitors --> Tracker
    Tracker --> EventCollectors
    Tracker --> HistoryTrack
    EventCollectors --> DataAPI
    DataAPI --> APILayer
    
    APILayer --> ServiceLayer
    ServiceLayer --> DBLayer
    DBLayer --> DuckDB
    DBLayer --> SQLite
    
    ServiceLayer --> AuthSystem
    AuthSystem --> AuthMW
    
    ReactUI --> APIClient
    APIClient <--> APILayer
    ReactUI --> StatsViz
    ReactUI --> Settings

    %% Click Events
    click Tracker "https://github.com/medama-io/medama/blob/main/tracker/src/tracker.js"
    click EventCollectors "https://github.com/medama-io/medama/blob/main/tracker/dist/click-events.js"
    click HistoryTrack "https://github.com/medama-io/medama/blob/main/tracker/tests/history.spec.js"
    click APILayer "https://github.com/medama-io/medama/tree/main/core/api/"
    click ServiceLayer "https://github.com/medama-io/medama/tree/main/core/services/"
    click AuthSystem "https://github.com/medama-io/medama/blob/main/core/services/auth.go"
    click DBLayer "https://github.com/medama-io/medama/tree/main/core/db/"
    click AuthMW "https://github.com/medama-io/medama/blob/main/core/middlewares/auth.go"
    click ReactUI "https://github.com/medama-io/medama/tree/main/dashboard/app/components/"
    click APIClient "https://github.com/medama-io/medama/tree/main/dashboard/app/api/"
    click StatsViz "https://github.com/medama-io/medama/tree/main/dashboard/app/components/stats/"
    click Settings "https://github.com/medama-io/medama/tree/main/dashboard/app/components/settings/"

    %% Styling
    classDef tracker fill:#a8e6cf,stroke:#3b6978
    classDef core fill:#dcedc1,stroke:#3b6978
    classDef dashboard fill:#ffd3b6,stroke:#3b6978
    classDef db fill:#ffaaa5,stroke:#3b6978

    %% Legend
    subgraph Legend
        L1["Tracker Components"]:::tracker
        L2["Core Components"]:::core
        L3["Dashboard Components"]:::dashboard
        L4[(Database)]:::db
    end
```
