White Paper | skathi.ai

SKATHI White Paper
# SKATHI.AI — APPLICATION WHITE PAPER
### Strategic & Technical Specification for No-Code Development Planning

**Version:** 2.0 | **Date:** July 2026 | **Status:** Live — accepting real payments
**Domain:** skathi.ai | **Platform:** Base44 (BaaS)

---

## 1. EXECUTIVE SUMMARY

Skathi.ai is a **YouTube comment automation agent** built for creators, brands, and agencies. It scans every comment on a user's channel, uses AI to categorize and suggest replies in the creator's own voice and language, detects purchase-intent leads, and enables one-click posting back to YouTube via OAuth.

**Core value proposition:** Saves 5+ hours/week of community management by surfacing what needs attention and drafting ready-to-send replies that sound human — not like AI.

**Business model:** SaaS subscription (Starter $19/mo, Pro $49/mo, Agency $149/mo) with 7-day free trial, 30-day money-back guarantee, and a 15% monthly revenue-share referral program.

**Built by:** A video production agency with 21 years in the industry (Netflix, Sony, Samsung credits). The team lives YouTube community management daily.

---

## 2. BRAND IDENTITY

- **Name origin:** Skathi (Saturn's moon, 273rd moon, orbits in retrograde — opposite direction from all others). The metaphor: "the entire content-tech market is moving toward faceless AI. Skathi goes the other way — it helps you be yourself, faster."
- **Tagline:** "Your YouTube Comment Agent."
- **Visual language:** Dark space-craft aesthetic. Pure black (#000000) background, single accent color — burnt orange (#E85002). Sharp edges (zero border-radius globally). Monospace typography for UI elements, Space Grotesk for display, Inter for body.
- **6-color locked palette:** Black, Orange (#E85002), White (#F9F9F9), Light Gray (#A7A7A7), Gray (#646464), Dark Gray (#333333). One gradient allowed (black → red → orange → sand).

---

## 3. TECH STACK

| Layer | Technology |
|---|---|
| **Platform** | Base44 (Backend-as-a-Service: auth, database, hosting, integrations) |
| **Frontend** | React 18 + Vite + Tailwind CSS |
| **UI Library** | shadcn/ui (Radix primitives) |
| **Icons** | lucide-react |
| **Animation** | Framer Motion |
| **State/Data** | @tanstack/react-query, Base44 SDK client |
| **Backend** | Deno Deploy serverless functions (TypeScript) |
| **Database** | Base44 entity system (MongoDB-backed, JSON schemas) |
| **Auth** | Base44 platform auth (email/password, session-based) |
| **Payments** | Stripe (Live Mode) — subscriptions, webhooks, customer portal |
| **AI** | Anthropic Claude (claude-haiku-4-5) — direct API calls, NOT Base44 integration credits |
| **YouTube** | YouTube Data API v3 + YouTube Analytics API (per-user OAuth 2.0) |
| **Research** | Apify (streamers~youtube-scraper actor) for competitor/topic research |
| **Email** | Base44 Core.SendEmail integration (transactional, branded HTML) |
| **Publishing** | iOS/Android from same React codebase |

---

## 4. APPLICATION ARCHITECTURE

### 4.1 Frontend Structure

```
src/
├── App.jsx                  → Router (BrowserRouter, AuthProvider, QueryClient)
├── Layout.jsx               → Shared layout (TopBar, BottomNav, TabContainer, SkathiHelper)
├── pages/                   → Route-level pages
│   ├── LandingPage.jsx      → Public marketing page (dark space aesthetic)
│   ├── Dashboard.jsx        → Authenticated home (channel metrics, cockpit gauges)
│   ├── CommentManager.jsx   → Core product: comment inbox, AI replies, lead detection
│   ├── CommentSettings.jsx  → Comment workflow settings
│   ├── Profile.jsx          → YouTube channels, Brand Voice, company info, support, wishlist
│   ├── Plans.jsx            → Pricing/checkout page
│   ├── Research.jsx         → Apify-powered competitor research
│   ├── RevenueShare.jsx     → Referral program dashboard
│   ├── OAuthCallback.jsx    → YouTube OAuth redirect handler
│   ├── Help.jsx             → Knowledge base
│   ├── Contact.jsx          → Contact form
│   ├── Status.jsx           → System status page
│   ├── Unsubscribe.jsx      → Email unsubscribe (token-based)
│   ├── Terms.jsx / Privacy.jsx
│   ├── AdminPanel.jsx       → Admin dashboard (role: admin required)
│   ├── AdminTickets.jsx     → Support ticket management
│   ├── AdminEvents.jsx      → BillingEvent audit log
│   ├── AdminPaymentTest.jsx → Stripe test utilities
│   ├── AdminCalculatorSettings.jsx → ROI calculator admin
│   ├── GrowthCalculator.jsx → (hidden/disabled route)
│   ├── RoiCalculator.jsx    → ROI calculation tool
│   ├── Referrals.jsx        → Lead referral submission
│   ├── Home.jsx             → Alternate home
│   ├── AdminClients.jsx / AdminClientDetail.jsx
│   ├── AdminReferrals.jsx / AdminRoiCalculations.jsx
├── components/              → Reusable components
│   ├── comments/            → Comment system (SyncStateView, SyncErrorView, VideoReviveCard,
│   │                          CommentDetailPanel, CommentRow, StarterCommentPanel, etc.)
│   ├── dashboard/           → Dashboard widgets (CockpitGauge, KpiRow, UsageMeter, etc.)
│   ├── landing/             → Landing page sections (PricingCard, TrustBar, FoundersDeal, etc.)
│   ├── navigation/          → TopBar, BottomNav, TabContainer, NotificationBell
│   ├── profile/             → Profile sections (YouTubeChannelsList, ReferralPanel, etc.)
│   ├── calculator/          → ROI calculator components
│   ├── support/             → Ticket system components
│   ├── referrals/           → Lead referral components
│   ├── ui/                  → shadcn/ui primitives
│   └── SkathiHelper.jsx     → AI chatbot widget
├── hooks/                   → Custom React hooks
│   ├── useCommentData.js    → Comment sync, AI analysis, state management
│   ├── useSubscription.js   → Subscription/credit management
│   ├── useYouTubeChannels.js→ Channel CRUD
│   ├── useResearch.js       → Apify research hook
│   └── usePullToRefresh.js  → Mobile pull-to-refresh
├── lib/                     → Utilities
│   ├── AuthContext.jsx      → Auth provider
│   ├── languages.js         → 8 supported language codes
│   ├── query-client.js      → React Query client
│   └── ThemeProvider.jsx    → Dark theme enforcement
└── api/
    ├── base44Client.js      → Pre-initialized Base44 SDK
    └── entities.js          → Entity SDK wrappers
```

### 4.2 Backend Structure

All backend functions live in base44/functions/{functionName}/entry.ts — Deno Deploy serverless handlers.

### 4.3 Routing

- / → LandingPage (public, no auth)
- /Dashboard, /CommentManager, /Profile, /Plans, /Research, /RevenueShare → Authenticated user pages (wrapped in Layout + TabContainer)
- /admin, /admin/tickets, /admin/events, /admin/payment-test → Admin-only (role check)
- /oauth-callback → YouTube OAuth redirect handler
- /unsubscribe → Email unsubscribe (token-based)
- /terms, /privacy, /contact, /help, /status → Public pages

---

## 5. ENTITY MODEL (DATABASE SCHEMA)

Base44 entities are JSON schemas backed by MongoDB. Every record has built-in fields: id, created_date, updated_date, created_by_id. Row-Level Security (RLS) is platform-managed — users see only their own data unless using service role.

### 5.1 Core Business Entities

#### Subscription
**Purpose:** Tracks each user's plan, billing, and usage limits. The central entity for all credit/quota enforcement.

| Field | Type | Description |
|---|---|---|
| user_id | string | **Required.** User ID |
| plan | enum | free / starter / pro / agency |
| status | enum | active / trial / cancelled |
| subscription_status | enum | trialing / active / past_due / canceled (from Stripe) |
| stripe_customer_id | string | Stripe Customer ID |
| stripe_subscription_id | string | Stripe Subscription ID (for cancellation) |
| card_fingerprint | string | Card fingerprint (Founder deal dedup) |
| is_founder_deal | boolean | $19/mo Pro forever (FOUNDER100 promo) |
| has_used_refund_guarantee | boolean | One-time money-back guarantee tracker |
| trial_reply_count | number | Replies used during trial |
| trial_reply_cap | number | 50 (Starter), 100 (Pro) |
| replies_used_this_month | number | Monthly reply counter |
| replies_cap_this_month | number | 400 / 1500 / 5000 |
| hourly_rate_counter | number | Replies in current hour (max 50) |
| hourly_rate_window_start | datetime | Hourly window start |
| credits_used | number | AI credits consumed |
| credits_limit | number | 10 / 400 / 1500 / 5000 |
| channels_limit | number | 1 / 1 / 3 / 10 |
| period_start / period_end | date | Billing period |
| current_period_start / current_period_end | datetime | From Stripe |
| promo_code_used | string | |
| trial_ends_at | date | |
| low_credit_email_sent | boolean | Prevents duplicate emails |
| zero_credit_email_sent | boolean | |
| trial_ending_email_sent | boolean | |

#### YouTubeChannel
**Purpose:** Stores each user's YouTube channel + OAuth tokens for independent API quota.

| Field | Type | Description |
|---|---|---|
| user_id | string | **Required.** |
| user_email | string | |
| channel_url | string | **Required.** Full YouTube URL |
| channel_name | string | Display name |
| channel_id | string | YouTube channel ID (UC...) |
| is_primary | boolean | Primary channel flag |
| added_at | datetime | |
| reply_language | string | AI reply language (e.g., pl-PL, en-US) |
| detected_language | string | Auto-detected from YouTube API |
| oauth_access_token | string | Per-user OAuth token |
| oauth_refresh_token | string | Per-user refresh token |
| oauth_token_expires_at | datetime | Token expiry |
| oauth_connected | boolean | OAuth completed? |

#### BrandVoice
**Purpose:** AI voice training profile — teaches the AI how to write replies in the creator's style.

| Field | Type | Description |
|---|---|---|
| client_email | string | |
| brand_name | string | **Required.** |
| industry | enum | gaming / fitness_wellness / tech_saas / ecommerce_retail / education_coaching / lifestyle_vlog / beauty_fashion / food_cooking / finance_business / entertainment_comedy / music / other |
| industry_other | string | Custom industry |
| channel_goal | enum | community_engagement / lead_generation / drive_sales / educate_audience / brand_awareness |
| icp_description | string | Ideal Customer Profile |
| tone_of_voice | array | Max 3: casual_friendly / professional_expert / humorous_witty / inspirational / educational / warm_personal / bold_direct / sarcastic_edgy |
| voice_samples | array | 3-5 real reply examples (critical for voice training) |
| products_services | string | What the creator sells |
| cta_strategy | enum | never / soft_mention / direct_cta |
| words_to_avoid | array | AI must never use |
| preferred_words | array | Brand signature phrases |
| topics_to_avoid | array | Politics, religion, competitors, etc. |
| reply_style_notes | string | Freeform notes |

#### YoutubeComment
**Purpose:** Synced comments from YouTube, enriched with AI analysis.

| Field | Type | Description |
|---|---|---|
| youtube_comment_id | string | YouTube's comment ID |
| youtube_video_id | string | **Required.** |
| channel_id | string | |
| client_email | string | |
| author_name | string | **Required.** |
| author_avatar | string | |
| text | string | **Required.** Comment text |
| published_at | datetime | |
| status | enum | new / needs_reply / lead / drafted / approved / posted / ignored |
| category | enum | question / positive / discussion / complaint / lead_intent / low_priority |
| is_lead | boolean | Purchase intent detected |
| sentiment | number | -1 to 1 |
| suggested_reply | string | AI-generated draft |
| approved_reply | string | User-approved version |
| posted_reply | string | What was actually posted |
| posted_at | datetime | |
| internal_note | string | Team notes |
| video_title / video_thumbnail | string | |
| like_count / reply_count | number | |

#### StarterComment
**Purpose:** AI-generated "starter comments" that the creator can post under their own videos to spark discussion.

| Field | Type | Description |
|---|---|---|
| youtube_video_id | string | **Required.** |
| client_email | string | |
| video_title | string | **Required.** |
| video_thumbnail / video_published_at | | |
| suggestions | array | 3 generated options |
| selected_text | string | User's pick |
| status | enum | pending / approved / posted / dismissed |
| posted_at | datetime | |

#### CommentLog
**Purpose:** Audit trail of all posted comments (replies + starters).

| Field | Type | Description |
|---|---|---|
| user_id | string | **Required.** |
| video_title / video_id | string | |
| comment_text | string | **Required.** |
| comment_type | enum | starter / reply |
| was_copied | boolean | Manual clipboard vs direct post |
| channel_id | string | |

### 5.2 User & Profile Entities

#### ClientProfile
**Purpose:** Extended user profile with company info, social links, referral codes, and cached dashboard data.

Key fields: user_email, company_name, logo_url, referral_code (auto-generated), referred_by_code, bank details for commission payouts, social links (YouTube, Trello, Instagram, Facebook, TikTok, website), icp_description, competitors (array), business_type, target_audience, offer_type, offer_description, inspiration_channels, channel stats (stats_subscribers, stats_views, stats_videos_count, stats_reels_count, stats_watch_time, stats_ctr), trends_report, last_dashboard_cache (JSON fallback when YouTube quota exceeded).

### 5.3 Billing & Analytics Entities

#### BillingEvent
**Purpose:** Audit log for all billing-related events.

| Field | Type | Description |
|---|---|---|
| event_type | string | trial_cap_hit / monthly_cap_hit / rate_limit_hit / founder_rejected / refund_blocked / subscription_canceled / refund_processed / research_call / welcome_email_sent / admin_notification_sent / subscription_inactive |
| user_id | string | **Required.** |
| user_email | string | |
| reason | string | |
| metadata | string | JSON with extra context |

#### PromoCode
**Purpose:** Admin-created promo codes for free trial upgrades.

Fields: code, plan_granted (pro/agency), days, max_uses, times_used, active, shared_with_email, used_by_email, used_by_name, used_at.

### 5.4 Referral System Entities

#### Referral
**Purpose:** Tracks who referred whom. Status: registered → subscribed.

Fields: referrer_user_id, referrer_email, referred_user_id, referred_email, referred_name, referral_code, status.

#### LeadReferral
**Purpose:** Users submit B2B leads they've referred to Skathi. Admin manages commission tracking.

Fields: submitter info, lead info (name, company, email, phone, position, website, LinkedIn), referral_note, referral_context, lead_potential (low/medium/high/unknown), status (12-state pipeline: submitted → won/lost), commission_type (fixed/percentage), commission_amount, commission_status (not_eligible/pending/approved/paid).

#### LeadMessage
**Purpose:** Threaded messages between user and admin about a specific lead.

### 5.5 Support System Entities

#### SupportTicket
**Purpose:** In-app support tickets with screenshot, browser info, referrer URL, and optional pre-filled chat history.

Fields: ticket_number (SK-XXXX), user_id, subject, category (bug_report/feature_request/billing/youtube_issue/account_issue/other), priority, status (open/in_progress/resolved/closed), description, screenshot_url, browser_info, referrer_url, from_chat_history.

#### TicketMessage
**Purpose:** Threaded messages on a ticket. author_type: user/admin/system.

### 5.6 Engagement & Notification Entities

#### Notification
**Purpose:** In-app notifications. Types: welcome, channel_added, plan_upgraded, credits_low, credits_zero.

#### WishlistItem
**Purpose:** User-submitted feature requests/bug reports/praise. Community voting system. Admin can respond and set status (new/under_review/planned/shipped/wont_do).

### 5.7 Research Entities

#### CacheYouTube
**Purpose:** 24-hour cache for Apify research results (reduces API costs).

Fields: cache_key (type:query), cache_type (channel/videos/search/trending), payload (JSON), fetched_at, expires_at.

### 5.8 Calculator Entities

#### CalculatorSettings / EstimationScenario / PricingModule
**Purpose:** ROI/Growth calculator configuration. Admin-managed pricing modules, estimation scenarios (conservative/realistic/ambitious), and global settings.

#### SavedQuote / RoiCalculation
**Purpose:** Saved calculation results for clients.

### 5.9 Secondary Entities (Referenced)

- **CommentAnalysis** — AI analysis results
- **SuperFan** — Returning commenter detection
- **InsightBrief** — AI-generated channel insights
- **ContentItem / ProjectUpdate / Message** — Content pipeline management
- **CommentActivity** — Engagement timeline
- **ClientReport** — Generated client reports
- **ReferralPayout / ReferralCommission** — Commission payout tracking

### 5.10 Built-in Entity

#### User
**Platform-managed.** Cannot be created via SDK. Fields: id, created_date, full_name, email, role (admin / user). Users join via invites (base44.users.inviteUser(email, role)). Built-in security: only admins can list/update/delete other users.

---

## 6. BACKEND FUNCTIONS (Complete Inventory)

All functions are Deno Deploy serverless handlers in base44/functions/{name}/entry.ts. They use createClientFromRequest(req) for auth context and base44.asServiceRole for admin operations.

### 6.1 YouTube Integration Functions

#### youtubeOAuth
**Purpose:** YouTube OAuth 2.0 handler — generates auth URLs, exchanges codes for tokens, refreshes tokens.

**Actions:**
- get_auth_url → Returns Google consent URL. Forces prompt=consent on first connection, prompt=none on reconnects. Scopes: youtube.force-ssl + youtube.readonly.
- exchange_code → Exchanges authorization code for access/refresh tokens, fetches channel info via channels?mine=true, creates or updates YouTubeChannel record with tokens.
- refresh_token → Manually refreshes a channel's access token.

**OAuth flow:**
1. Frontend calls youtubeOAuth({ action: "get_auth_url", channelRecordId })
2. User redirected to Google consent
3. Google redirects to /oauth-callback?code=xxx&state=channelRecordId
4. OAuthCallback.jsx calls youtubeOAuth({ action: "exchange_code", code, channelRecordId })
5. Tokens saved to YouTubeChannel entity

#### fetchComments
**Purpose:** Fetches recent videos (max 15) and their comments for a user's channel.

**Flow:**
1. Auth check → find user's YouTubeChannel record
2. **CHECK 1:** OAuth connected? → NEEDS_YOUTUBE_CONNECTION if not
3. **CHECK 2:** Get valid access token (auto-refresh with 60s buffer) → NEEDS_RECONNECT if refresh fails
4. Resolve channel ID from URL (supports /channel/UC..., /@handle, /c/name, /user/name)
5. Fetch channel info (channels?part=snippet,statistics)
6. Fetch recent videos from uploads playlist (playlistItems → videos for details)
7. Fetch comments for each video in batches of 5 (commentThreads?part=snippet&order=relevance)
8. Mark owner comments (isOwnerComment) by comparing authorChannelId with channel ID
9. Return structured response with quota tracking

**Error codes:** NEEDS_YOUTUBE_CONNECTION (403), NEEDS_RECONNECT (401), QUOTA_EXHAUSTED (429), SYNC_ERROR (400/500), SERVER_ERROR (500)

**Quota tracking:** Logs YouTube Data API v3 unit costs per call. Typical sync: ~20 units.

#### postYoutubeReply
**Purpose:** Posts a reply to a YouTube comment using the channel owner's OAuth token.

**Flow:** Auth → find channel → OAuth checks → POST /youtube/v3/comments with parentId and textOriginal. Returns { success, commentId, commentMode: "owner" }.

#### postStarterComment
**Purpose:** Posts a top-level "starter comment" under the creator's own video.

**Flow:** Auth → find channel → OAuth checks → POST /youtube/v3/commentThreads with videoId and textOriginal.

#### youtube (Legacy)
**Purpose:** Dashboard data fetcher — channel statistics, video insights, analytics. Uses user OAuth tokens with token refresh. Limited to 3 pages (max 150 videos) to conserve quota. Has last_dashboard_cache fallback on ClientProfile when quota exceeded.

#### fetchDashboardData
**Purpose:** Alternative dashboard data fetcher using user OAuth tokens with refresh logic.

#### fetchVideoMeta
**Purpose:** Fetches metadata for a specific video (used by VideoReviveCard for starter comment generation).

#### onYouTubeChannelAdded
**Purpose:** Entity automation trigger — fires when a YouTubeChannel is created. Sends "channel connected" email and notification.

### 6.2 AI Functions

#### analyzeComments
**Purpose:** AI analysis of a batch of YouTube comments using Claude Haiku.

**Flow:**
1. Auth check
2. Filter out owner comments (they're never analyzed for "needs_reply")
3. **Credit check:** credits_used >= credits_limit → ANALYSIS_LIMIT (comments still display, just no AI suggestions)
4. Build prompt with language instructions + brand voice context
5. Call Anthropic API directly (claude-haiku-4-5, max 4096 tokens)
6. Parse JSON response, map back to original comment indices
7. Return per-comment: category, is_lead, status (needs_reply/ignored), suggested_reply

**Supported languages:** en-US, en-GB, es-ES, pt-BR, pl-PL, it-IT, sv-SE, uk-UA

**Prompt rules:**
- 1-3 sentence replies max
- Sound human, never AI ("Great question!", "Thanks for sharing!" banned)
- Match commenter's energy
- No hashtags, max 1 emoji
- Don't start with commenter's name
- CTA strategy from BrandVoice (never/soft_mention/direct_cta)

#### replyGuard
**Purpose:** Central guard function wrapping ALL AI reply generation with 4 safety checks. Also handles starter comment generation in mode: "starter".

**4 ordered guard checks:**
1. **Subscription status** — canceled/past_due → SUBSCRIPTION_INACTIVE (403)
2. **Trial cap** — trial_reply_count >= trial_reply_cap → TRIAL_CAP_HIT (403). Increments trial counter.
3. **Monthly cap** — replies_used_this_month >= replies_cap_this_month → MONTHLY_CAP_HIT (403). Increments both replies_used_this_month and credits_used.
4. **Hourly rate limit** — hourly_rate_counter >= 50 → RATE_LIMIT_HIT (429). 1-hour rolling window.

**After all checks pass (1 credit consumed):**
- **Reply mode:** Calls Anthropic API directly (same logic as analyzeComments)
- **Starter mode:** Generates 3 starter comment options (provocative question, bold thesis, invitation to discuss)

**All billing events logged** to BillingEvent entity.

#### generateStarterComments
**Purpose:** Standalone starter comment generation (legacy/alternate path).

### 6.3 Stripe/Billing Functions

#### stripeCheckout
**Purpose:** Creates Stripe Checkout sessions.

**Flow:**
1. Auth check
2. Map priceKey (e.g., pro_monthly) to Stripe Price ID
3. **Founder deal check:** If isFounderDeal, check for refund block in Stripe customer metadata → reject if blocked
4. Create checkout session with mode: subscription, 7-day trial for Starter/Pro, Founder deal applies FOUNDER100 promotion code
5. Metadata: base44_app_id, user_id, user_email, plan, billing, is_founder_deal
6. Return checkout URL

**Stripe Price IDs:**
| Plan | Monthly | Annual |
|---|---|---|
| Starter ($19) | price_1TZcEJKHiymLkWn7zCAFhffP | price_1TZcEJKHiymLkWn7bvPHYyuh |
| Pro ($49) | price_1TZcEJKHiymLkWn7KKWxR409 | price_1TZcEJKHiymLkWn7ULXvANcU |
| Agency ($149) | price_1TZcEJKHiymLkWn7wGbxhWpZ | price_1TZcEJKHiymLkWn7VG19FuDR |

#### stripeWebhook
**Purpose:** Handles all Stripe webhook events. This is the source of truth for subscription state.

**Handled events:**
- checkout.session.completed → Creates/updates Subscription with plan, credits, trial status. Sends welcome email + admin notification. Creates in-app notification.
- customer.subscription.updated → Syncs status, period dates. Detects plan changes from metadata. Resets usage on trial→active conversion.
- customer.subscription.deleted → **Immediate revocation** (no grace period). Downgrades to free, sets credits_limit=10, replies_cap=0.
- invoice.payment_succeeded → Resets monthly usage counters. Resets email flags.
- invoice.payment_failed → Marks subscription past_due. Sends payment failed email.
- charge.refunded → Revokes access immediately. Sets has_used_refund_guarantee=true. Blocks Founder resubscription for 90 days.

**Webhook signature verification:** Uses stripe.webhooks.constructEventAsync() (async, SubtleCrypto — synchronous version throws in Deno).

#### stripePortal
**Purpose:** Creates Stripe Billing Portal sessions for self-service subscription management.

#### cancelSubscription
**Purpose:** Cancels a Stripe subscription immediately.

#### adminRefund
**Purpose:** Admin-initiated refund processing.

#### founderEligibility
**Purpose:** Checks if a user is eligible for the Founder's Deal (FOUNDER100 promo). Deduplicates by card fingerprint.

#### paymentAudit
**Purpose:** Audit log for payment-related admin actions.

### 6.4 Research Function

#### skathiResearch
**Purpose:** Apify bridge for YouTube competitor/topic research. Does NOT touch own-channel data (that stays on official YouTube API).

**Flow:**
1. Auth check
2. **Cache check:** Look for CacheYouTube record with cache_key = type:query not expired (24h TTL) → return cached
3. **User daily limit:** Check BillingEvent count for research_call today. Limits: free=3, starter=10, pro=30, agency=100
4. **Global daily cap:** 500 calls across ALL users (cost protection)
5. Call Apify actor streamers~youtube-scraper (run-sync-get-dataset-items)
6. Normalize results to standard shape
7. Save/update cache
8. Log BillingEvent with event_type: research_call

**Query types:** search, channel, videos, trending

### 6.5 User Lifecycle Functions

#### onUserRegistered
**Purpose:** Entity automation trigger — fires on User creation.

**Actions:**
1. Create Subscription (free, 10 credits, 1 channel)
2. Send welcome email
3. Create in-app welcome notification
4. Generate referral code (6-char uppercase) → create ClientProfile
5. If ?ref= was used, create Referral record (status: registered)
6. Notify admin

#### applyReferralCode
**Purpose:** Applies a pending referral code to a user's profile and creates the Referral record. Uses service role to bypass RLS.

#### deleteMyAccount
**Purpose:** Secure account deletion. Identity from session only (never from body).

**Cascading deletes:** YouTubeChannel, Subscription, CommentLog, Notification, SupportTicket, WishlistItem, BillingEvent, TicketMessage (by user_id) → BrandVoice, YoutubeComment, StarterComment, LeadMessage (by email) → ClientProfile (last). Auth account cannot be deleted from function — caller must hard-logout.

#### dailyChecks
**Purpose:** Scheduled daily function. Checks for trials ending within 3 days → sends warning email (once per subscription via trial_ending_email_sent flag).

#### checkCreditEmails
**Purpose:** Called after credit consumption. Sends low-credit (≥80% used) and zero-credit emails. Prevents duplicates via boolean flags.

### 6.6 Admin Functions

#### adminActions
**Purpose:** Single service-role function for all admin mutations. Replaces direct frontend SDK calls.

**Security:**
- base44.auth.me() required; role !== "admin" → 403
- Identity from session only
- remove_admin: refuses if target email in PROTECTED_EMAILS (daras@video-concierge.com, daras@woodpeckermp.pl)

**Actions:**
- change_plan — Validates plan, sets limits server-side
- reset_credits — Resets credits_used and replies_used_this_month to 0
- remove_admin — Downgrades user role to "user"

#### adminNotify
**Purpose:** Sends admin notifications (new user, new customer, cancellation, promo used, etc.).

#### wishlistAdmin
**Purpose:** Admin management of wishlist items (respond, change status).

#### submitTicket / replyToTicket
**Purpose:** Support ticket creation and threaded replies.

### 6.7 Communication Functions

#### sendTransactionalEmail
**Purpose:** Central email sender. Builds branded HTML emails (dark theme, orange accents).

**Email types:** welcome, welcome_paid (5-step onboarding), channel_added, upgrade, low_credits, zero_credits, cancellation, trial_ending, payment_failed

**Email design:** Dark (#000000/#0A0A0A) background, Skathi branding, orange (#E85002) CTAs, unsubscribe token links.

#### emailTemplates
**Purpose:** Email template management/utilities.

#### skathiHelper
**Purpose:** AI chatbot backend for the in-app SkathiHelper widget.

#### unsubscribe
**Purpose:** Token-based email unsubscribe handler.

---

## 7. AUTOMATIONS

| Name | Type | Trigger | Function |
|---|---|---|---|
| Daily Checks | Scheduled | Daily | dailyChecks — trial expiry warnings |
| On User Registered | Entity | User.create | onUserRegistered — creates Subscription, ClientProfile, sends welcome |
| On YouTube Channel Added | Entity | YouTubeChannel.create | onYouTubeChannelAdded — sends confirmation email |
| Stripe Webhook | Connector | Stripe events | stripeWebhook — subscription lifecycle |

---

## 8. PRICING & PLAN STRUCTURE

| Feature | Free | Starter ($19/mo) | Pro ($49/mo) | Agency ($149/mo) |
|---|---|---|---|---|
| **AI Credits/month** | 10 | 400 | 1,500 | 5,000 |
| **Channels** | 1 | 1 | 3 | 10 |
| **Trial reply cap** | — | 50 | 100 | — |
| **7-day trial** | — | Yes | Yes | No |
| **Voice training** | Basic | 50 replies | Full history | Per-client profiles |
| **Sentiment dashboard** | — | — | Yes | Yes |
| **CSV export** | — | — | Yes | Yes |
| **Team seats** | — | — | — | 5 |
| **White-label reports** | — | — | — | Yes |
| **API access** | — | — | — | Yes |
| **Dedicated manager** | — | — | — | Yes |

**Annual billing:** ~20% discount (Starter $180/yr, Pro $468/yr, Agency $1428/yr)

**Founder's Deal:** FOUNDER100 promo code → Pro at $19/mo forever. Deduplicated by card fingerprint. Blocked for 90 days after refund.

**Money-back guarantee:** 30-day, one-time per account (has_used_refund_guarantee).

---

## 9. CREDIT & RATE LIMITING SYSTEM

All credit consumption is **server-side** in replyGuard. The frontend (useSubscription.checkAndConsumeCredit) only handles housekeeping (period reset, trial expiry) — it does NOT increment credits.

### Enforcement order (replyGuard):
1. **Subscription status** — canceled/past_due blocked
2. **Trial cap** — 50 (Starter) / 100 (Pro) during trial
3. **Monthly cap** — 400 / 1500 / 5000 for active subscriptions
4. **Hourly rate** — 50 replies/hour (all users, anti-spam protection)

Each check increments the relevant counter and logs a BillingEvent on failure.

### Separate credit checks:
- analyzeComments checks credits_used >= credits_limit before calling Anthropic → returns ANALYSIS_LIMIT (comments still display, AI suggestions disabled)
- skathiResearch has its own daily limits (3/10/30/100 by plan) + global 500/day cap

---

## 10. EXTERNAL API INTEGRATIONS

### 10.1 YouTube Data API v3
- **Auth:** Per-user OAuth 2.0 (not shared API key)
- **Scopes:** youtube.force-ssl (read/write comments), youtube.readonly
- **Quota:** 10,000 units/day per Google Cloud project (shared across project, NOT per-user)
- **Token refresh:** 60-second buffer, auto-refresh before each API call, tokens persisted to YouTubeChannel
- **Unit costs:** channels.list=1, playlistItems.list=1, videos.list=1, commentThreads.list=1, comments.insert=50, commentThreads.insert=50

### 10.2 YouTube Analytics API
- Used for watch time, CTR (private data, manual input fallback)
- Accessed via same OAuth tokens

### 10.3 Anthropic Claude
- **Model:** claude-haiku-4-5 (fast, cost-effective)
- **Direct API calls** (NOT Base44 integrations) to avoid burning integration credits
- **Max tokens:** 4096 (reply analysis), 2048 (starter comments)
- **Fallback:** If ANTHROPIC_API_KEY not set, falls back to base44.integrations.Core.InvokeLLM with claude_sonnet_4_6 (costs integration credits)

### 10.4 Stripe
- **Mode:** Live (accepting real payments)
- **Products:** Skathi Starter ($19), Skathi Pro ($49), Skathi Agency ($149)
- **Features:** Subscriptions, 7-day trials, promotion codes (FOUNDER100), customer portal, webhooks
- **Webhook events:** checkout.session.completed, customer.subscription.updated/deleted, invoice.payment_succeeded/failed, charge.refunded

### 10.5 Apify
- **Actor:** streamers~youtube-scraper
- **Mode:** run-sync-get-dataset-items (synchronous)
- **Cache:** 24h TTL in CacheYouTube entity
- **Purpose:** Competitor research, topic search, trending videos (NOT own-channel data)

### 10.6 Google OAuth 2.0
- **Endpoints:** accounts.google.com/o/oauth2/v2/auth, oauth2.googleapis.com/token
- **Redirect URI:** From YOUTUBE_OAUTH_REDIRECT_URI secret (must match Google Cloud Console exactly)
- **Consent:** prompt=consent on first connection, prompt=none on reconnects

---

## 11. ENVIRONMENT VARIABLES / SECRETS

| Secret | Purpose |
|---|---|
| STRIPE_SECRET_KEY | Stripe API (live mode) |
| STRIPE_PUBLISHABLE_KEY | Stripe frontend |
| STRIPE_WEBHOOK_SECRET | Webhook signature verification (live) |
| STRIPE_TEST_SECRET_KEY | Stripe test mode |
| STRIPE_TEST_PUBLISHABLE_KEY | Stripe test frontend |
| STRIPE_TEST_WEBHOOK_SECRET | Test webhook verification |
| ANTHROPIC_API_KEY | Claude AI direct API calls |
| YOUTUBE_OAUTH_CLIENT_ID | Google OAuth client ID |
| YOUTUBE_OAUTH_CLIENT_SECRET | Google OAuth client secret |
| YOUTUBE_OAUTH_REDIRECT_URI | OAuth callback URL (skathi.ai/oauth-callback) |
| YOUTUBE_API_KEY | Legacy shared API key (deprecated, kept for fallback) |
| YOUTUBE_OAUTH_REFRESH_TOKEN | Legacy shared refresh token (deprecated) |
| APIFY_TOKEN | Apify API token for research actor |
| BASE44_APP_ID | Auto-populated by platform |

---

## 12. SECURITY MODEL

### 12.1 Authentication
- Platform-managed (Base44 auth): email/password, session-based
- base44.auth.me() in every function — returns user or 401
- base44.auth.isAuthenticated() for frontend checks
- base44.auth.redirectToLogin(nextUrl) for login flow
- base44.auth.logout(redirectUrl) for logout

### 12.2 Authorization
- **RLS (Row-Level Security):** Platform-managed. Users see only their own entities.
- **Service role:** base44.asServiceRole bypasses RLS for admin operations. Used in: stripeWebhook, onUserRegistered, dailyChecks, adminActions, checkCreditEmails, applyReferralCode, deleteMyAccount, skathiResearch.
- **Admin role:** user.role === "admin" checked in adminActions, AdminPanel, AdminTickets, AdminEvents. Protected emails cannot be demoted.

### 12.3 Data Security
- **Identity from session:** deleteMyAccount, adminActions never trust body for user identity
- **OAuth tokens:** Per-user, stored in YouTubeChannel entity, auto-refreshed
- **Stripe webhook:** Signature verified with constructEventAsync (async SubtleCrypto)
- **No shared API keys for YouTube:** Each user has independent OAuth quota
- **Card fingerprint dedup:** Prevents Founder deal abuse across accounts
- **Refund block:** 90-day block on Founder resubscription after refund

### 12.4 Frontend Security
- AdminPanel access: role === "admin" only (no PIN, platform-enforced)
- Checkout: iframe check blocks checkout from embedded contexts
- All sensitive mutations go through backend functions (never direct SDK calls from frontend)

---

## 13. DESIGN SYSTEM

### 13.1 Color Palette (Locked — 6 colors + 1 gradient)
| Token | Hex | Usage |
|---|---|---|
| --s-black | #000000 | Primary background |
| --s-orange | #E85002 | Branding accent, CTA |
| --s-white | #F9F9F9 | Primary text |
| --s-light-gray | #A7A7A7 | Secondary text, icons |
| --s-gray | #646464 | Muted text, disabled |
| --s-dark-gray | #333333 | Elevated surfaces, borders |
| --s-gradient | linear-gradient(135deg, #000 0%, #C10801 33%, #F16001 66%, #D9C3AB 100%) | Max 2x in entire app |

### 13.2 Typography
| Role | Font | Usage |
|---|---|---|
| Display | Space Grotesk (700, -0.02em) | Headings, hero text |
| Body | Space Grotesk / Inter (300) | Paragraphs, descriptions |
| Mono | JetBrains Mono (var(--skathi-font-mono)) | UI labels, buttons, code, nav |

### 13.3 Global Rules
- **Zero border-radius** globally
- Hidden scrollbars globally
- Sharp focus rings (1px orange)
- Dark selection highlight
- user-select: none on interactive elements
- 8pt spacing grid

### 13.4 Component Patterns
- **Buttons:** Orange CTA (primary), outlined (secondary/outline), ghost (tertiary). All uppercase, mono font, letter-spacing.
- **Cards:** #111111 bg, #333333 border, hover → orange border + translateY(-2px)
- **Forms:** #0D0D0D input bg, #333333 border, mono placeholders
- **Tables:** Dense, edge-to-edge, no rounded corners

---

## 14. KEY USER FLOWS

### 14.1 New User Onboarding
1. User visits skathi.ai → sees LandingPage
2. Clicks "Enter Orbit" → redirected to Base44 login
3. After registration → onUserRegistered automation fires:
   - Creates Subscription (free, 10 credits)
   - Creates ClientProfile with referral code
   - Sends welcome email
   - If ?ref= present → creates Referral record
4. User lands on Dashboard → prompted to connect YouTube channel
5. User goes to Profile → adds YouTube channel URL
6. User clicks "Connect" → YouTube OAuth flow
7. After OAuth → onYouTubeChannelAdded fires → confirmation email
8. User fills BrandVoice profile (niche, tone, voice samples)
9. User opens CommentManager → first sync → AI analysis → first reply

### 14.2 Comment Management Flow
1. User opens CommentManager → selects channel
2. fetchComments syncs videos + comments via OAuth
3. analyzeComments categorizes comments, suggests replies
4. User reviews inbox: filter by category, lead status, needs_reply
5. For each comment: edit AI draft → approve → postYoutubeReply (direct post) or copy to clipboard
6. replyGuard enforces all limits before each AI generation
7. CommentLog records every posted comment

### 14.3 Starter Comment Flow
1. User opens VideoReviveCard for a video
2. fetchVideoMeta gets video details + transcript
3. replyGuard (mode: starter) generates 3 comment options
4. User selects one → postStarterComment posts to YouTube
5. StarterComment entity tracks status

### 14.4 Subscription Flow
1. User visits /Plans → selects plan + billing (monthly/annual)
2. stripeCheckout creates checkout session (with trial if applicable)
3. User completes Stripe Checkout
4. stripeWebhook receives checkout.session.completed:
   - Creates/updates Subscription with plan, credits, trial status
   - Sends welcome_paid email (5-step onboarding)
   - Sends admin notification
   - Creates in-app notification
5. User redirected to /welcome

### 14.5 Referral Flow
1. User shares their referral link (skathi.ai?ref=CODE)
2. New user registers with ?ref= → onUserRegistered creates Referral (status: registered)
3. When referred user subscribes → Stripe webhook → Referral status → subscribed
4. Referrer earns 15% monthly per active referral + 5% on second-tier
5. Commission tracked via LeadReferral / ReferralPayout / ReferralCommission entities

### 14.6 Research Flow
1. User opens Research page
2. Enters search query or channel URL
3. skathiResearch checks 24h cache → if miss, calls Apify
4. Results displayed with video thumbnails, views, channel info
5. Daily limits enforced per plan + global 500/day cap

---

## 15. ERROR HANDLING ARCHITECTURE

### Standardized error response format:
```json
{ "success": false, "error": "User-friendly message", "errorCode": "ERROR_CODE" }
```

### Error codes & user-facing Polish messages:
| Code | Meaning | User Message (PL) |
|---|---|---|
| NEEDS_YOUTUBE_CONNECTION | No OAuth connection | "Połącz swój kanał YouTube, aby synchronizować komentarze." |
| NEEDS_RECONNECT | Token refresh failed | "Połączenie z YouTube wygasło — połącz kanał ponownie." |
| QUOTA_EXHAUSTED | YouTube API quota hit | "Osiągnięto dzienny limit YouTube — spróbuj ponownie za jakiś czas." |
| ANALYSIS_LIMIT | AI credits exhausted | "Analiza AI niedostępna — wyczerpane kredyty." |
| SYNC_ERROR | YouTube API error | "Coś poszło nie tak przy synchronizacji." |
| SERVER_ERROR | Generic server error | "Coś poszło nie tak przy synchronizacji." |
| SUBSCRIPTION_INACTIVE | Canceled/past_due | "Subscription inactive. Update your billing." |
| TRIAL_CAP_HIT | Trial limit reached | "Trial reply limit reached." |
| MONTHLY_CAP_HIT | Monthly limit reached | "Monthly reply limit reached." |
| RATE_LIMIT_HIT | Hourly limit (50/hr) | "Rate limit reached (50 replies/hour)." |

Frontend SyncErrorView component renders appropriate UI for each code (OAuth connect button, reconnect button, retry button, or info-only state).

---

## 16. KNOWN ISSUES & TECHNICAL DEBT

1. **YouTube API daily quota (10K units)** is shared across the entire Google Cloud project — not truly per-user despite per-user OAuth
2. **GrowthCalculator route** is hidden/disabled
3. **StarterCommentPanel handleRegenerate** lacks user-facing toast feedback
4. **deleteMyAccount** does not purge secondary entities (CommentAnalysis, SuperFan, InsightBrief)
5. **analyzeComments** has a separate credit check from replyGuard — potential for slight inconsistency
6. **Legacy youtube function** uses shared API key as fallback (should be fully migrated to OAuth)
7. **LandingPage.jsx** is ~1000 lines — should be split into sub-components
8. **No connector automations** active yet (Slack, Gmail, etc. available but not connected)

---

## 17. AUTOMATION OPPORTUNITIES (Not Yet Built)

Based on the existing architecture, these are logical next-step automations:

1. **Auto-reply scheduling** — Queue approved replies for optimal posting times (first-hour priority)
2. **Weekly digest emails** — Sentiment summary, top comments, engagement metrics (Pro plan feature)
3. **Returning commenter detection** — Auto-tag SuperFans, prioritize their comments
4. **Spam/toxicity auto-filter** — Auto-ignore comments matching patterns
5. **Multi-channel sync scheduler** — Rotate channels to conserve quota
6. **Slack/Discord alerts** — Real-time notification for leads or high-priority comments
7. **API access for Agency plan** — Webhook integrations for programmatic comment management

---

## 18. FILE COUNT & SCALE

- **Frontend pages:** ~30
- **Frontend components:** ~120+
- **Backend functions:** 31
- **Database entities:** ~25
- **Automations:** 4 (2 entity, 1 scheduled, 1 connector)
- **Environment secrets:** 14

---

## 19. CONTACT & ADMIN

- **Protected admin emails:** daras@video-concierge.com, daras@woodpeckermp.pl
- **Booking:** cal.com/dariusz-kabsch-xjbwvl
- **Support:** In-app ticket system (SupportTicket entity)
- **AI Helper:** In-app SkathiHelper chatbot widget

---

*This document represents the complete technical and strategic state of the Skathi.ai platform as of July 2026. It is intended for no-code strategic planning of future development phases.*
Kliknij w tekst → Ctrl+A → Ctrl+C, lub użyj przycisku "Kopiuj"
This site uses cookies
We use essential cookies for the app to function, and optional analytics cookies. Learn more in our Privacy Policy.