Project Overview

An open-source ad server built in Go, with OpenRTB compatibility and a pluggable architecture for custom ad selection logic.

Architecture Overview

Component	Technology	Purpose
API Layer	internal/api	REST handlers for ad requests and management
Selection Logic	internal/logic	Pluggable ad selection and filtering algorithms
Data Layer	internal/db	Database models and access patterns
Configuration	PostgreSQL	Campaign and line item storage
Operational Data	Redis	Real-time counters and rate limiting
Analytics	ClickHouse	Event tracking and reporting

Key Features

Feature	Description
Publisher Control	Pluggable ad selection logic, custom targeting, dual-counter pacing
Multi-Format Ad Support	HTML, banner (server-composed with responsive images), and native formats
Quality Control	Built-in ad reporting system for content moderation
Analytics	ClickHouse storage, Prometheus metrics, custom event tracking
Integration	JavaScript SDK, server-to-server API, traffic simulator

Technical Implementation

OpenAdServe demonstrates modern ad server architecture through clean, production-quality code:

Ad Selection Logic: Rule-based filtering with pluggable selector patterns and optimized single-pass performance Campaign Pacing: Dual-counter systems for budget and impression distribution Real-time Decisions: Sub-100ms ad serving with caching and optimization Data Architecture: Multi-store patterns for configuration, counters, and analytics Integration Patterns: SDK design and server-to-server API structures Quality Control: User reporting and content moderation workflows

Target Audience

Audience	Use Case
Publishers	Small to medium publishers needing full control over ad serving logic and revenue optimization
Engineers	Developers building custom ad tech or extending existing infrastructure with modern Go patterns
Product Managers	Technical PMs evaluating capabilities, understanding complexity, making build vs. buy decisions

Project Scope

What this provides:

• Production-ready ad server for small to medium publishers
• Complete control over ad selection algorithms and targeting
• Foundation to build custom ad tech solutions
• Real alternative to black-box platforms

What this is NOT:

• Horizontally scalable distributed system (single-instance design)
• Enterprise solution for large publishers with massive scale
• Drop-in replacement for Google Ad Manager

See limitations.md for detailed constraints and production considerations.

Customizable Ad Selection

Implement the selectors.Selector interface to create custom ad selection logic. The default RuleBasedSelector uses an optimized single-pass filter for maximum performance while maintaining standard targeting and pacing.

Filter Implementations (internal/logic/filters):

Recommended:

• SinglePassFilter - Production-optimized implementation combining all criteria (3x faster, lower memory)

Individual Filters (for custom composition):

• FilterByTargeting - Device, geo, registered dimensions, custom key-values
• FilterBySize - Creative dimensions and format compatibility
• FilterByActive - Line item status
• FilterByFrequency - User exposure limits (requires Redis)
• FilterByPacing - Daily delivery caps and dual-counter distribution (requires Redis)

Use SinglePassFilter for production deployments. Individual filters are available for custom selector implementations or performance testing.