# hillfolk/go-ga4-to-bigquery architecture

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

- Interactive diagram: https://gitdiagram.com/hillfolk/go-ga4-to-bigquery
- Repository: https://github.com/hillfolk/go-ga4-to-bigquery

## Overview

##### Main Components

a) External Services Layer:
- Google Analytics 4 (GA4) API
- Google BigQuery API

b) Application Core:
- CLI Interface
- Report Engine
- Service Connectors

c) Report Types Module:
- All supported report implementations

##### Input/Configuration Flow
- To the CLI interface (cmd package)
- Flow into the application core (internal/app.go)

##### Data Flow
- Data transformation in Report Engine
- Data storage flow to BigQuery

##### Report Implementation Structure
- It to the main Report Engine

Use this specific layout:

**┌─────────────────────────────────────────────────────────┐**
- External Services                      │

- ┌─────────────┐                  ┌──────────────┐    │
- GA4     │                  │   BigQuery   │    │
- ┘                  └──────────────┘    │
- ┘
- ▲                           ▼

**┌───────────────────────────────────────────────────────┐**
- Application Core                      │
- ┌──────────┐    ┌─────────────┐    ┌────────────┐   │
- CLI    │─-->│   Report    │─-->│  Service   │   │
- Interface │    │   Engine    │    │ Connectors │   │
- ┘    └─────────────┘    └────────────┘   │

- ┘
- ▼
**┌───────────────────────────────────────────────────────┐**
- Report Implementations                   │
- ┌─────────────┐ ┌────────────┐ ┌──────────────────┐ │
- Active    │ │   Events   │ │  User Channel    │ │
- Users     │ │            │ │    Grouping      │ │
- ┘ └────────────┘ └──────────────────┘ │
- ┌─────────────┐ ┌────────────────────────────────┐  │
- User     │ │         Cross Channel          │  │
- Technology  │ │                                │  │
- ┘ └────────────────────────────────┘  │
- ┘

- Use blue for external services
- Use green for application core components
- Use yellow for report implementations

Important Elements to Highlight:

##### Configuration
- Config.json input point
- Authentication flow for Google services

##### Service Interfaces
- GA4 API integration points
- BigQuery data insertion points

##### Report Engine
- Abstraction layer (internal/reports/reports.go)
- Connection to individual report implementations

##### Data Flow
- Async operations if any
- Data transformation points
- Error handling paths

Additional Notes:
- Version/requirement information (Go 1.16+)
- External dependencies (Google Cloud SDK)
- Configuration requirements (API enablement, permissions)

- External service integration
- Core application logic
- Report implementation details
- Configuration and setup requirements

This will provide a clear understanding of how the application interfaces with Google services and processes different types of analytics reports.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services Layer
    subgraph ExternalServices["External Services"]
        GA4["GA4 API"]:::external
        BQ["BigQuery API"]:::external
    end

    %% Application Core Layer
    subgraph AppCore["Application Core"]
        Config["Configuration JSON"]:::config
        click Config "https://github.com/hillfolk/go-ga4-to-bigquery/blob/main/sample-config.json"
        
        CLI["CLI Interface"]:::core
        click CLI "https://github.com/hillfolk/go-ga4-to-bigquery/blob/main/cmd/root.go"
        
        ReportEngine["Report Engine"]:::core
        click ReportEngine "https://github.com/hillfolk/go-ga4-to-bigquery/blob/main/internal/reports/reports.go"
        
        ServiceConnectors["Service Connectors"]:::core
        GA4Connector["GA4 Connector"]:::connector
        click GA4Connector "https://github.com/hillfolk/go-ga4-to-bigquery/blob/main/internal/ga4.go"
        BQConnector["BigQuery Connector"]:::connector
        click BQConnector "https://github.com/hillfolk/go-ga4-to-bigquery/blob/main/internal/bigquery.go"
        
        ServiceConnectors --> GA4Connector
        ServiceConnectors --> BQConnector
    end

    %% Report Implementations Layer
    subgraph ReportImpl["Report Implementations"]
        ActiveUsers["Active Users Report"]:::report
        click ActiveUsers "https://github.com/hillfolk/go-ga4-to-bigquery/blob/main/internal/reports/impl/report_active_users.go"
        
        Events["Events Report"]:::report
        click Events "https://github.com/hillfolk/go-ga4-to-bigquery/blob/main/internal/reports/impl/report_events.go"
        
        UserChannel["User Channel Grouping Report"]:::report
        click UserChannel "https://github.com/hillfolk/go-ga4-to-bigquery/blob/main/internal/reports/impl/report_user_channel_grouping.go"
        
        UserTech["User Technology Report"]:::report
        click UserTech "https://github.com/hillfolk/go-ga4-to-bigquery/blob/main/internal/reports/impl/report_user_technology.go"
        
        CrossChannel["Cross Channel Report"]:::report
        click CrossChannel "https://github.com/hillfolk/go-ga4-to-bigquery/blob/main/internal/reports/impl/report_cross_channel.go"
    end

    %% Connections
    Config --> CLI
    CLI --> ReportEngine
    ReportEngine --> ServiceConnectors
    GA4Connector --> GA4
    BQConnector --> BQ
    ReportEngine --> ReportImpl
    
    %% Styles
    classDef external fill:#a8d1f0,stroke:#333,stroke-width:2px
    classDef core fill:#b7e3c0,stroke:#333,stroke-width:2px
    classDef connector fill:#d4e3b7,stroke:#333,stroke-width:2px
    classDef report fill:#ffe0b2,stroke:#333,stroke-width:2px
    classDef config fill:#e1bee7,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        L1["External Services"]:::external
        L2["Core Components"]:::core
        L3["Service Connectors"]:::connector
        L4["Report Types"]:::report
        L5["Configuration"]:::config
    end
```
