Vision and Scope

Vision

Kobi is an end-to-end SaaS / AI service for small-business clients across diverse verticals — health, paid private schools, tourism, ecommerce, and others. Each vertical has different creative, compliance, and funnel needs, but digital media investment follows a common operational pattern.

The Digital Ads module (this repo) owns that pattern: automate everything from onboarding to reporting, with agents doing repeatable work and humans approving what matters.

Mandate

Manage end-to-end digital media investment in a fully automated way — onboarding, media plan, campaign execution, optimization, plan update, and reporting — including all supporting sub-services.

Target clients (examples)

The module is vertical-agnostic at the core; vertical-specific rules live in configuration and agent prompts, not in separate codebases per industry.

In scope

Core lifecycle

• Digital media onboarding (intake, access, verifications)
• Media planning (budget, channel mix, audience, creative brief)
• Campaign execution (build, launch, pause, budget shifts)
• Optimization (bid/budget, audience, creative rotation)
• Plan update (replanning, versioning, approval)
• Reporting (performance, attribution, CRM-linked outcomes)

Sub-services (supporting automation)

• Account creation & ownership — agency/Kobi-owned; clients never manage raw ad accounts; plan-driven spend caps
• Social / BM access — client consents via portal OAuth to link Page + Instagram; system users for API automation
• Provisioning templates — pixels, catalogs, and events by vertical and SKU — see provisioning spec
• Account verifications — Kobi-entity business verify on MCC/BM/BC (PRE); optional client domain verify; agency billing inherit
• Billing & invoicing — Kobi/agency payment method on all ad accounts; clients invoiced monthly (media spend + fees)
• Merchant Center — creation and linking for Shopping / ecommerce feeds
• Feed management — product/data feeds for Google, Meta catalog, etc.
• Meta CPAS (Collaborative Ads) — Phase 2 core track: brand ↔ marketplace catalog segments, Advantage+ catalog sales to retailer PDPs; democratize enterprise CPAS for SMB — see meta-collaborative-ads-cpas.md
• Conversion tracking — first-party, cookieless-ready tagging; server-side where needed
• CAPI & offline conversions — CRM → platform conversion import
• Internal CRM APIs — wire campaigns to CRM entities (leads, appointments, enrollments, orders)
• Agentic orchestration — multi-agent workflows with defined handoffs and guardrails
• Human touch dashboard — every manual step visible, approvable, versioned
• GCP deployment (later phase) — skeleton on Google Cloud for handoff to implementation team
• Engagement via paid ads only — dark/unpublished post creatives and boost existing client organic posts; no organic feed publishing (ADR 0004)

Client agreements, approvals, and data responsibility

Clients accept Kobi terms of service before onboarding. Every material decision — media plan, budget, creative, channel mix, tracking setup, and data-use scope — flows through human-in-the-loop approval and is versioned.

Legal artifacts (ToS, DPA, media-authorization addenda) may be maintained in the broader Kobi platform legal layer; this module enforces capture, versioning, and linkage to onboarding and plan approvals.

Billing, payment, and monthly invoicing

Clients never attach their own payment method to ad platform accounts. Kobi operates on an agency billing model:

Monthly invoicing applies wherever the platform and Kobi billing module support it: media spend reconciliation, management fees, and (optionally) infrastructure / LLM ops allocation per tenant. Ad-hoc client cards on ad accounts are out of scope.

Tax on media spend (finance dependency — parent/VC-owned): ad spend in Turkey/EU carries VAT/KDV and, for foreign ad platforms, digital-services / withholding tax that affect invoice gross-up, margin, and the media float. This module passes through platform spend and exposes the line items, but the tax treatment, gross-up, and registration are owned by the parent/VC finance layer — flagged here so it is not missed at invoicing. Not an engineering blocker; confirm before first client billing.

Platforms (Phase 1–4 order)

1. Google Ads
2. Meta Ads
3. TikTok Ads
4. DV360
5. Google Analytics 4 (measurement source of truth)
6. Internal CRM

Out of scope (this module / Phase 0)

Phase 2 core tracks (post-pilot — strategic)

Success criteria (for implementation phases)

• New client onboarded to first live campaign within SLA (target TBD per vertical)
• ≥90% of routine changes executed by agents without human intervention
• All human touches logged with approver, timestamp, and plan version
• GA4 reconciled with platform reporting within defined tolerance
• CRM offline conversions flowing to Google and Meta CAPI with match-rate monitoring

Dependencies on broader Kobi platform

• VC / partnerships — warm introductions to Google, Meta, and TikTok partner reps — Emre (A); Arif (C). W0 Q1
• Creative production module — integrate before live pilot — Emre (A program); Creative lead TBD (R provider); Arif (R consumer API). W0 Q2
• Internal CRM — entity model, webhooks/API for conversion export
• Identity / tenant model — multi-tenant isolation for clients
• Billing (future) — monthly client invoicing (media spend pass-through + Kobi fees); integrates with platform spend exports
• Shared design system (future) — human touch dashboard UI

Document navigation

• Architecture: 02-architecture/
• Platforms: 03-platforms/
• Lifecycle: 04-lifecycle/
• Roadmap: 08-roadmap-and-timelines.md