Antes del Código, Existe un Dominio

La publicidad digital impulsa gran parte de la internet moderna. Detrás de cada banner, promoción en barra lateral o listado patrocinado existe un sistema de gestión de campañas: software que decide qué anuncio mostrar, a quién y cuándo. Estos sistemas no son exclusivos de Google o Meta. Cualquier producto que venda espacio publicitario, promueva contenido interno o gestione colocaciones de afiliados necesita las mismas abstracciones fundamentales.

Esta serie explora la arquitectura de un sistema dinámico completo de campañas publicitarias en SvelteKit. A lo largo de siete artículos, verás cómo el modelado de dominio, las interfaces de gestión, los pipelines de resolución de anuncios, los análisis en tiempo real, las pruebas A/B y el control de presupuesto encajan en un diseño orientado a producción. El código incluido es ilustrativo, diseñado para enseñar los patrones y las concesiones, no para copiarse literalmente en un proyecto.

Este primer artículo sienta las bases: el dominio, el modelo de datos, el esquema de la base de datos y la estructura del proyecto de la que depende el resto de la serie.

This is Part 1 of 7 in the Ad Campaign Architecture series:

Foundations (you are here) - Domain modeling, schema design, project structure
Campaign CRUD - Form action patterns, validation, status machines
The Rendering Engine - Targeting pipeline, weighted selection, ad serving
Real-Time Dashboard - Event tracking, SSE streaming, live metrics
A/B Testing & Optimization - Traffic splitting, statistical significance
Budget & Scheduling - Pacing algorithms, lifecycle automation
Production Hardening - Database indexing, Redis caching, rate limiting, GDPR

Para Qué Sirve Realmente Esta Arquitectura

Antes de profundizar en el dominio, vale la pena ser directo sobre el contexto en el que este sistema tiene sentido y el contexto en el que no lo tiene. La publicidad web ha cambiado considerablemente en la última década, y construir un sistema de anuncios hoy sin entender ese panorama es construir sin mapa.

La realidad más destacada es que una parte significativa de los usuarios nunca ve anuncios web en absoluto. La adopción de bloqueadores de anuncios en escritorio se sitúa entre el 30 y el 45 por ciento dependiendo de la encuesta, y entre audiencias de desarrolladores y técnicas (exactamente la audiencia a la que se dirige este sitio) ese número es de entre el 60 y el 70 por ciento. Esto no va a desaparecer.

La protección de rastreo a nivel del navegador, la Prevención Inteligente de Rastreo de Safari, los valores predeterminados de privacidad mejorada de Firefox y la aplicación propia de Chrome de la Coalición para Mejores Anuncios han erosionado la infraestructura de la que depende la publicidad programática de terceros. El acuerdo implícito que impulsó gran parte de la web —contenido gratuito a cambio de visualizaciones de anuncios— está roto por un lado. Las visualizaciones no están ocurriendo.

A esto se suma la capa legal. El RGPD en Europa y el CPRA en California requieren el consentimiento explícito del usuario antes de recopilar datos de comportamiento para publicidad. Las tasas de consentimiento en los mercados europeos para el rastreo personalizado suelen oscilar entre el 30 y el 60 por ciento dependiendo de cómo esté diseñado el banner de consentimiento. Si tus usuarios son globales, perderás la mayoría de tu inventario europeo potencial antes de servir una sola impresión.

Entonces, ¿por qué existe esta serie?

Por dos razones. Primero, los patrones en esta arquitectura se transfieren mucho más allá de la publicidad con banners. Un sistema que resuelve qué creatividad mostrar basándose en el dispositivo, la ubicación, el horario, la frecuencia y el presupuesto es el mismo sistema que impulsa los feature flags con targeting, las recomendaciones de contenido personalizado, las pruebas A/B en cualquier elemento de página, las promociones internas y los reconocimientos de patrocinadores. El modelo de dominio y el pipeline de resolución que construyes aquí son genuinamente reutilizables.

Segundo, la publicidad de primera parte para audiencias especializadas aún funciona. Los formatos que se sostienen son contextualmente relevantes, no intrusivos, renderizados en el servidor (sin saltos de diseño, sin destellos de contenido asíncrono) y claramente etiquetados. Los patrocinios directos de empresas cuyos productos la audiencia realmente usa —como herramientas para desarrolladores, servicios de infraestructura y libros técnicos— producen tasas de clics un orden de magnitud más altas que el inventario genérico de display, precisamente porque la coincidencia entre audiencia y oferta es real en lugar de inferida a partir de datos de vigilancia.

