# labidalarfin/ad-decision-engine architecture

> Architecture diagram of the GitHub repository labidalarfin/ad-decision-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/labidalarfin/ad-decision-engine
- Repository: https://github.com/labidalarfin/ad-decision-engine

## Overview

This repository implements a real-time ad-serving service: an HTTP ad request is parsed and validated, campaign candidates are selected and filtered, bids are scored and auctioned, and a response can include signed tracking URLs. Supporting capabilities include catalog refresh, budgets, pacing, frequency caps, user segments, event processing, and observability. The README is empty, and several runtime implementations were not excerpted; dashed links mark important workflow relationships that the available evidence cannot verify directly.

Main entry points: [`src/app/app.h`](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/app/app.h) (Application), [`src/core/decision_engine.cpp`](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/core/decision_engine.cpp) (Decision Engine), [`src/server/ad_request_handler.cpp`](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/server/ad_request_handler.cpp) (Ad Request Handler), [`src/state/runtime_state.cpp`](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/state/runtime_state.cpp) (Runtime Controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Ad Serving"]
  node_app["Application<br/>[app.h]"]
  node_http["HTTP Server<br/>[http_server.cpp]"]
  node_handler["Ad Request Handler"]
  node_engine["Decision Engine"]
  node_model["Ad Domain Model<br/>[model.h]"]
end

subgraph group_campaign["Campaign Selection"]
  node_catalog["Catalog Snapshots<br/>[catalog.cpp]"]
  node_pipeline["Candidate Filters<br/>[pipeline.cpp]"]
  node_scoring["Scoring and Auctions<br/>[scoring.cpp]"]
end

subgraph group_state["Runtime State"]
  node_runtime["Runtime Controls<br/>[runtime_state.cpp]"]
  node_redis["Redis Client<br/>[redis_client.cpp]"]
end

subgraph group_signals["Events and Observability"]
  node_events["Event Processing<br/>[events.cpp]"]
  node_observability["Tracing and Metrics<br/>[observability.cpp]"]
  node_ctr["CTR Statistics<br/>[scoring.cpp]"]
end

subgraph group_foundation["Shared Foundations"]
  node_crypto["URL Signing<br/>[crypto.cpp]"]
  node_json["JSON Handling<br/>[json.cpp]"]
  node_network["TCP Networking<br/>[net.cpp]"]
  node_containers["Shared Containers<br/>[containers.h]"]
end

node_requester(("Ad Requester"))

node_requester -.->|"sends request"| node_http
node_http -.->|"routes request"| node_handler
node_handler -.->|"requests decision"| node_engine
node_handler -.->|"parses payload"| node_json
node_handler -.->|"signs tracking URLs"| node_crypto
node_engine -.->|"reads snapshot"| node_catalog
node_engine -.->|"filters candidates"| node_pipeline
node_engine -.->|"scores and auctions"| node_scoring
node_engine -.->|"loads user context"| node_runtime
node_catalog -.->|"builds campaign data"| node_model
node_pipeline -.->|"checks serving limits"| node_runtime
node_scoring -.->|"reads CTR estimates"| node_ctr
node_events -.->|"updates statistics"| node_ctr
node_runtime -.->|"reads and writes state"| node_redis
node_redis -.->|"uses TCP"| node_network
node_app -->|"owns server"| node_http
node_app -->|"owns handler"| node_handler
node_app -->|"owns engine"| node_engine
node_app -->|"owns snapshots"| node_catalog
node_app -->|"owns state managers"| node_runtime
node_app -->|"owns event processing"| node_events
node_app -->|"owns instrumentation"| node_observability

click node_app "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/app/app.h"
click node_http "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/server/http_server.cpp"
click node_handler "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/server/ad_request_handler.cpp"
click node_engine "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/core/decision_engine.cpp"
click node_model "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/domain/model.h"
click node_catalog "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/catalog/catalog.cpp"
click node_pipeline "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/pipeline/pipeline.cpp"
click node_scoring "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/scoring/scoring.cpp"
click node_runtime "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/state/runtime_state.cpp"
click node_redis "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/state/redis_client.cpp"
click node_events "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/events/events.cpp"
click node_observability "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/observability/observability.cpp"
click node_ctr "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/scoring/scoring.cpp"
click node_crypto "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/common/crypto.cpp"
click node_json "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/common/json.cpp"
click node_network "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/common/net.cpp"
click node_containers "https://github.com/labidalarfin/ad-decision-engine/blob/main/src/common/containers.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_http,node_handler,node_engine,node_model toneBlue
class node_catalog,node_pipeline,node_scoring toneAmber
class node_runtime,node_redis,node_requester toneMint
class node_events,node_observability,node_ctr toneRose
class node_crypto,node_json,node_network,node_containers toneIndigo
```

## Components

### Ad Serving

- [Application](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/app/app.h): `src/app/app.h`
- [HTTP Server](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/server/http_server.cpp): `src/server/http_server.cpp`
- [Ad Request Handler](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/server/ad_request_handler.cpp): `src/server/ad_request_handler.cpp`
- [Decision Engine](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/core/decision_engine.cpp): `src/core/decision_engine.cpp`
- [Ad Domain Model](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/domain/model.h): `src/domain/model.h`

### Campaign Selection

- [Catalog Snapshots](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/catalog/catalog.cpp): `src/catalog/catalog.cpp`
- [Candidate Filters](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/pipeline/pipeline.cpp): `src/pipeline/pipeline.cpp`
- [Scoring and Auctions](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/scoring/scoring.cpp): `src/scoring/scoring.cpp`

### Runtime State

- [Runtime Controls](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/state/runtime_state.cpp): `src/state/runtime_state.cpp`
- [Redis Client](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/state/redis_client.cpp): `src/state/redis_client.cpp`

### Events and Observability

- [Event Processing](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/events/events.cpp): `src/events/events.cpp`
- [Tracing and Metrics](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/observability/observability.cpp): `src/observability/observability.cpp`
- [CTR Statistics](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/scoring/scoring.cpp): `src/scoring/scoring.cpp`

### Shared Foundations

- [URL Signing](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/common/crypto.cpp): `src/common/crypto.cpp`
- [JSON Handling](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/common/json.cpp): `src/common/json.cpp`
- [TCP Networking](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/common/net.cpp): `src/common/net.cpp`
- [Shared Containers](https://github.com/labidalarfin/ad-decision-engine/blob/main/src/common/containers.h): `src/common/containers.h`

### Other components

- **Ad Requester**

## Connections

- Ad Requester → HTTP Server: sends request
- HTTP Server → Ad Request Handler: routes request
- Ad Request Handler → Decision Engine: requests decision
- Ad Request Handler → JSON Handling: parses payload
- Ad Request Handler → URL Signing: signs tracking URLs
- Decision Engine → Catalog Snapshots: reads snapshot
- Decision Engine → Candidate Filters: filters candidates
- Decision Engine → Scoring and Auctions: scores and auctions
- Decision Engine → Runtime Controls: loads user context
- Catalog Snapshots → Ad Domain Model: builds campaign data
- Candidate Filters → Runtime Controls: checks serving limits
- Scoring and Auctions → CTR Statistics: reads CTR estimates (evidence: `src/scoring/scoring.cpp`)
- Event Processing → CTR Statistics: updates statistics
- Runtime Controls → Redis Client: reads and writes state
- Redis Client → TCP Networking: uses TCP
- Application → HTTP Server: owns server (evidence: `src/app/app.h`)
- Application → Ad Request Handler: owns handler (evidence: `src/app/app.h`)
- Application → Decision Engine: owns engine (evidence: `src/app/app.h`)
- Application → Catalog Snapshots: owns snapshots (evidence: `src/app/app.h`)
- Application → Runtime Controls: owns state managers (evidence: `src/app/app.h`)
- Application → Event Processing: owns event processing (evidence: `src/app/app.h`)
- Application → Tracing and Metrics: owns instrumentation (evidence: `src/app/app.h`)
