Marketing Portal

Advertiser self-service platform for MiFamilias advertising

System Overview

The Marketing Portal enables advertisers to create and manage ad campaigns that display to free-tier users in the MiFamilias mobile app.

flowchart TB subgraph Advertisers["Advertiser Portal"] MP["marketing.mifamilias.com"] Login["Login/Register"] Dashboard["Dashboard"] Campaigns["Campaigns"] Analytics["Analytics"] end subgraph Admin["Admin Portal"] AR["Ad Reviews"] MM["Marketing Metrics"] end subgraph Backend["Backend API"] AdvAPI["Advertiser API"] AdsAPI["Ads API"] StatsAPI["Stats API"] end subgraph Storage["Storage"] DDB[("DynamoDB")] S3["S3 (Creatives)"] end subgraph Mobile["Mobile App"] AdBanner["Ad Banner Component"] AdService["Advertising Service"] end MP --> Login Login --> Dashboard Dashboard --> Campaigns Dashboard --> Analytics Campaigns --> AdvAPI Analytics --> StatsAPI AR --> AdsAPI MM --> StatsAPI AdvAPI --> DDB AdsAPI --> DDB AdsAPI --> S3 AdService --> AdsAPI AdBanner --> AdService

Campaign Approval Workflow

All ad campaigns go through a review process before going live. This ensures ad quality and policy compliance.

stateDiagram-v2 [*] --> Draft: Create Campaign Draft --> PendingReview: Submit for Review Draft --> Draft: Edit PendingReview --> Approved: Admin Approves PendingReview --> Rejected: Admin Rejects Rejected --> Draft: Edit & Resubmit Approved --> Active: Start Date Reached Active --> Paused: Advertiser Pauses Active --> Completed: End Date or Budget Paused --> Active: Resume Paused --> Completed: End Date Completed --> [*]

Status Definitions

Status Description Actions Available
Draft Campaign created but not submitted Edit, Submit for Review, Delete
Pending Review Awaiting admin approval (1-2 business days) View only
Approved Approved, waiting for start date View, Edit budget
Rejected Rejected with feedback Edit & Resubmit
Active Running and serving impressions Pause, View Analytics
Paused Temporarily stopped by advertiser Resume, Edit
Completed End date reached or budget exhausted View Analytics, Duplicate

Ad Serving Flow

How ads are served to users in the mobile app based on subscription tier.

sequenceDiagram participant User as Mobile App User participant App as MiFamilias App participant API as Ads API participant DB as DynamoDB User->>App: Opens Family Feed App->>API: GET /ads/active API->>API: Check subscription tier alt Paid Tier (Starter/Family/Transcend) API-->>App: { ads: [], showAds: false } App-->>User: No ads displayed else Free Tier API->>DB: Query active ads (GSI3) DB-->>API: Active campaigns API->>API: Apply targeting & frequency cap API-->>App: { ads: [...], showAds: true } App-->>User: Display ad banner User->>App: Views ad (impression) App->>API: POST /ads/{id}/events (impression) User->>App: Clicks ad App->>API: POST /ads/{id}/events (click) App->>User: Open destination URL end

Analytics & Metrics

Key performance indicators tracked for each campaign.