Este sitio usa una versión de este sistema. La arquitectura en esta serie no es hipotética. Las colocaciones de patrocinios se resuelven en el servidor basándose en el contexto de la página, se sirven sin dependencias de rastreo de JavaScript y se miden usando análisis de primera parte que no requieren cookies de terceros.

La historia del consentimiento es sencilla: límites de frecuencia con alcance de sesión, sin rastreo entre sitios, sin datos personales vendidos a terceros. El problema de los bloqueadores de anuncios se reduce considerablemente cuando el anuncio no es distinguible del contexto editorial por las heurísticas que usan los bloqueadores, y cuando el contenido que lo rodea vale la pena leer.

El sistema vale más la pena construirlo si eres dueño de tu inventario y tienes una relación directa con tus patrocinadores. Vale menos la pena construirlo si tu plan es conectarte a un exchange programático y vender inventario remanente (espacio publicitario no vendido) a $0.50 CPM. Esta serie está diseñada para el primer caso.

Entremos al dominio.

El Dominio: Cómo Funcionan los Sistemas de Anuncios

Antes de escribir cualquier código, necesitas un modelo mental claro de cómo operan los sistemas de campañas publicitarias. Incluso si nunca has trabajado en ad tech, los conceptos se corresponden claramente con problemas que ya has resuelto —catálogos de productos, gestión de contenido, feature flags. El vocabulario es diferente, pero los patrones son familiares.

La Jerarquía

Todo sistema de anuncios organiza sus datos en una jerarquía. La profundidad exacta varía según la plataforma, pero la estructura central es notablemente consistente en toda la industria:

Definamos cada nivel con precisión:

Anunciante - La entidad que paga por los anuncios. En una plataforma de autoservicio, es un negocio registrado. En un sistema interno, podría ser un departamento o equipo de producto. Cada campaña pertenece a un anunciante.

Campaña - Una iniciativa de marketing con un objetivo, presupuesto y marco temporal definidos. "Venta de Verano 2026" o "Lanzamiento de Nueva Función" son campañas. Una campaña agrupa ad groups relacionados bajo un presupuesto y calendario compartidos.

Ad Group - Una estrategia de targeting dentro de una campaña. Una campaña puede tener un ad group dirigido a usuarios móviles en Europa y otro dirigido a usuarios de escritorio en Norteamérica. Los ad groups controlan quién ve los anuncios y dónde aparecen.

Creatividad - El contenido real que se muestra al usuario: una imagen, un bloque de texto, un fragmento HTML o un video. Cada ad group puede tener múltiples creatividades, lo que permite pruebas A/B y rotación.

Colocación - Una ubicación nombrada en tu sitio donde pueden aparecer anuncios: "homepage-hero", "sidebar-top", "article-footer". Las colocaciones son el lado de la oferta —el inventario disponible.

If the hierarchy feels abstract, think of it as a file system: Advertiser → Campaign → Ad Group → Creative is like Company → Project → Folder → File. Each level adds specificity and scope.

El Ciclo de Vida de una Solicitud de Anuncio

Cuando un usuario visita una página que tiene colocaciones de anuncios, el sistema debe decidir qué mostrar. Esta decisión ocurre en milisegundos e involucra varios pasos:

Llega la solicitud - Un usuario carga una página que incluye una o más colocaciones de anuncios.
Se consultan los anuncios elegibles - El sistema encuentra todas las campañas activas que apuntan a la colocación solicitada y coinciden con el contexto del usuario (dispositivo, ubicación, hora).
Se aplican los filtros de targeting - Se eliminan los anuncios que no coinciden con los atributos del usuario o que han agotado sus límites de frecuencia.
Se verifica el presupuesto - Se excluyen los anuncios de campañas que han gastado su presupuesto diario o de por vida.
Se selecciona un ganador - De los candidatos restantes, se elige una creatividad según prioridad, peso o asignación de prueba A/B.
El anuncio se renderiza - La creatividad seleccionada se incluye en la página renderizada en el servidor.
Se registran los eventos - Se registra una impresión cuando el anuncio se vuelve visible. Se registra un clic si el usuario interactúa.

