Antes do Código, Há um Domínio

A publicidade digital impulsiona grande parte da internet moderna. Por trás de cada banner, promoção na barra lateral ou listagem patrocinada existe um sistema de gerenciamento de campanhas — um software que decide qual anúncio exibir, para quem e quando. Esses sistemas não são exclusivos do Google ou da Meta. Qualquer produto que venda espaço publicitário, promova conteúdo interno ou gerencie colocações de afiliados precisa das mesmas abstrações fundamentais.

Esta série explora a arquitetura de um sistema completo de campanhas publicitárias dinâmicas em SvelteKit. Ao longo de sete artigos, você verá como modelagem de domínio, interfaces de gerenciamento, pipelines de resolução de anúncios, análises em tempo real, testes A/B e controle de ritmo de orçamento se encaixam em um design voltado para produção. O código ao longo da série é ilustrativo, projetado para ensinar os padrões e as trocas envolvidas, não para ser copiado literalmente em um projeto.

Este primeiro artigo estabelece as bases: o domínio, o modelo de dados, o schema do banco de dados e a estrutura de projeto da qual o restante da série depende.

Esta é a Parte 1 de 7 da série Arquitetura de Campanhas Publicitárias:

Fundamentos (você está aqui) - Modelagem de domínio, design de schema, estrutura de projeto
CRUD de Campanhas - Padrões de form action, validação, máquinas de estado
O Motor de Renderização - Pipeline de targeting, seleção ponderada, veiculação de anúncios
Dashboard em Tempo Real - Rastreamento de eventos, streaming SSE, métricas ao vivo
Testes A/B e Otimização - Divisão de tráfego, significância estatística
Orçamento e Agendamento - Algoritmos de pacing, automação de ciclo de vida
Endurecimento para Produção - Indexação de banco de dados, cache Redis, rate limiting, GDPR

Para Que Serve Esta Arquitetura de Fato

Antes de mergulhar no domínio, vale ser direto sobre o contexto em que esse sistema faz sentido e o contexto em que não faz. A publicidade web mudou consideravelmente na última década, e construir um sistema de anúncios hoje sem entender esse cenário é construir sem um mapa.

A realidade principal é que uma parcela significativa dos usuários nunca vê anúncios na web. A adoção de bloqueadores de anúncios no desktop fica entre 30 e 45 por cento dependendo da pesquisa, e entre públicos de desenvolvedores e técnicos (exatamente o público que este site alcança) esse número se aproxima de 60 a 70 por cento. Isso não vai mudar.

A proteção de rastreamento em nível de navegador, a Prevenção Inteligente de Rastreamento do Safari, os padrões de privacidade aprimorados do Firefox e a própria aplicação da Coalizão para Melhores Anúncios do Chrome corroeram a infraestrutura da qual a publicidade programática de terceiros depende. O acordo implícito que alimentou grande parte da web — conteúdo gratuito em troca de visualizações de anúncios — está quebrado de um lado. As visualizações não estão acontecendo.

Some a isso a camada jurídica. O GDPR na Europa e o CPRA na Califórnia exigem consentimento explícito do usuário antes que você colete dados comportamentais para publicidade. As taxas de consentimento em mercados europeus para rastreamento personalizado geralmente ficam entre 30 e 60 por cento, dependendo de como o banner de consentimento é projetado. Se seus usuários são globais, você perderá a maioria do seu potencial de inventário europeu antes de veicular uma única impressão.

Então por que esta série existe?

Por dois motivos. Primeiro, os padrões desta arquitetura se transferem muito além da publicidade em banners. Um sistema que resolve qual criativo exibir com base em dispositivo, localização, agendamento, frequência e orçamento é o mesmo sistema que alimenta feature flags com targeting, recomendações de conteúdo personalizadas, testes A/B em qualquer elemento de página, promoções internas da casa e reconhecimentos de patrocinadores. O modelo de domínio e o pipeline de resolução que você constrói aqui são genuinamente reutilizáveis.

Segundo, a publicidade própria (first-party) para públicos especializados ainda funciona. Os formatos que se sustentam são contextualmente relevantes, não-interruptivos, renderizados no servidor (sem layout shift, sem flash assíncrono de conteúdo) e claramente rotulados. Patrocínios diretos de empresas cujos produtos o público realmente usa — como ferramentas de desenvolvimento, serviços de infraestrutura, livros técnicos — produzem taxas de clique uma ordem de magnitude maiores do que o inventário de exibição genérico, precisamente porque a correspondência entre público e oferta é real, não inferida a partir de dados de vigilância.

Este site usa uma versão deste sistema. A arquitetura desta série não é hipotética. As colocações de patrocínio são resolvidas no servidor com base no contexto da página, veiculadas sem dependências de rastreamento JavaScript e medidas usando análises próprias que não requerem cookies de terceiros.

