# ankane/ahoy architecture

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

- Interactive diagram: https://gitdiagram.com/ankane/ahoy
- Repository: https://github.com/ankane/ahoy

## Overview

##### Project Type and Purpose
- Ahoy is a Ruby gem / Rails Engine providing first-party analytics for Rails applications.
- It exposes HTTP API endpoints (`/ahoy/visits`, `/ahoy/events`) and ships with a default database store, while allowing custom stores (Kafka, Kinesis, etc.).
- It integrates client-side libraries (ahoy.js, native SDKs) with server-side tracking logic, background jobs (geocoding), and ActiveRecord/Mongoid models.

##### Main Architectural Components
A. Clients
– Web browser running ahoy.js
– Native mobile apps (iOS, Android)
– AMP pages
B. Host Rails Application
– Mounts the Ahoy Rails Engine
– Your existing controllers, views, and models (e.g., `Order`, `User`)
– Authentication framework (Devise, Doorkeeper, or custom)
C. Ahoy Engine (in `app/controllers/ahoy`, `lib/ahoy/engine.rb`)
– Controllers: `VisitsController`, `EventsController`
– Routes: mounted under `/ahoy` via `config/routes.rb` in the engine
– Tracker (`lib/ahoy/tracker.rb`) invoked by controllers and by your app via `ahoy.track`
– Models: `Ahoy::Visit`, `Ahoy::Event` (ActiveRecord/Mongoid) and query methods (`lib/ahoy/query_methods.rb`)
– Generators (`lib/generators/ahoy`) for migrations, models, and initializer templates
D. Data Store Layer
– Default: `Ahoy::DatabaseStore` writes visits & events to your Rails DB
– Custom: any subclass of `Ahoy::BaseStore` (Kafka, RabbitMQ, Fluentd, etc.)
– Store methods: `track_visit`, `track_event`, `geocode`, `authenticate`
E. Background Job Processor
– Geocoding job (`lib/ahoy/geocode_v2_job.rb`) enqueued on `:ahoy` queue
– Any other asynchronous tasks (e.g., custom data-store flush)
F. External Services
– Geocoding services (third-party API or local MaxMind DB)
– Third-party analytics sinks (Kafka, Kinesis, NSQ, etc.)
– Exception reporters (Rollbar via Safely)

##### Relationships & Data Flow
1. Client → HTTP(S) POST to `/ahoy/visits` → `Ahoy::VisitsController#create`
2. Controller calls `Ahoy::Tracker#track_visit` → delegates to your `Ahoy::Store` → writes to DB or pushes to message queue
3. Visit model persisted; background job enqueues geocoding: `Ahoy::GeocodeV2Job.perform_later(visit_id)`
4. Client or server calls `ahoy.track` → HTTP POST to `/ahoy/events` → `Ahoy::EventsController#create` → `track_event` in store
5. Authentication hook (`Ahoy::Store#authenticate`) links `current_user` to `ahoy_visit_id`
6. Host App models use `visitable` to join visits, enabling queries like `Order.joins(:ahoy_visit)`
7. Query layer (`QueryMethods`) handles JSON, HSTORE, arrays across MySQL, Postgres, SQLite, MongoDB

##### Architectural Patterns & Design Principles
– Plugin architecture: shipped as a self-contained Rails Engine
– Store subscriber pattern: base store with hook methods, easily extendable
– MVC (controllers → tracker → store → models)
– Asynchronous background processing for geocoding and heavy tasks
– Separation of concerns: tracking logic lives in the engine, your app handles domain models

## Diagram (Mermaid)