Este flujo es la columna vertebral de toda la serie. Cada artículo siguiente se enfoca en uno o más de estos pasos.

Diseño del Modelo de Datos

Con el dominio comprendido, vamos a traducirlo en tipos de TypeScript y un esquema de base de datos. Un buen modelado de datos en esta etapa previene migraciones dolorosas más adelante.

Tipos Principales

Estos son los tipos de TypeScript que representan las entidades del dominio. Se usarán en toda la aplicación —en funciones de carga, acciones de formulario, rutas de API y componentes.

// src/lib/types/ads.ts

/** Campaign status reflects the lifecycle state */
export type CampaignStatus = 'draft' | 'active' | 'paused' | 'completed' | 'archived'

/** How the budget is allocated */
export type BudgetType = 'daily' | 'lifetime'

/** What the campaign optimizes for */
export type CampaignGoal = 'impressions' | 'clicks' | 'conversions'

/** Supported creative formats */
export type CreativeFormat = 'image' | 'text' | 'html' | 'video'

/** Device targeting options */
export type DeviceType = 'desktop' | 'mobile' | 'tablet' | 'all'

// ─── Advertiser ────────────────────────────────────────

export interface Advertiser {
	id: string
	name: string
	email: string
	company: string
	createdAt: Date
	updatedAt: Date
}

// ─── Campaign ──────────────────────────────────────────

export interface Campaign {
	id: string
	advertiserId: string
	name: string
	description: string
	status: CampaignStatus
	goal: CampaignGoal
	budgetType: BudgetType
	budgetAmount: number // in cents to avoid floating-point issues
	budgetSpent: number // in cents
	startDate: Date
	endDate: Date | null // null means no end date
	createdAt: Date
	updatedAt: Date
}

// ─── Ad Group ──────────────────────────────────────────

export interface AdGroup {
	id: string
	campaignId: string
	name: string
	isActive: boolean
	targeting: TargetingRules
	priority: number // higher = more likely to win
	createdAt: Date
	updatedAt: Date
}

export interface TargetingRules {
	placements: string[] // e.g. ['homepage-hero', 'sidebar-top']
	devices: DeviceType[]
	geoCountries: string[] // ISO 3166-1 alpha-2 codes
	geoRegions: string[] // e.g. ['US-CA', 'US-NY']
	scheduleTimezone: string // IANA timezone
	scheduleDays: number[] // 0 = Sunday, 6 = Saturday
	scheduleHoursStart: number // 0-23
	scheduleHoursEnd: number // 0-23
	frequencyCap: number | null // max impressions per user per day
	urlPatterns: string[] // regex patterns to match page URLs
}

// ─── Creative ──────────────────────────────────────────

export interface Creative {
	id: string
	adGroupId: string
	name: string
	format: CreativeFormat
	content: CreativeContent
	weight: number // relative weight for rotation (1-100)
	isActive: boolean
	clickUrl: string
	impressionUrl: string | null // optional third-party tracking pixel
	createdAt: Date
	updatedAt: Date
}

export type CreativeContent =
	| { type: 'image'; src: string; alt: string; width: number; height: number }
	| { type: 'text'; headline: string; body: string; ctaText: string }
	| { type: 'html'; markup: string }
	| { type: 'video'; src: string; poster: string; duration: number }

// ─── Placement ─────────────────────────────────────────

export interface Placement {
	id: string
	slug: string // unique identifier like 'homepage-hero'
	name: string // human-readable: 'Homepage Hero Banner'
	description: string
	width: number | null // suggested dimensions
	height: number | null
	allowedFormats: CreativeFormat[]
	isActive: boolean
}

// ─── Events ────────────────────────────────────────────

export interface AdEvent {
	id: string
	type: 'impression' | 'click' | 'conversion'
	campaignId: string
	adGroupId: string
	creativeId: string
	placementId: string
	userId: string | null // anonymous users have null
	sessionId: string
	timestamp: Date
	metadata: Record<string, string> // device, geo, referrer, etc.
}

Budget amounts are stored in cents (integers) instead of dollars (floats). This is standard practice in financial systems because floating-point arithmetic produces rounding errors. 0.1 + 0.2 is 0.30000000000000004 in JavaScript. With cents, 10 + 20 is always 30. Display formatting happens at the UI layer.