A história de consentimento é direta: caps de frequência com escopo de sessão, sem rastreamento entre sites, sem dados pessoais vendidos a terceiros. O problema dos bloqueadores de anúncios diminui consideravelmente quando o anúncio não é distinguível do contexto editorial pelas heurísticas que os bloqueadores usam, e quando o conteúdo ao redor vale a pena ser lido.

O sistema vale mais a pena ser construído se você possui seu inventário e tem uma relação direta com seus patrocinadores. Vale menos a pena ser construído se seu plano é conectar-se a uma exchange programática e vender inventário remanescente (espaço publicitário não vendido) a $0,50 CPM. Esta série é projetada para o primeiro caso.

Vamos entrar no domínio.

O Domínio: Como Sistemas de Anúncios Funcionam

Antes de escrever qualquer código, você precisa de um modelo mental claro de como os sistemas de campanhas publicitárias operam. Mesmo que você nunca tenha trabalhado em ad tech, os conceitos se mapeiam perfeitamente para problemas que você já resolveu — catálogos de produtos, gerenciamento de conteúdo, feature flags. O vocabulário é diferente, mas os padrões são familiares.

A Hierarquia

Todo sistema de anúncios organiza seus dados em uma hierarquia. A profundidade exata varia por plataforma, mas a estrutura central é notavelmente consistente em toda a indústria:

Vamos definir cada nível com precisão:

Advertiser (Anunciante) - A entidade que paga pelos anúncios. Em uma plataforma self-serve, é uma empresa registrada. Em um sistema interno, pode ser um departamento ou equipe de produto. Toda campanha pertence a um anunciante.

Campaign (Campanha) - Uma iniciativa de marketing com um objetivo, orçamento e prazo definidos. "Liquidação de Verão 2026" ou "Lançamento de Novo Recurso" são campanhas. Uma campanha agrupa ad groups relacionados sob um orçamento e agendamento compartilhados.

Ad Group (Grupo de Anúncios) - Uma estratégia de targeting dentro de uma campanha. Uma campanha pode ter um ad group direcionado a usuários mobile na Europa e outro direcionado a usuários desktop na América do Norte. Os ad groups controlam quem vê os anúncios e onde eles aparecem.

Creative (Criativo) - O conteúdo real exibido ao usuário: uma imagem, um bloco de texto, um snippet HTML ou um vídeo. Cada ad group pode ter múltiplos criativos, permitindo testes A/B e rotação.

Placement (Posicionamento) - Um local nomeado em seu site onde anúncios podem aparecer: "homepage-hero", "sidebar-top", "article-footer". Os posicionamentos são o lado da oferta — o inventário disponível.

Se a hierarquia parecer abstrata, pense nela como um sistema de arquivos: Advertiser → Campaign → Ad Group → Creative é como Empresa → Projeto → Pasta → Arquivo. Cada nível adiciona especificidade e escopo.

O Ciclo de Vida de uma Requisição de Anúncio

Quando um usuário visita uma página que possui posicionamentos de anúncios, o sistema deve decidir o que exibir. Essa decisão acontece em milissegundos e envolve várias etapas:

A requisição chega - Um usuário carrega uma página que inclui um ou mais posicionamentos de anúncios.
Anúncios elegíveis são consultados - O sistema encontra todas as campanhas ativas que têm como alvo o posicionamento solicitado e correspondem ao contexto do usuário (dispositivo, localização, horário).
Filtros de targeting são aplicados - Anúncios que não correspondem aos atributos do usuário ou que esgotaram seus caps de frequência são eliminados.
O orçamento é verificado - Anúncios de campanhas que gastaram seu orçamento diário ou vitalício são excluídos.
Um vencedor é selecionado - Dos candidatos restantes, um criativo é escolhido com base em prioridade, peso ou alocação de teste A/B.
O anúncio é renderizado - O criativo selecionado é incluído na página renderizada no servidor.
Eventos são rastreados - Uma impressão é registrada quando o anúncio se torna visível. Um clique é registrado se o usuário interagir.

Esse fluxo é a espinha dorsal de toda a série. Cada artigo subsequente aprofunda uma ou mais dessas etapas.

Design do Modelo de Dados

Com o domínio compreendido, vamos traduzi-lo em tipos TypeScript e um schema de banco de dados. Uma boa modelagem de dados nesta fase previne migrações dolorosas mais tarde.

Tipos Principais

Estes são os tipos TypeScript que representam as entidades do domínio. Eles serão usados em toda a aplicação — em load functions, form actions, rotas de API e 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.
}