flowchart LR subgraph Tracking["Event Tracking"] IMP["Impressions"] CLK["Clicks"] end subgraph Metrics["Calculated Metrics"] CTR["CTR
(Clicks/Impressions)"] CPC["CPC
(Spend/Clicks)"] CPM["CPM
(Spend/1000 Impr)"] end subgraph Breakdowns["Breakdowns"] ByCamp["By Campaign"] ByDay["By Day of Week"] ByHour["By Hour"] ByPlatform["By Platform"] ByAge["By Age Group"] end IMP --> CTR CLK --> CTR CLK --> CPC IMP --> CPM CTR --> ByCamp CTR --> ByDay CTR --> ByHour CTR --> ByPlatform CTR --> ByAge

Metric Definitions

Metric Formula Description
Impressions Count Number of times ad was viewed
Clicks Count Number of times ad was clicked
CTR (Click-Through Rate) (Clicks / Impressions) × 100 Percentage of impressions that resulted in clicks
CPC (Cost Per Click) Spend / Clicks Average cost for each click
CPM (Cost Per Mille) (Spend / Impressions) × 1000 Cost per 1,000 impressions

Portal Structure

Pages available in the Marketing Portal (marketing.mifamilias.com).

flowchart TB subgraph Public["Public Pages"] Index["/ (Login/Register)"] end subgraph Auth["Authenticated Pages"] Dash["/dashboard.html
Overview & Quick Stats"] Camp["/campaigns.html
Campaign Management"] Anal["/analytics.html
Detailed Metrics"] Bill["/billing.html
Credits & Payments"] end Index -->|Login| Dash Dash --> Camp Dash --> Anal Dash --> Bill Camp --> Anal Bill --> Anal

Page Features

Page Features
index.html
  • Login with email/password
  • Create new advertiser account
  • Demo credentials displayed
dashboard.html
  • Active campaigns count
  • 30-day impressions & clicks
  • Average CTR
  • Recent campaigns list
  • Performance chart (7 days)
campaigns.html
  • Status filter tabs
  • Campaign cards with preview
  • Create new campaign
  • Submit for review
  • Edit & resubmit rejected
  • Pause/resume active
analytics.html
  • Period selector (7/14/30/90 days)
  • Key metrics with change indicators
  • Performance over time chart
  • CTR trend chart
  • Breakdown by campaign
  • Breakdown by day of week
  • Audience insights (platform, age, hours)
  • CSV export
billing.html
  • Credit balance display
  • Monthly spend progress bar
  • Payment methods management
  • Add/remove credit cards (Stripe)
  • Set default payment method
  • Credit pack purchase (with bonus tiers)
  • Invoice history table
  • Invoice download (PDF)
  • Spend alerts configuration
  • Budget limit settings

Admin Review Process

How administrators review and approve/reject submitted campaigns.

sequenceDiagram participant Adv as Advertiser participant MP as Marketing Portal participant Admin as Admin Portal participant Reviewer as Admin User Adv->>MP: Creates campaign Adv->>MP: Submits for review MP->>Admin: Campaign added to queue Reviewer->>Admin: Opens ad-reviews.html Admin->>Reviewer: Shows pending campaigns Reviewer->>Admin: Clicks "Review" Admin->>Reviewer: Shows full details + checklist alt Approve Reviewer->>Admin: Checks all items, clicks Approve Admin->>MP: Status → Approved MP->>Adv: Email notification (approved) else Reject Reviewer->>Admin: Enters feedback, clicks Reject Admin->>MP: Status → Rejected + feedback MP->>Adv: Email notification (rejected + reason) Adv->>MP: Edits campaign Adv->>MP: Resubmits end

Review Checklist

Billing & Credits System

Prepaid credit system for advertising spend with Stripe integration.

flowchart TB subgraph Purchase["Credit Purchase"] Pack["Select Credit Pack"] Pay["Stripe Payment"] Credits["Credits Added"] end subgraph Spend["Ad Spend"] Campaign["Active Campaign"] Imp["Impression Served"] Debit["Credits Deducted"] end subgraph Alerts["Alerts"] Budget80["80% Budget Alert"] LowCredit["Low Credit Alert"] DailyLimit["Daily Limit Alert"] end Pack --> Pay Pay --> Credits Credits --> Campaign Campaign --> Imp Imp --> Debit Debit -->|Balance Check| Budget80 Debit -->|Balance Check| LowCredit Debit -->|Daily Check| DailyLimit

Credit Packs

Pack Amount Credits Bonus Effective Rate
Starter $100 10,000 0% $10 / 1,000 credits
Growth $500 52,500 +5% $9.52 / 1,000 credits
Scale $1,000 110,000 +10% $9.09 / 1,000 credits
Enterprise $2,500 287,500 +15% $8.70 / 1,000 credits

Billing API Endpoints

Method Endpoint Description
POST /advertisers/register Create advertiser account
POST /advertisers/login Authenticate (returns JWT)
GET /advertisers/profile Get advertiser profile
GET /advertisers/billing Get billing overview (balance, methods, invoices)
POST /advertisers/billing/payment-methods Add payment method (Stripe PaymentMethod)
DELETE /advertisers/billing/payment-methods/{id} Remove payment method
PUT /advertisers/billing/payment-methods/{id}/default Set default payment method
POST /advertisers/billing/credits Purchase credits (processes payment)
GET /advertisers/billing/invoices List invoices (paginated)
GET /advertisers/billing/invoices/{id} Get invoice details with line items
PUT /advertisers/billing/alerts Update alert preferences

Alert Configuration

Alert Type Default Description
Budget 80% Enabled Alert when monthly spend reaches 80% of limit
Low Credit Enabled ($50) Alert when credit balance falls below threshold
Daily Limit $1,000/day Maximum daily spend (prevents budget overruns)
Monthly Limit $10,000/mo Maximum monthly spend

Stripe Integration

The billing system supports both live Stripe and demo mode:

In demo mode, payment methods use mock card details and purchases succeed immediately without actual charges.

Roadmap

Planned features for the Marketing Portal.

Phase Features Status
Phase 1-2 Portal foundation, approval workflow Complete
Phase 3 Campaign duplication, pause/resume, editing, tags, search Complete
Phase 4 A/B testing with auto-optimize, statistical significance Complete
Phase 5 Dayparting, audience targeting, geographic/age/platform filters Complete
Phase 6 Creative library, image upload Future
Phase 7 Conversion tracking, attribution models, cohort analysis, reports Complete
Phase 8 Stripe billing, invoices, credit packs (backend complete) Complete
Phase 9 In-app messaging, notifications Future
Phase 10 REST API, webhooks Future