Relaciones entre Entidades

Las relaciones entre entidades son sencillas pero vale la pena documentarlas visualmente:

Observaciones clave sobre las relaciones:

Uno a muchos domina: un anunciante posee campañas, una campaña contiene ad groups, un ad group tiene creatividades. Esto hace que las consultas sean sencillas —casi siempre se recorre de arriba hacia abajo desde la campaña hasta la creatividad.
Muchos a muchos aparece entre ad groups y colocaciones: un único ad group puede apuntar a múltiples colocaciones, y una única colocación puede recibir anuncios de múltiples ad groups. El arreglo targeting.placements en el ad group maneja esto sin una tabla de unión.
Los eventos referencian todo: cada evento registra el contexto completo de lo que ocurrió —qué campaña, ad group, creatividad y colocación estuvieron involucrados. Esta desnormalización es intencional. Las tablas de eventos crecen rápido, y conviene evitar joins al consultar millones de filas para análisis.

Configuración del Proyecto

Con el dominio y el modelo de datos definidos, configuremos el proyecto de SvelteKit con todo lo necesario para el resto de la serie.

Estructura de Directorios

El proyecto sigue una estructura modular que separa las responsabilidades de forma clara:

src/
├── lib/
│   ├── types/
│   │   └── ads.ts              ← Type definitions (above)
│   ├── server/
│   │   ├── db/
│   │   │   ├── schema.ts       ← Database schema (Drizzle)
│   │   │   ├── client.ts       ← Database client
│   │   │   └── seed.ts         ← Development seed data
│   │   ├── ads/
│   │   │   ├── campaigns.ts    ← Campaign repository
│   │   │   ├── ad-groups.ts    ← Ad group repository
│   │   │   ├── creatives.ts    ← Creative repository
│   │   │   ├── placements.ts   ← Placement repository
│   │   │   ├── resolver.ts     ← Ad selection engine
│   │   │   └── tracker.ts      ← Event tracking
│   │   └── validation/
│   │       └── ads.ts          ← Valibot schemas
│   ├── components/
│   │   └── ads/
│   │       ├── AdSlot.svelte        ← Renders an ad placement
│   │       ├── CampaignForm.svelte  ← Campaign create/edit form
│   │       ├── AdGroupForm.svelte   ← Ad group form
│   │       ├── CreativeForm.svelte  ← Creative form
│   │       ├── MetricsChart.svelte  ← Real-time metrics
│   │       └── ABTestPanel.svelte   ← A/B test controls
│   └── utils/
│       ├── format.ts           ← Currency, date, percentage formatting
│       └── targeting.ts        ← Client-side targeting helpers
├── routes/
│   ├── (app)/
│   │   └── ads/
│   │       ├── +page.svelte              ← Campaign dashboard
│   │       ├── +page.server.ts
│   │       ├── campaigns/
│   │       │   ├── new/
│   │       │   │   ├── +page.svelte      ← Create campaign
│   │       │   │   └── +page.server.ts
│   │       │   └── [id]/
│   │       │       ├── +page.svelte      ← Campaign detail
│   │       │       ├── +page.server.ts
│   │       │       └── ad-groups/
│   │       │           └── [groupId]/
│   │       │               ├── +page.svelte
│   │       │               └── +page.server.ts
│   │       └── placements/
│   │           ├── +page.svelte
│   │           └── +page.server.ts
│   └── api/
│       └── ads/
│           ├── serve/+server.ts          ← Ad serving endpoint
│           ├── track/+server.ts          ← Event tracking endpoint
│           └── metrics/+server.ts        ← Metrics SSE endpoint

The (app) directory is a SvelteKit route group. It does not affect the URL - /ads/campaigns/new not /(app)/ads/campaigns/new. Route groups let you apply a shared layout (with navigation, sidebar, etc.) to a set of pages without adding a URL segment. The ad management pages share a layout with navigation, while the API routes do not.

Esquema de la Base de Datos

Usamos Drizzle ORM para el acceso tipado a la base de datos. Aquí está el esquema completo:

// src/lib/server/db/schema.ts

import { pgTable, text, integer, boolean, timestamp, json, pgEnum } from 'drizzle-orm/pg-core'
import { relations } from 'drizzle-orm'