```mermaid
graph TD
    %% Clients (Blue)
    subgraph "Clients" 
        direction TB
        Browser["Web Browser (ahoy.js)"]:::client
        Native["Native Mobile (iOS/Android)"]:::client
        AMP["AMP Pages"]:::client
    end

    %% Host Application (Gray)
    subgraph "Host Rails App" 
        direction TB
        Auth["Authentication (Devise/Doorkeeper)"]:::host
        Mount["Mount Ahoy Engine"]:::host
    end

    %% Ahoy Engine (Green)
    subgraph "Ahoy Engine" 
        direction TB
        EngineMount["Engine Mount Point"]:::engine
        Routes["Engine Routes"]:::engine
        subgraph "Controllers"
            direction TB
            BaseCtrl["BaseController"]:::engine
            VisitsCtrl["VisitsController"]:::engine
            EventsCtrl["EventsController"]:::engine
        end
        subgraph "Tracker"
            direction TB
            Tracker["Tracker"]:::engine
            CtrlHelper["Controller Helper"]:::engine
        end
        subgraph "Models & Query"
            direction TB
            ModelMixin["Model Mixin"]:::engine
            VisitProps["Visit Properties"]:::engine
            QueryMethods["Query Methods"]:::engine
        end
        subgraph "Generators"
            direction TB
            GenBase["Generator Base"]:::engine
            ARGen["ActiveRecord Generator"]:::engine
            MongoGen["Mongoid Generator"]:::engine
            InstallGen["Install Generator"]:::engine
            Templates["Generator Templates"]:::engine
        end
        Version["Version & Gemspec"]:::engine
    end

    %% Data Store Layer (Orange)
    subgraph "Data Store Layer"
        direction TB
        BaseStore["Abstract Store (BaseStore)"]:::store
        DBStore["Database Store"]:::store
        MQ["Message Queue Topics (Kafka, etc.)"]:::store
    end

    %% Background Jobs (Purple)
    subgraph "Background Jobs"
        direction TB
        GeocodeJob["GeocodeV2Job"]:::job
    end

    %% Databases & Queues (Orange)
    subgraph "Storage"
        direction TB
        VisitsTable["ahoy_visits Table"]:::store
        EventsTable["ahoy_events Table"]:::store
    end

    %% External Services (Red)
    subgraph "External Services"
        direction TB
        Geocoder["Geocoding Service"]:::external
        AnalyticsSink["3rd-Party Analytics Sink"]:::external
        ExceptionReporter["Exception Reporter"]:::external
    end

    %% Relationships
    Browser -->|POST /ahoy/visits| VisitsCtrl
    Native -->|POST /ahoy/visits| VisitsCtrl
    AMP -->|POST /ahoy/visits| VisitsCtrl

    VisitsCtrl -->|calls Tracker#track_visit| Tracker
    EventsCtrl -->|calls Tracker#track_event| Tracker
    Tracker -->|delegates| BaseStore
    BaseStore -->|default| DBStore
    BaseStore -->|custom| MQ

    DBStore -->|INSERT INTO| VisitsTable
    DBStore -->|INSERT INTO| EventsTable
    MQ -->|publish| AnalyticsSink

    VisitsTable -->|enqueues| GeocodeJob
    GeocodeJob -->|calls geocode| Geocoder

    HostRails["Host Rails App"] -.->|mounts| EngineMount
    EngineMount --> Routes
    Auth -->|hooks| BaseStore

    %% Click events
    click EngineMount "https://github.com/ankane/ahoy/blob/master/lib/ahoy/engine.rb"
    click Routes "https://github.com/ankane/ahoy/blob/master/config/routes.rb"
    click BaseCtrl "https://github.com/ankane/ahoy/blob/master/app/controllers/ahoy/base_controller.rb"
    click VisitsCtrl "https://github.com/ankane/ahoy/blob/master/app/controllers/ahoy/visits_controller.rb"
    click EventsCtrl "https://github.com/ankane/ahoy/blob/master/app/controllers/ahoy/events_controller.rb"
    click Tracker "https://github.com/ankane/ahoy/blob/master/lib/ahoy/tracker.rb"
    click CtrlHelper "https://github.com/ankane/ahoy/blob/master/lib/ahoy/controller.rb"
    click ModelMixin "https://github.com/ankane/ahoy/blob/master/lib/ahoy/model.rb"
    click VisitProps "https://github.com/ankane/ahoy/blob/master/lib/ahoy/visit_properties.rb"
    click QueryMethods "https://github.com/ankane/ahoy/blob/master/lib/ahoy/query_methods.rb"
    click BaseStore "https://github.com/ankane/ahoy/blob/master/lib/ahoy/base_store.rb"
    click DBStore "https://github.com/ankane/ahoy/blob/master/lib/ahoy/database_store.rb"
    click GeocodeJob "https://github.com/ankane/ahoy/blob/master/lib/ahoy/geocode_v2_job.rb"
    click GenBase "https://github.com/ankane/ahoy/blob/master/lib/generators/ahoy/base_generator.rb"
    click ARGen "https://github.com/ankane/ahoy/blob/master/lib/generators/ahoy/activerecord_generator.rb"
    click MongoGen "https://github.com/ankane/ahoy/blob/master/lib/generators/ahoy/mongoid_generator.rb"
    click InstallGen "https://github.com/ankane/ahoy/blob/master/lib/generators/ahoy/install_generator.rb"
    click Templates "https://github.com/ankane/ahoy/tree/master/lib/generators/ahoy/templates/"
    click Version "https://github.com/ankane/ahoy/blob/master/lib/ahoy/version.rb"
    click Version "https://github.com/ankane/ahoy/blob/master/ahoy_matey.gemspec"

    %% Styles
    classDef client fill:#AEDFF7,stroke:#0366d6,color:#0366d6;
    classDef host fill:#E0E0E0,stroke:#888888,color:#333333;
    classDef engine fill:#D5F5E3,stroke:#27AE60,color:#117A37;
    classDef store fill:#FAD7A0,stroke:#D35400,color:#873600;
    classDef job fill:#E8DAEF,stroke:#8E44AD,color:#5B2C6F;
    classDef external fill:#F5B7B1,stroke:#C0392B,color:#641E16;
```
