Architecture Overview

Understanding Gonzo's architecture helps you extend it, contribute to it, or integrate it into your systems. This page provides a high-level overview of how Gonzo is structured.

High-Level Architecture

Gonzo follows a clean, modular architecture with clear separation of concerns:

┌─────────────────────────────────────────────────┐
│                   CLI Layer                     │
│            (cmd/gonzo - Entry Point)            │
└─────────────────┬───────────────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    │             │             │
    ▼             ▼             ▼
┌─────────┐  ┌─────────┐  ┌──────────┐
│  Input  │  │   TUI   │  │   AI     │
│ Sources │  │ Engine  │  │ Engine   │
└────┬────┘  └────┬────┘  └────┬─────┘
     │            │            │
     │       ┌────▼────┐       │
     └──────►│Analyzer │◄──────┘
             │ Engine  │
             └────┬────┘
                  │
             ┌────▼────┐
             │ Memory  │
             │ Store   │
             └─────────┘

Directory Structure

gonzo/
├── cmd/
│   └── gonzo/          # Application entry point
│       └── main.go     # CLI initialization
│
├── internal/           # Private application code
│   ├── tui/           # Terminal UI implementation
│   │   ├── model.go   # Bubble Tea model
│   │   ├── view.go    # UI rendering
│   │   └── update.go  # Event handling
│   │
│   ├── analyzer/      # Log analysis engine
│   │   ├── parser.go  # Format detection & parsing
│   │   ├── filter.go  # Filtering logic
│   │   └── stats.go   # Statistical analysis
│   │
│   ├── memory/        # Frequency tracking & storage
│   │   ├── buffer.go  # Log buffer management
│   │   └── freq.go    # Word frequency tracking
│   │
│   ├── otlplog/       # OTLP format handling
│   │   ├── receiver.go # OTLP receiver server
│   │   ├── grpc.go    # gRPC handler
│   │   └── http.go    # HTTP handler
│   │
│   └── ai/            # AI integration
│       ├── client.go   # OpenAI client
│       ├── provider.go # Multi-provider support
│       └── analysis.go # Analysis logic
│
├── examples/          # Example configs & formats
│   ├── config.yaml    # Sample configuration
│   ├── formats/       # Custom format definitions
│   └── send_otlp_logs.py # OTLP example
│
├── docs/             # Documentation
└── tests/            # Test files

Core Components

1. CLI Layer (cmd/gonzo)

Purpose: Application entry point and command-line interface.

Responsibilities:

• Parse command-line arguments using Cobra

• Load configuration from files and environment

• Initialize and start the TUI or OTLP receiver

• Handle graceful shutdown

Key Files:

• main.go - Entry point

• root.go - Root command definition

• version.go - Version command

2. TUI Engine (internal/tui)

Purpose: Terminal user interface using Bubble Tea framework.

Responsibilities:

• Render the 2x2 dashboard layout

• Handle keyboard and mouse input

• Update UI in response to events

• Manage focus and navigation

Architecture Pattern: Model-View-Update (MVU/Elm architecture)

Key Components:

type Model struct {
    logViewer    viewport.Model
    wordFreq     table.Model
    attributes   list.Model
    counts       statsModel
    focusIndex   int
    paused       bool
}

func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd)
func (m Model) View() string

Styling: Uses Lipgloss for colors, borders, and layout.

3. Analyzer Engine (internal/analyzer)

Purpose: Core log processing and analysis.

Responsibilities:

• Detect log format (JSON, logfmt, plain text)

• Parse logs into structured format

• Extract attributes and severity

• Apply filters and search patterns

• Generate statistics

Key Algorithms:

• Format Detection: Heuristic-based per-line detection

• Pattern Extraction: Uses drain3 algorithm for pattern mining

• Severity Extraction: Keyword matching and field extraction

Flow:

Raw Log → Format Detection → Parser → Structured Log → Analyzer → Stats

4. Memory Store (internal/memory)

Purpose: Efficient in-memory storage and tracking.

Responsibilities:

• Buffer recent logs (circular buffer)

• Track word frequencies

• Maintain attribute counts

• Manage memory limits

Data Structures:

• Log Buffer: Ring buffer (default 1000 entries)

• Word Frequency: Hash map with LRU eviction (default 10,000 words)

• Attribute Store: Nested maps for fast lookup

Memory Management:

• Configurable buffer sizes

• Automatic eviction of old data

• Optimized for real-time streaming

5. OTLP Handler (internal/otlplog)

Purpose: OpenTelemetry Protocol log receiver.

Responsibilities:

• Run gRPC server (port 4317)

• Run HTTP server (port 4318)

• Accept OTLP log data

• Convert to internal log format

• Feed to analyzer engine

Protocol Support:

• gRPC: Full OTLP logs specification

• HTTP: OTLP/HTTP with JSON encoding

• Both: Resource and log record attributes

Architecture:

OTLP Client → [gRPC/HTTP] → OTLP Receiver → Log Converter → Analyzer

6. AI Integration (internal/ai)

Purpose: AI-powered log analysis.

Responsibilities:

• Connect to AI providers (OpenAI, Ollama, LM Studio)

• Send log context for analysis

• Parse AI responses

• Manage chat conversations

Provider Support:

• OpenAI API

• OpenAI-compatible APIs

• Local models (Ollama, LM Studio)

• Automatic model selection

Integration Points:

• Instant analysis (i key)

• Chat mode (c key)

• Model switching (m key)

Data Flow

Log Ingestion Flow

Input Source
    ↓