// ─── Enums ─────────────────────────────────────────────

export const campaignStatusEnum = pgEnum('campaign_status', [
	'draft',
	'active',
	'paused',
	'completed',
	'archived'
])

export const budgetTypeEnum = pgEnum('budget_type', ['daily', 'lifetime'])

export const campaignGoalEnum = pgEnum('campaign_goal', ['impressions', 'clicks', 'conversions'])

export const creativeFormatEnum = pgEnum('creative_format', ['image', 'text', 'html', 'video'])

export const eventTypeEnum = pgEnum('event_type', ['impression', 'click', 'conversion'])

// ─── Tables ────────────────────────────────────────────

export const advertisers = pgTable('advertisers', {
	id: text('id').primaryKey(),
	name: text('name').notNull(),
	email: text('email').notNull().unique(),
	company: text('company').notNull(),
	createdAt: timestamp('created_at').defaultNow().notNull(),
	updatedAt: timestamp('updated_at').defaultNow().notNull()
})

export const campaigns = pgTable('campaigns', {
	id: text('id').primaryKey(),
	advertiserId: text('advertiser_id')
		.notNull()
		.references(() => advertisers.id),
	name: text('name').notNull(),
	description: text('description').notNull().default(''),
	status: campaignStatusEnum('status').notNull().default('draft'),
	goal: campaignGoalEnum('goal').notNull().default('impressions'),
	budgetType: budgetTypeEnum('budget_type').notNull().default('daily'),
	budgetAmount: integer('budget_amount').notNull().default(0),
	budgetSpent: integer('budget_spent').notNull().default(0),
	startDate: timestamp('start_date').notNull(),
	endDate: timestamp('end_date'),
	createdAt: timestamp('created_at').defaultNow().notNull(),
	updatedAt: timestamp('updated_at').defaultNow().notNull()
})

export const adGroups = pgTable('ad_groups', {
	id: text('id').primaryKey(),
	campaignId: text('campaign_id')
		.notNull()
		.references(() => campaigns.id, { onDelete: 'cascade' }),
	name: text('name').notNull(),
	isActive: boolean('is_active').notNull().default(true),
	targeting: json('targeting').notNull().$type<TargetingRules>(),
	priority: integer('priority').notNull().default(1),
	createdAt: timestamp('created_at').defaultNow().notNull(),
	updatedAt: timestamp('updated_at').defaultNow().notNull()
})

export const creatives = pgTable('creatives', {
	id: text('id').primaryKey(),
	adGroupId: text('ad_group_id')
		.notNull()
		.references(() => adGroups.id, { onDelete: 'cascade' }),
	name: text('name').notNull(),
	format: creativeFormatEnum('format').notNull(),
	content: json('content').notNull().$type<CreativeContent>(),
	weight: integer('weight').notNull().default(50),
	isActive: boolean('is_active').notNull().default(true),
	clickUrl: text('click_url').notNull(),
	impressionUrl: text('impression_url'),
	createdAt: timestamp('created_at').defaultNow().notNull(),
	updatedAt: timestamp('updated_at').defaultNow().notNull()
})

export const placements = pgTable('placements', {
	id: text('id').primaryKey(),
	slug: text('slug').notNull().unique(),
	name: text('name').notNull(),
	description: text('description').notNull().default(''),
	width: integer('width'),
	height: integer('height'),
	allowedFormats: json('allowed_formats').notNull().$type<string[]>().default([]),
	isActive: boolean('is_active').notNull().default(true)
})

export const adEvents = pgTable('ad_events', {
	id: text('id').primaryKey(),
	type: eventTypeEnum('type').notNull(),
	campaignId: text('campaign_id')
		.notNull()
		.references(() => campaigns.id),
	adGroupId: text('ad_group_id')
		.notNull()
		.references(() => adGroups.id),
	creativeId: text('creative_id')
		.notNull()
		.references(() => creatives.id),
	placementId: text('placement_id')
		.notNull()
		.references(() => placements.id),
	userId: text('user_id'),
	sessionId: text('session_id').notNull(),
	timestamp: timestamp('timestamp').defaultNow().notNull(),
	metadata: json('metadata').notNull().$type<Record<string, string>>().default({})
})

// ─── Relations ─────────────────────────────────────────