Os valores de orçamento são armazenados em centavos (inteiros) em vez de dólares (floats). Esta é uma prática padrão em sistemas financeiros porque a aritmética de ponto flutuante produz erros de arredondamento. 0.1 + 0.2 é 0.30000000000000004 em JavaScript. Com centavos, 10 + 20 é sempre 30. A formatação para exibição acontece na camada de UI.

Relacionamentos entre Entidades

Os relacionamentos entre entidades são diretos, mas vale a pena documentá-los visualmente:

Observações importantes sobre os relacionamentos:

Um-para-muitos domina: um anunciante possui campanhas, uma campanha contém ad groups, um ad group tem criativos. Isso torna as consultas diretas — você quase sempre percorre de cima para baixo, da campanha ao criativo.
Muitos-para-muitos aparece entre ad groups e posicionamentos: um único ad group pode ter como alvo múltiplos posicionamentos, e um único posicionamento pode receber anúncios de múltiplos ad groups. O array targeting.placements no ad group resolve isso sem uma tabela de junção.
Eventos referenciam tudo: cada evento registra o contexto completo do que aconteceu — qual campanha, ad group, criativo e posicionamento estavam envolvidos. Essa desnormalização é intencional. Tabelas de eventos crescem rapidamente, e você quer evitar joins ao consultar milhões de linhas para análises.

Configuração do Projeto

Com o domínio e o modelo de dados definidos, vamos configurar o projeto SvelteKit com tudo que é necessário para o restante da série.

Estrutura de Diretórios

O projeto segue uma estrutura modular que separa as 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

O diretório (app) é um grupo de rotas do SvelteKit. Ele não afeta a URL — /ads/campaigns/new e não /(app)/ads/campaigns/new. Grupos de rotas permitem que você aplique um layout compartilhado (com navegação, barra lateral etc.) a um conjunto de páginas sem adicionar um segmento de URL. As páginas de gerenciamento de anúncios compartilham um layout com navegação, enquanto as rotas de API não.

Schema do Banco de Dados

Usamos o Drizzle ORM para acesso ao banco de dados com segurança de tipos. Aqui está o schema 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'

Schemas de Validação

Cada envio de formulário neste sistema será validado no servidor usando Valibot. Aqui estão os schemas principais:

// 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>

O Valibot oferece uma abordagem modular e tree-shakeable para validação de schemas. Ao contrário de alternativas monolíticas, cada função de validação é uma importação independente, então seu bundle de produção inclui apenas o que você realmente usa. Para um sistema que valida múltiplos tipos de entidade com regras diferentes, isso mantém o overhead mínimo.

Funções Utilitárias

Algumas funções utilitárias serão usadas em todo o sistema. Vamos defini-las agora:

// 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)
}

O Pipeline de Resolução de Anúncios

A peça mais crítica do sistema é o resolvedor de anúncios — a função que recebe um posicionamento e o contexto do usuário e retorna o melhor criativo a exibir. Aqui está o pipeline conceitual que implementaremos completamente na Parte 3:

Cada estágio é um filtro que estreita o conjunto de candidatos. Esse design em forma de funil é intencional — ele elimina o maior número de candidatos nos estágios mais baratos (consulta ao banco de dados e correspondência de posicionamento) antes de avançar para verificações mais custosas (caps de frequência, que exigem consultas por usuário).

Em sistemas de anúncios em produção, o pipeline de resolução é executado a cada carregamento de página. Se seu site recebe 10.000 visualizações de página por minuto e cada página tem 3 posicionamentos, isso representa 30.000 decisões de anúncio por minuto. O pipeline deve ser rápido — idealmente abaixo de 10ms por decisão. Abordaremos cache, otimização de consultas e tratamento de casos extremos na Parte 3.

Dados de Seed para Desenvolvimento

Para desenvolver e testar o sistema, precisamos de dados de seed realistas. Aqui está um script de seed que cria um cenário 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')
}

O Que Vem a Seguir

Agora você tem a base completa para um sistema dinâmico de campanhas publicitárias:

Compreensão do domínio - A hierarquia de anunciantes, campanhas, grupos de anúncios, criativos e posicionamentos
Modelo de dados - Tipos TypeScript e um schema de banco de dados Drizzle que representam fielmente o domínio
Validação - Schemas Valibot que aplicam regras de negócio em cada envio de formulário
Utilitários - Auxiliares de formatação e cálculo utilizados em todo o sistema
Dados de seed - Um cenário de desenvolvimento realista para construir e testar

Cada artigo desta série inclui código de referência que ilustra o design para aquela camada. O código é voltado para produção, mas intencionalmente incompleto — código de integração, configuração e alguns repositórios são deixados como exercícios. Uma implementação completa para acompanhar o desenvolvimento está disponível como um projeto separado.