# 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**:

```go
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:

```go
// 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:

```yaml
# 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:

```go
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:

```go
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**](https://github.com/charmbracelet/bubbletea) - TUI framework (MVU pattern)
* [**Lipgloss**](https://github.com/charmbracelet/lipgloss) - Styling and layout
* [**Bubbles**](https://github.com/charmbracelet/bubbles) - Reusable TUI components

#### CLI & Configuration

* [**Cobra**](https://github.com/spf13/cobra) - CLI framework
* [**Viper**](https://github.com/spf13/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

```bash
# Development build
make build

# All platforms
make cross-build

# With tests
make dev
```

#### Development Mode

```bash
# 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

{% hint style="info" %}
**Want to contribute?** Check the Contributing Guide and Development Setup to get started!
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.controltheory.com/backup/api-and-architecture/architecture-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.