export const advertiserRelations = relations(advertisers, ({ many }) => ({
	campaigns: many(campaigns)
}))

export const campaignRelations = relations(campaigns, ({ one, many }) => ({
	advertiser: one(advertisers, {
		fields: [campaigns.advertiserId],
		references: [advertisers.id]
	}),
	adGroups: many(adGroups),
	events: many(adEvents)
}))

export const adGroupRelations = relations(adGroups, ({ one, many }) => ({
	campaign: one(campaigns, {
		fields: [adGroups.campaignId],
		references: [campaigns.id]
	}),
	creatives: many(creatives)
}))

export const creativeRelations = relations(creatives, ({ one }) => ({
	adGroup: one(adGroups, {
		fields: [creatives.adGroupId],
		references: [adGroups.id]
	})
}))

// Import types used in JSON columns
import type { TargetingRules, CreativeContent } from '$lib/types/ads'

Esquemas de Validación

Cada envío de formulario en este sistema será validado en el servidor usando Valibot. Aquí están los esquemas principales:

// src/lib/server/validation/ads.ts

import * as v from 'valibot'

export const CampaignSchema = v.object({
	name: v.pipe(
		v.string(),
		v.minLength(3, 'Campaign name must be at least 3 characters'),
		v.maxLength(100, 'Campaign name must be under 100 characters')
	),
	description: v.optional(v.pipe(v.string(), v.maxLength(500))),
	goal: v.picklist(['impressions', 'clicks', 'conversions']),
	budgetType: v.picklist(['daily', 'lifetime']),
	budgetAmount: v.pipe(v.number(), v.minValue(100, 'Minimum budget is $1.00 (100 cents)')),
	startDate: v.pipe(v.string(), v.isoTimestamp()),
	endDate: v.optional(v.pipe(v.string(), v.isoTimestamp()))
})

export const AdGroupSchema = v.object({
	name: v.pipe(
		v.string(),
		v.minLength(2, 'Ad group name must be at least 2 characters'),
		v.maxLength(100)
	),
	priority: v.pipe(v.number(), v.minValue(1), v.maxValue(100)),
	targeting: v.object({
		placements: v.pipe(v.array(v.string()), v.minLength(1, 'Select at least one placement')),
		devices: v.array(v.picklist(['desktop', 'mobile', 'tablet', 'all'])),
		geoCountries: v.array(v.pipe(v.string(), v.length(2))),
		geoRegions: v.array(v.string()),
		scheduleTimezone: v.string(),
		scheduleDays: v.array(v.pipe(v.number(), v.minValue(0), v.maxValue(6))),
		scheduleHoursStart: v.pipe(v.number(), v.minValue(0), v.maxValue(23)),
		scheduleHoursEnd: v.pipe(v.number(), v.minValue(0), v.maxValue(23)),
		frequencyCap: v.nullable(v.pipe(v.number(), v.minValue(1))),
		urlPatterns: v.array(v.string())
	})
})

export const CreativeSchema = v.object({
	name: v.pipe(v.string(), v.minLength(2), v.maxLength(100)),
	format: v.picklist(['image', 'text', 'html', 'video']),
	weight: v.pipe(v.number(), v.minValue(1), v.maxValue(100)),
	clickUrl: v.pipe(v.string(), v.url('Must be a valid URL')),
	impressionUrl: v.optional(v.pipe(v.string(), v.url())),
	content: v.union([
		v.object({
			type: v.literal('image'),
			src: v.pipe(v.string(), v.url()),
			alt: v.pipe(v.string(), v.minLength(1)),
			width: v.pipe(v.number(), v.minValue(1)),
			height: v.pipe(v.number(), v.minValue(1))
		}),
		v.object({
			type: v.literal('text'),
			headline: v.pipe(v.string(), v.minLength(1), v.maxLength(100)),
			body: v.pipe(v.string(), v.minLength(1), v.maxLength(500)),
			ctaText: v.pipe(v.string(), v.minLength(1), v.maxLength(50))
		}),
		v.object({
			type: v.literal('html'),
			markup: v.pipe(v.string(), v.minLength(1))
		}),
		v.object({
			type: v.literal('video'),
			src: v.pipe(v.string(), v.url()),
			poster: v.pipe(v.string(), v.url()),
			duration: v.pipe(v.number(), v.minValue(1))
		})
	])
})

