# Aihub Ads Platform — Product Plan

## Vision

Ads is a **hub module** on Aihub — not a separate product. One user account, one app, same login as Machines, Casino, Forex, and Surveys.

Inside the **Ads hub**, users can:

1. **Watch & earn** — subscribe to an Ads plan, view image/posters or videos, earn UGX to wallet.
2. **Advertise** — register as a person or company on the **same account**, fund a campaign from platform balance, upload poster or video, and publish ads for others to watch.

The platform takes a fee per completed view. Admin approves business profiles and campaigns (same trust model as KYC and deposits).

---

## Module model (no separation)

| Concept | How it works |
|---------|----------------|
| Login | Existing member auth only (`users` + phone) |
| Hub entry | **Hubs → Ads** (`modules.slug = 'ads'`) |
| Earn access | Active **Ads subscription** (`plan_type = 'ads'`) |
| Post access | Approved **ad profile** on same `user_id` (individual or company) |
| Money in | Existing **deposit / balance** flows |
| Money out (rewards) | Existing **wallet** (`creditWallet` → main) |
| Admin | One **Admin → Ads** section (like Casino, Surveys) |

**There is no:**

- Separate advertiser website or portal  
- Separate advertiser username/password  
- Separate `advertiser_login` or `user_type = 'advertiser'` tokens  
- Second app or second registration funnel  

---

## Ads hub layout (single screen, tabs)

Same pattern as **Forex Terminal** (Terminal | Academy | Signals) or **Football Hub** tabs:

| Tab | Who | Gate |
|-----|-----|------|
| **Watch & Earn** | Any subscriber | Ads subscription required |
| **Post an Ad** | User with approved ad profile | Profile approved by admin |
| **My Campaigns** | Same user | Shows drafts, pending, active, ended |
| **My Earnings** | Subscriber | History of ad rewards |

If user has no subscription → Watch tab shows paywall → **Subscriptions** (existing `uGo('subs')`).

If user has no ad profile → Post tab shows “Register your business” form on same screen.

---

## Parties (all = same `users` table)

### Viewer (earn)

- Normal Aihub user.
- **Must subscribe** to an Ads plan before watching paid ads.
- Watches posters (timer) or videos (min progress), earns per completion.

### Advertiser (post)

- **Same user** — not a different account type.
- Completes **ad profile** once: individual name OR company name, category, optional reg number.
- Admin approves profile → user can create campaigns.
- Funds campaigns from **investment balance** (`users.balance`) or approved deposit tagged for ads (admin setting).

### Admin

- Approves ad profiles and campaigns.
- Sets economics: CPV, platform fee %, daily earn caps, min watch time.
- Moderates media (image/video).

---

## What advertisers post

| Ad type | Media | Viewer action |
|---------|--------|----------------|
| **Poster / image** | JPG, PNG, WebP | View X seconds; optional open link |
| **Video** | MP4 | Watch min duration; optional CTA |
| **Click-through** | Image or video + URL | Visit site / WhatsApp after watch |

Each campaign: title, description, media, optional target URL, budget (UGX), schedule.

---

## Money flow

```
User (advertiser) allocates budget from balance → ad_campaigns.budget
        ↓
Other users (subscribers) watch & complete ad
        ↓
Viewer reward → creditWallet(main) + logTx('Ad Reward')
        ↓
Platform fee retained in campaign accounting
        ↓
Campaign pauses when budget exhausted
```

**Funding campaigns**

- User taps “Fund campaign” → debits `users.balance` (same pool as machine purchase / other subs).
- Optional: allow wallet transfer to “ad budget” via existing wallet module later — MVP uses balance debit.

**Earning**

- `creditWallet()` + `notify()` — aligned with wallet service, not legacy direct SQL.

---

## Subscription gate (required to earn)

Users **cannot** earn from watching until they have an active **Ads** subscription.

| Plan (example) | Duration | Price | Perk |
|----------------|----------|-------|------|
| Ads Weekly | 7 days | UGX 5,000 | Watch & earn access |
| Ads Monthly | 30 days | UGX 15,000 | Higher daily earn cap |

- `subscription_plans.plan_type = 'ads'`
- Pay from `users.balance` via existing `subscribe` API
- `unlock_rules` on module `ads`: `rule_type = 'subscription'`

**Note:** Subscription is for **watching/earning only**. Posting ads uses ad profile approval + balance, not necessarily the same sub (admin can add rule later if desired).

---

## Campaign rules

### Create campaign (Post tab)

1. User has approved `ad_profiles` row.
2. Choose image or video, upload, set budget from balance.
3. Submit → `pending` → admin approve → `active`.

### Complete ad (Watch tab)

1. User has active Ads subscription.
2. Open ad → timer or video progress.
3. Server validates → pay reward → decrement campaign budget.

### Fraud

- One completion per user per campaign per 24h (default).
- Daily earn cap per user.
- Min watch time / min video %.
- Cannot complete own campaigns.
- `fraud_events` on abuse patterns.

---

## Module registration in platform

```text
modules
  slug: ads
  name: Ads
  description: Watch ads to earn, or post your business ads

subscription_plans
  plan_type: ads  (for watch/earn access)

ad_profiles
  user_id → users.id  (business registration, not separate login)

ad_campaigns
  user_id → users.id  (owner = poster)
```

---

## Revenue (platform)

| Stream | Description |
|--------|-------------|
| Ads subscriptions | Weekly/monthly earn access |
| Platform fee | % of each completed view |
| Featured pin | Optional paid boost in feed |

---

## Phased rollout

### Phase 1 — MVP
- `ads` module + hub card + Ads subscription plans
- Watch tab: image ads, timer, wallet reward
- Post tab: ad profile form + campaign create
- Admin: approve profiles & campaigns

### Phase 2
- Video ads, My Campaigns stats, My Earnings history

### Phase 3
- Featured ads, missions (“watch 5 ads”), leaderboard

---

## Decisions (locked)

| Topic | Decision |
|-------|----------|
| Separate advertiser login? | **No** — same user account |
| Separate portal? | **No** — tabs inside Ads hub |
| Advertiser identity | `ad_profiles` linked to `user_id` |
| Campaign owner | `ad_campaigns.user_id` |
| Earn gate | Ads subscription module unlock |
| Post gate | Approved ad profile + sufficient balance |