TG logo
Back to Projects

ad_simulator

Modular advertising stack simulating real-time bidding, semantic campaign matching, cache-backed decisioning, and observability with Prometheus and Grafana.

ad_simulator

A professional advertising platform simulation that combines a real-time bidding engine, semantic campaign matching, caching, analytics, and observability.

This repository contains a .NET-based mini ad-server and bidding stack built for experimentation, training, and prototype deployments.

Project Summary

ad_simulator is a modular backend system that simulates a modern advertising infrastructure with the following capabilities:

  • Real-time bid evaluation and winning campaign selection
  • PostgreSQL-backed campaign and video storage with pgvector support for embeddings
  • Redis caching for fast campaign lookup and budget management
  • Metrics and observability through Prometheus and Grafana
  • Optional event-driven pipeline support with Kafka
  • A simple Node/Express frontend for service demonstration

Architecture Overview

The core system is built around a microservices pattern with the following components:

  • src/BidEngine - The primary bid evaluation service and API layer
  • src/Shared - Shared domain models used by services across the repository
  • tests/BidEngine.Tests - Unit tests for the bid engine behavior
  • FrontEnd - Lightweight Express frontend that consumes the bid engine API
  • infrastructure/database/migrations - SQL migration scripts for PostgreSQL and pgvector
  • docs/ - Supporting documentation for architecture, API, deployment, and operations

Primary Service Responsibilities

  • BidEngine handles requests for bidding, active campaign selection, budget deduction, and vectorized semantic matching.
  • Shared contains cross-service models such as BidRequest, Campaign, and Video.
  • FrontEnd provides a frontend demo interface and can be extended for interactive testing.

Technologies Used

  • .NET 9 / ASP.NET Core
  • Entity Framework Core 9
  • PostgreSQL with pgvector
  • Redis for caching and transient budget state
  • Prometheus for metrics collection
  • Grafana for dashboarding
  • Docker Compose for environment orchestration
  • Node.js + Express + EJS for the frontend demo
  • Optional Kafka for event streaming

Why This Project

ad_simulator showcases how real-time advertising decisioning can be designed with observability and privacy in mind. The system is optimized for local experimentation, allowing developers to test bidding logic, semantic campaign matching, and caching strategies without a production ad platform.

Quick Start

Local development with Docker

git clone https://github.com/<your-org>/ad_simulator.git
cd ad_simulator
docker compose up -d

Service endpoints

  • Bid Engine: http://localhost:8081
  • Frontend UI: http://localhost:3001
  • Prometheus: http://localhost:9090
  • Grafana: http://localhost:3000

Key Differentiators

  • Semantic campaign matching using embeddings for relevance ranking
  • Cache-first bidding logic for low-latency ad selection
  • Observability-first design with metrics and dashboards from day one
  • Modular microservice layout that separates bidding, storage, and front-end demos