export type CampaignInput = v.InferOutput<typeof CampaignSchema>
export type AdGroupInput = v.InferOutput<typeof AdGroupSchema>
export type CreativeInput = v.InferOutput<typeof CreativeSchema>

Valibot offers a modular, tree-shakeable approach to schema validation. Unlike monolithic alternatives, each validation function is an independent import, so your production bundle includes only what you actually use. For a system that validates multiple entity types with different rules, this keeps the overhead minimal.

Funciones de Utilidad

Algunas funciones de utilidad se usarán en todo el sistema. Definámoslas ahora:

// src/lib/utils/format.ts

/**
 * Format cents as a display currency string.
 * 1500 → "$15.00"
 */
export function formatCurrency(cents: number, currency = 'USD'): string {
	return new Intl.NumberFormat('en-US', {
		style: 'currency',
		currency
	}).format(cents / 100)
}

/**
 * Format a number as a percentage with specified decimal places.
 * 0.156 → "15.6%"
 */
export function formatPercent(value: number, decimals = 1): string {
	return `${(value * 100).toFixed(decimals)}%`
}

/**
 * Calculate Click-Through Rate.
 * Returns 0 if there are no impressions (avoids division by zero).
 */
export function calculateCTR(clicks: number, impressions: number): number {
	if (impressions === 0) return 0
	return clicks / impressions
}

/**
 * Format a date for display in campaign lists.
 */
export function formatDate(date: Date): string {
	return new Intl.DateTimeFormat('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric'
	}).format(date)
}

/**
 * Calculate budget utilization as a decimal (0–1).
 */
export function budgetUtilization(spent: number, total: number): number {
	if (total === 0) return 0
	return Math.min(spent / total, 1)
}

El Pipeline de Resolución de Anuncios

La pieza más crítica del sistema es el resolvedor de anuncios: la función que toma una colocación y el contexto del usuario y devuelve la mejor creatividad para mostrar. Aquí está el pipeline conceptual que implementaremos completamente en la Parte 3:

Cada etapa es un filtro que reduce el conjunto de candidatos. Este diseño en forma de embudo es intencional —elimina la mayor cantidad de candidatos en las etapas más económicas (consulta de base de datos y coincidencia de colocación) antes de pasar a verificaciones más costosas (límites de frecuencia, que requieren búsquedas por usuario).

In production ad systems, the resolution pipeline runs on every page load. If your site gets 10,000 page views per minute and each page has 3 placements, that is 30,000 ad decisions per minute. The pipeline must be fast, ideally under 10ms per decision. We will address caching, query optimization, and edge-case handling in Part 3.

Datos de Prueba para Desarrollo

Para desarrollar y probar el sistema, necesitamos datos de prueba realistas. Aquí hay un script de seed que crea un escenario completo:

// src/lib/server/db/seed.ts

import { db } from './client'
import { advertisers, campaigns, adGroups, creatives, placements } from './schema'
import crypto from 'node:crypto'

const id = () => crypto.randomUUID()