┌───────────────────────┐
│  File / Stdin / OTLP  │
└───────┬───────────────┘
        ↓
┌───────────────────────┐
│  Format Detection     │
│  (JSON/logfmt/text)   │
└───────┬───────────────┘
        ↓
┌───────────────────────┐
│  Parser               │
│  (Extract fields)     │
└───────┬───────────────┘
        ↓
┌───────────────────────┐
│  Analyzer             │
│  (Stats, patterns)    │
└───────┬───────────────┘
        ↓
┌───────────────────────┐
│  Memory Store         │
│  (Buffer, frequency)  │
└───────┬───────────────┘
        ↓
┌───────────────────────┐
│  TUI Update           │
│  (Render dashboard)   │
└───────────────────────┘

User Interaction Flow

User Input (keyboard/mouse)
    ↓
┌───────────────────────┐
│  TUI Event Handler    │
└───────┬───────────────┘
        ↓
┌───────────────────────┐
│  Action Processor     │
│  (filter, pause, etc) │
└───────┬───────────────┘
        ↓
┌───────────────────────┐
│  State Update         │
└───────┬───────────────┘
        ↓
┌───────────────────────┐
│  UI Re-render         │
└───────────────────────┘

AI Analysis Flow

User selects log + presses 'i'
    ↓
┌───────────────────────┐
│  Extract Log Context  │
└───────┬───────────────┘
        ↓
┌───────────────────────┐
│  Format Prompt        │
└───────┬───────────────┘
        ↓
┌───────────────────────┐
│  Send to AI Provider  │
└───────┬───────────────┘
        ↓
┌───────────────────────┐
│  Parse Response       │
└───────┬───────────────┘
        ↓
┌───────────────────────┐
│  Display in Modal     │
└───────────────────────┘

Key Design Patterns

1. Model-View-Update (MVU)

The TUI uses Bubble Tea's MVU pattern:

// Model: Application state
type Model struct { ... }

// Update: State transitions
func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { ... }

// View: Render current state
func (m Model) View() string { ... }

Benefits:

• Predictable state management

• Easy testing

• Clear separation of concerns

2. Plugin Architecture

Custom formats are pluggable:

# formats/my-format.yaml
name: my-format
pattern: '(\d+) (\w+) (.+)'
fields:
  - timestamp
  - level
  - message

Benefits:

• Extend without code changes

• Community-contributed formats

• Easy testing of parsers

3. Streaming Pipeline

Logs flow through processing pipeline:

input → detect → parse → analyze → store → display

Benefits:

• Real-time processing

• Low memory footprint

• Handles unlimited log streams

4. Provider Abstraction

AI providers implement common interface:

type Provider interface {
    Analyze(log Log) (string, error)
    Chat(messages []Message) (string, error)
    ListModels() ([]Model, error)
}

Benefits:

• Easy to add new providers

• Swap providers at runtime

• Consistent API

Technology Stack

Core Framework

• Bubble Tea - TUI framework (MVU pattern)

• Lipgloss - Styling and layout

• Bubbles - Reusable TUI components

CLI & Configuration

• Cobra - CLI framework

• Viper - Configuration management

Protocols & APIs

• OpenTelemetry - OTLP protocol implementation

• gRPC - For OTLP gRPC receiver

• HTTP/JSON - For OTLP HTTP receiver

Log Processing

• drain3 - Pattern extraction algorithm

• regex - Format parsing

• Standard library - JSON, text processing

AI Integration

• OpenAI API - Primary AI provider

• HTTP client - For API calls

• JSON - Request/response format

Performance Considerations

Memory Management

Bounded Buffers:

• Log buffer: Default 1000 entries (configurable)

• Word frequency: Default 10,000 words (configurable)

• Automatic eviction prevents unlimited growth

Efficient Storage:

• Circular buffers for logs

• Hash maps for fast lookup

• Lazy evaluation where possible

CPU Optimization

Incremental Processing:

• Process logs as they arrive

• Update statistics incrementally

• Avoid re-processing entire dataset

Configurable Update Rate:

• Dashboard updates: Default 1 second (configurable)

• Reduces CPU for high-volume logs

Network Efficiency

OTLP Receiver:

• Batched processing

• Efficient protobuf serialization

• Concurrent request handling

AI Requests:

• Single requests (not streamed currently)

• Reusable HTTP connections

• Configurable timeouts

Extension Points

Gonzo is designed to be extended in several ways:

1. Custom Formats - Add new log format parsers

2. Custom Skins - Create new color schemes

3. AI Providers - Integrate new AI services

4. Input Sources - Add new log sources

5. Export Formats - Add new export options

See Extension Points for detailed information.

Testing Strategy

Unit Tests:

• Parser logic

• Analyzer algorithms

• Format detection

Integration Tests:

• End-to-end log processing

• OTLP receiver

• File input handling

Manual Testing:

• TUI interactions

• Visual regressions

• Performance with large datasets

Building & Development

Build Process

# Development build
make build

# All platforms
make cross-build

# With tests
make dev

Development Mode

# Format, vet, test, build
make dev

# Run tests
make test

# Race detection
make test-race

Release Process

1. Version bump in code

2. Update CHANGELOG.md

3. Create Git tag

4. GitHub Actions builds binaries

5. Publish to releases page

Related Documentation

• OTLP Protocol Details - Deep dive into OTLP implementation

• Extension Points - How to extend Gonzo

• Contributing Guide - How to contribute

Want to contribute? Check the Contributing Guide and Development Setup to get started!