export async function seed() {
	console.log('🌱 Seeding ad campaign data...')

	// ── Placements ──────────────────────────────────────
	const placementData = [
		{
			id: id(),
			slug: 'homepage-hero',
			name: 'Homepage Hero Banner',
			description: 'Full-width banner at the top of the homepage',
			width: 1200,
			height: 400,
			allowedFormats: ['image', 'html'],
			isActive: true
		},
		{
			id: id(),
			slug: 'sidebar-top',
			name: 'Sidebar Top',
			description: 'Top position in the sidebar',
			width: 300,
			height: 250,
			allowedFormats: ['image', 'text'],
			isActive: true
		},
		{
			id: id(),
			slug: 'article-footer',
			name: 'Article Footer',
			description: 'Banner below article content',
			width: 728,
			height: 90,
			allowedFormats: ['image', 'text', 'html'],
			isActive: true
		}
	]

	await db.insert(placements).values(placementData)

	// ── Advertiser ──────────────────────────────────────
	const advId = id()
	await db.insert(advertisers).values({
		id: advId,
		name: 'Acme Corp',
		email: 'ads@acme.example.com',
		company: 'Acme Corporation'
	})

	// ── Campaign ────────────────────────────────────────
	const campId = id()
	await db.insert(campaigns).values({
		id: campId,
		advertiserId: advId,
		name: 'Summer Sale 2026',
		description: 'Promote our summer product line across the site',
		status: 'active',
		goal: 'clicks',
		budgetType: 'daily',
		budgetAmount: 5000, // $50.00/day
		budgetSpent: 0,
		startDate: new Date('2026-06-01'),
		endDate: new Date('2026-08-31')
	})

	// ── Ad Groups ───────────────────────────────────────
	const desktopGroupId = id()
	const mobileGroupId = id()

	await db.insert(adGroups).values([
		{
			id: desktopGroupId,
			campaignId: campId,
			name: 'Desktop Users - US',
			isActive: true,
			priority: 10,
			targeting: {
				placements: ['homepage-hero', 'sidebar-top'],
				devices: ['desktop'],
				geoCountries: ['US'],
				geoRegions: [],
				scheduleTimezone: 'America/New_York',
				scheduleDays: [1, 2, 3, 4, 5],
				scheduleHoursStart: 8,
				scheduleHoursEnd: 22,
				frequencyCap: 3,
				urlPatterns: []
			}
		},
		{
			id: mobileGroupId,
			campaignId: campId,
			name: 'Mobile Users - Global',
			isActive: true,
			priority: 8,
			targeting: {
				placements: ['homepage-hero', 'article-footer'],
				devices: ['mobile', 'tablet'],
				geoCountries: [],
				geoRegions: [],
				scheduleTimezone: 'UTC',
				scheduleDays: [0, 1, 2, 3, 4, 5, 6],
				scheduleHoursStart: 0,
				scheduleHoursEnd: 23,
				frequencyCap: 5,
				urlPatterns: []
			}
		}
	])

	// ── Creatives ───────────────────────────────────────
	await db.insert(creatives).values([
		{
			id: id(),
			adGroupId: desktopGroupId,
			name: 'Summer Hero - Variant A',
			format: 'image',
			content: {
				type: 'image',
				src: '/ads/summer-hero-a.jpg',
				alt: 'Summer Sale - Up to 50% off',
				width: 1200,
				height: 400
			},
			weight: 60,
			isActive: true,
			clickUrl: 'https://acme.example.com/summer-sale?utm_source=site&utm_creative=hero-a',
			impressionUrl: null
		},
		{
			id: id(),
			adGroupId: desktopGroupId,
			name: 'Summer Hero - Variant B',
			format: 'image',
			content: {
				type: 'image',
				src: '/ads/summer-hero-b.jpg',
				alt: 'Summer Collection Now Available',
				width: 1200,
				height: 400
			},
			weight: 40,
			isActive: true,
			clickUrl: 'https://acme.example.com/summer-sale?utm_source=site&utm_creative=hero-b',
			impressionUrl: null
		},
		{
			id: id(),
			adGroupId: mobileGroupId,
			name: 'Mobile Text Ad',
			format: 'text',
			content: {
				type: 'text',
				headline: 'Summer Sale is Here!',
				body: 'Get up to 50% off our entire summer collection. Free shipping on orders over $50.',
				ctaText: 'Shop Now'
			},
			weight: 100,
			isActive: true,
			clickUrl: 'https://acme.example.com/summer-sale?utm_source=site&utm_creative=mobile-text',
			impressionUrl: null
		}
	])

	console.log('✅ Seed data inserted successfully')
}

¿Qué sigue?

Ahora tienes la base completa para un sistema dinámico de campañas publicitarias:

Comprensión del dominio - La jerarquía de anunciantes, campañas, grupos de anuncios, creatividades y ubicaciones
Modelo de datos - Tipos de TypeScript y un esquema de base de datos Drizzle que representan fielmente el dominio
Validación - Esquemas de Valibot que aplican las reglas de negocio en cada envío de formulario
Utilidades - Ayudantes de formato y cálculo utilizados en todo el sistema
Datos de prueba - Un escenario de desarrollo realista para construir y probar

Cada artículo de esta serie incluye código de referencia que ilustra el diseño de esa capa. El código es consciente del entorno de producción, pero intencionalmente incompleto — el código de unión, la configuración y algunos repositorios se dejan como ejercicios. Una implementación completa paso a paso está disponible como proyecto separado.