TopAds v4.2.2 Production

TopAds is an enterprise-grade omnichannel SaaS platform for customer conversations, CRM, sales, marketing automation, billing, and workflow orchestration — self-hostable and CodeCanyon-ready.

Overview

TopAds unifies WhatsApp, Instagram, Messenger, Email, SMS, and Live Chat into a single omnichannel inbox, powered by an AI Assistant, no-code Workflow Builder, and a full Business Intelligence suite. It ships with a Setup Wizard, PWA, role-based access, demo mode, and multi-tenant SaaS billing.

Features Summary

Tech Stack

Installation Guide

This is the definitive path for self-hosting TopAds. Follow every step in order.

System Requirements

1. Environment Setup

Clone the repository and copy the example environment file:

git clone https://your-repo/topads.git
cd topads
cp .env.example .env

2. Install Dependencies

# with bun (recommended)
bun install

# or npm
npm install

3. Database Setup

TopAds uses Supabase Postgres. Create a project, then apply the shipped migrations:

npx supabase link --project-ref <YOUR_PROJECT_REF>
npx supabase db push

4. Configure Environment Variables

Fill in the required values in .env. See Configuration Guide for the full reference.

5. First Run

bun run dev
# open http://localhost:8080

On first launch the app auto-redirects to /setup. Complete the 6-step wizard to create the Super Admin, apply branding, configure SMTP, and lock installation.

Build & Deployment

Development Build

bun run dev            # hot-reload dev server on :8080
bun run typecheck      # tsgo --noEmit
bun run lint           # eslint

Production Build

bun run build          # emits .output/
bun run start          # serves the production bundle

VPS / Bare-Metal Deployment

1. Provision Ubuntu 22.04+, install Node 22 LTS.
2. Clone repo, install deps, build the app.
3. Run under pm2 or systemd:

pm2 start app.cjs --name topads
pm2 save
pm2 startup

Front the app with Nginx or Caddy for TLS termination and static asset caching.

cPanel (Node.js Selector / Passenger)

1. Upload the built project to your home directory.
2. In Setup Node.js App set Application startup file to app.cjs.
3. Set Node version to 22 LTS (required for WebSockets).
4. Run npm install from the panel, then Restart App.

Docker

docker build -t topads .
docker run -p 8080:8080 --env-file .env topads

Common Deployment Issues

Project Structure

topads/
├── src/
│   ├── routes/                 # File-based routing (TanStack)
│   │   ├── __root.tsx          # Root layout + providers
│   │   ├── index.tsx           # Marketing landing
│   │   ├── auth.tsx            # Sign-in / sign-up
│   │   ├── setup.tsx           # 6-step onboarding wizard
│   │   ├── install.tsx         # License / bootstrap
│   │   ├── _authenticated/     # Protected app subtree
│   │   └── api/public/*        # Webhooks & external HTTP
│   ├── components/             # UI components (shadcn + custom)
│   ├── lib/                    # Business logic + server fns
│   │   ├── setup/              # Setup wizard server fns
│   │   ├── demo/               # Demo-mode utilities & guards
│   │   ├── admin/              # Platform settings
│   │   ├── messaging/          # Provider abstraction
│   │   └── pwa/                # Service worker registrar
│   ├── integrations/supabase/  # Auto-generated Supabase clients
│   ├── hooks/                  # Reusable React hooks
│   └── styles.css              # Tailwind v4 + tokens
├── public/                     # Static assets, sw.js, manifest
├── docs/                       # This documentation portal
├── supabase/migrations/        # SQL migrations
├── app.cjs                     # cPanel/Passenger entrypoint
└── vite.config.ts              # Vite + TanStack config

Core Modules

• Auth — Supabase Auth + _authenticated layout gate, roles in user_roles.
• Messaging — Provider abstraction (src/lib/messaging/) with async outbox and webhook processing.
• CRM — Contacts, companies, deals, pipelines, activities.
• Workflow — Visual builder on React Flow with typed nodes.
• Billing — Stripe subscriptions, invoices, plans.
• PWA — Custom SW, dynamic manifest driven by admin settings.

API Structure

Two boundaries — pick by caller:

• createServerFn — typed RPC for internal client calls (loaders, components).
• Server routes (src/routes/api/) — raw HTTP for webhooks, cron, public APIs. External callers use /api/public/*.

Auth System

1. Supabase Auth issues the session (email/password + Google OAuth).
2. Client attaches bearer via functionMiddleware in src/start.ts.
3. Protected server fns use .middleware([requireSupabaseAuth]).
4. Roles resolved via has_role(user_id, role) — never trust client-supplied role claims.

Configuration Guide

.env Variables

App Settings

Global runtime settings live in the settings table under the platform scope and are edited from Super Admin → Settings. Keys include branding, localization, smtp, notifications, billing, pwa, and setup_complete.

Email (SMTP) Configuration

{
  "host": "smtp.yourprovider.com",
  "port": 587,
  "username": "no-reply@yourdomain.com",
  "from_address": "no-reply@yourdomain.com",
  "from_name": "TopAds",
  "encryption": "tls"
}

Database Configuration

Managed by Supabase. Connection strings are provided by the Supabase dashboard. All schema changes flow through supabase/migrations/.

PWA Configuration

The manifest is generated dynamically at /manifest.webmanifest from admin-controlled settings. Fields available in Super Admin → PWA:

• App name & short name
• Theme color & background color
• Display mode (standalone, minimal-ui, fullscreen)
• Icon set (192, 256, 384, 512 px + maskable)
• Splash branding

PWA Icons Setup (Admin-Controlled)

1. Open Super Admin → PWA.
2. Upload a 512×512 master icon — variants are generated automatically.
3. Save. The service worker will emit a "New version available" toast on next load; users tap Reload to activate.

Features Documentation

User System

Users authenticate through Supabase Auth. Profiles live in public.profiles and are auto-created via a trigger on signup. Password resets follow the standard /reset-password flow with a PASSWORD_RECOVERY event guard.

Role-Based Access (RBAC)

Roles are enum-typed and stored in public.user_roles. Never store roles on profiles.

Dashboard System

Role-aware landing pages under /_authenticated/. Widgets consume live queries from CRM, Inbox, Billing, and BI.

Navigation System

Responsive by breakpoint — full sidebar above 1200 px, forced 60 px mini rail between 768–1200 px, slide-in drawer below 768 px. Managed by LayoutProvider.

PWA System

Installable across mobile, tablet, and desktop with a NetworkFirst navigation strategy and CacheFirst asset strategy. Falls back to /offline when disconnected.

Setup Wizard System

See Setup Wizard.

Demo System

See Demo Mode.

Notification System

In-app toasts (Sonner), realtime notifications table with per-user preferences, and optional web push via the service worker.

Demo / Test Mode (.env Controlled)

Demo mode is a single environment switch controlling both UI visibility and server-side CRUD enforcement.

Enable

APP_MODE=demo
VITE_APP_MODE=demo

Behavior Matrix

Demo Accounts

Accounts are auto-provisioned on first login via the provisionDemoAccounts server function.

Server-Side Guard

All destructive server fns include demoWriteGuard middleware. Blocked calls return HTTP 423 with a user-safe DemoModeBlockedError and are logged as structured JSON ([demo.blocked]).

Setup Wizard

The Setup Wizard runs after installation and is gated on two conditions: no super admin exists and platform.setup_complete is not set. Once completed, the route locks permanently.

Flow

1. Environment Validation — probes DB, storage, auth, environment. Blocks on any critical fail.
2. Super Admin Creation — name, email, password + confirm, live strength meter (score ≥ 3).
3. App Identity & Branding — name, tagline, primary color, logo URL, favicon URL.
4. System Configuration — timezone, currency, date format, language, SMTP, notifications.
5. SaaS Settings — SaaS mode toggle, subscription system, multi-tenant, default plan.
6. Launch — summary + "Launch Application" → writes setup_complete and redirects to /dashboard.

Security Behavior

• /setup is protected by beforeLoad — redirects to /auth if any super admin exists or setup is complete.
• Every wizard server fn re-checks setup-open status; stale tabs cannot reopen setup.
• completeSetup refuses if no super admin exists yet.
• /install is likewise redirected once setup is finalized.

Resetting Setup (Recovery Only)

DELETE FROM public.settings
WHERE scope = 'platform' AND key = 'setup_complete';

Changelog

Version 4.2.2 Current

• The product is now TopAds end to end — app UI, documentation portal, changelog, deployment manifests, SDK/CLI package names, and stored marketplace copy — with browser storage keys migrated automatically so active organization, workspace, and preferences survive the rename.
• Fixed outbound messages stalling in “queued”: composite WhatsApp thread keys now resolve to the correct recipient, with automatic retry for messages stuck longer than 20 seconds.
• Unsupported WhatsApp media types (WebP images, WebM audio) are delivered as documents instead of failing with a media upload error; voice notes record as OGG/Opus.
• Attachments and downloads work across the app — outbound media creates attachment records visible in the conversation, media lightbox, and CRM profile, with blob-based downloads plus an explicit error state and retry.
• Inbox sync status consolidated into a single info popover showing last sync time, duration, item counts, and recent runs.
• Sidebar menus behave as an accordion: one section open at a time, state persisted across navigation, with smooth collapse and expand animations.
• Automated security scanning in CI, plus audited agent, user, and RLS coverage across the platform.

Version 4.0.0

• Subscription plans are now fully linked to payment gateways: per-plan price/product mapping, workspace-level overrides, environment-aware resolution, and an admin "verify mappings" action that syncs live from the gateway API.
• Billing webhooks normalize Stripe and Paddle events into a single router that keeps subscription status, renewals, and cancellations in sync automatically, with signature verification and a replay tool for failed deliveries.
• Full upgrade/downgrade flow — plan change wizard, checkout hand-off, entitlement refresh on return, and a billing settings page with invoices and subscription history.
• Redesigned marketing site: new landing page, live pricing driven by real plans, monthly/yearly toggle, plan comparison table, current-plan badges, and smooth in-page scrolling.
• WhatsApp templates enforce strictly numbered placeholders ({{1}}, {{2}}); named variables are auto-converted on import with a field-by-field preview, plus URL button query/fragment parameter mapping.
• Version 4.0.0 consolidates the 3.9.x billing and platform work into the first fully self-serve release: sign up, pick a plan, pay, and get entitlements without admin involvement.

Version 3.9.0

• Super Admin consoles for AI providers and payment gateways, including credential storage with column-level protection, connection tests, and a gateway health widget.
• Platform audit logging for every gateway and plan-linkage change, plus a webhook delivery health panel with per-event status.
• Plan → gateway price mapping (plan_gateway_prices) with workspace-level overrides, environment-aware resolution, and server-side conflict detection for duplicate mappings.
• Localization rebuilt for 100+ languages with full RTL support and generated locale data.
• Platform Settings: General, Branding, Maintenance mode, and feature flags now apply globally at runtime.
• Drag-and-drop uploads for logo, favicon, and PWA icons backed by a private branding bucket with a streaming public endpoint.
• Accessible accent-colour engine — contrast is measured and adjusted instead of blocking the save.

Version 3.8.9

• WhatsApp templates can be picked, previewed, and sent directly from the Inbox, with markdown-accurate bubble previews and manual Meta sync.
• Template parameter editor with auto-suggested values from the contact/CRM record, reusable saved presets, and strict inline validation that blocks invalid sends.
• Friendly Meta delivery error mapping (including #131030 recipient-not-allowed) with retry suppression for unrecoverable failures.
• Meta App settings screen for App ID/Secret with live connection verification, plus a Facebook Pages manager showing Messenger capability status and safe disconnect/reconnect.
• Multi-bot Telegram support — several bots per workspace, each as an independent Inbox account with its own webhook and outbound token.
• Unified Inbox fixes: correct contact/conversation mapping for Telegram ingest, webhook idempotency, and a double-increment unread-count bug removed (DB trigger now owns unread state).
• Realtime outbound updates and monotonic delivery-status guard so "read" can never regress to "sent" on out-of-order receipts.
• Live Chat widget: unified realtime status line, Supabase broadcast updates, required pre-chat fields, and fixed agent handoff/assignment.
• Security: tightened RLS across API keys, OAuth clients, webhooks, meeting credentials, and WhatsApp catalog; template RBAC with full audit logging; extensions moved out of public; CI blocks merges on new scan findings.
• UI consistency: standardized h-8 w-8 icon buttons app-wide and default accent locked to #D81C20.

Version 3.8.8

• App-wide realtime with burst deduplication, coalesced query invalidation, and exponential-backoff reconnection.
• Inbox sync settings with background refetch, and a media lightbox for images, video, and documents.
• CRM contact identity and cache keys unified so profile edits propagate everywhere instantly.
• E.164 phone validation for WhatsApp template sends and template version history.

Version 3.8.7

• Conversation transcript export and cross-platform typing indicators.
• Agent notifications for assignment, handoff, and SLA breaches.
• Flow Builder workspace security — loader-level access guards with live revocation and no data reads on denied opens.
• TypeScript build performance work; typecheck time reduced from timeout to roughly 35 s.

Version 3.8.6

• Email and SMS channel accounts added to the omnichannel model.
• Thread deduplication and hardened conversation merging to stop duplicate chats.
• Live Chat widget requires contact details before starting, with fixed media rendering.
• RLS corrections for contact re-match jobs, inbox agent assignment, and mobile AI endpoints.
• Security CI gate blocking merges on new scan findings; database extensions moved to an extensions schema.

Version 3.4.6

• Production-ready Setup Wizard (6 steps) with server-side lock and route guards.
• Centralized Environment Mode System (Demo vs Production) with demoWriteGuard.
• Enterprise PWA with dynamic manifest, custom service worker, and admin-controlled icons.
• Responsive navigation — full sidebar > 1200 px, mini rail 768–1200 px, drawer < 768 px.
• Security hardening — XSS remediation, CSP headers, HIBP password check, RLS enforcement.
• Auth listener filtered — no more hourly router thrashing on TOKEN_REFRESHED.
• Overhauled documentation portal with sidebar nav, search, and syntax highlighting.

Version 3.4.0

• WhatsApp Cloud API provider abstraction, webhook processing, and template sync.
• AI Chatbot Builder, Live Chat Widget, and Helpdesk module.
• Stripe billing, SaaS plan management, and revenue snapshots.

Version 3.3.3

• Project Documentation System v1.
• Node.js 22 deployment support for cPanel/LiteSpeed.
• Swapped xlsx for SheetJS CDN (CVE mitigation).

Troubleshooting

Server Issues

Auth Issues

• "Unauthorized: No authorization header" — bearer middleware missing; ensure attachSupabaseAuth is registered in src/start.ts.
• Google sign-in "Unsupported provider" — enable Google in Supabase Auth settings.
• Password reset auto-logs in — check /reset-password is present and gated on PASSWORD_RECOVERY.

Build Issues

• Route tree mismatch — verify every createFileRoute("...") matches its filename.
• Blank page after deploy — check Vite base is / and hashed assets resolve at domain root.
• Migration rejected — public tables must include GRANT statements alongside CREATE TABLE.

PWA Issues

• Install prompt not showing — service worker requires HTTPS and a valid manifest with 192 & 512 px icons.
• Stale content after deploy — SW emits "New version available" toast; users tap Reload to activate.

FAQ

Setup

Can I re-run the setup wizard? Only by deleting platform.setup_complete from the settings table. Intended for recovery only.

Can I skip a wizard step? No. Each step server-validates before Next is enabled.

Deployment

Does TopAds work on shared hosting? Yes on cPanel with Node.js Selector (Node 22 LTS) + Passenger. See Build & Deployment.

Docker support? Yes — a Dockerfile is included; multi-stage build produces a slim runtime image.

Roles

How do I promote a user to Super Admin? Insert a row into user_roles with role super_admin. Never store roles on the profile.

Can I add custom roles? Yes — extend the app_role enum via a migration and update has_role policies.

PWA

Where do I upload the app icon? Super Admin → PWA. Variants are generated automatically.

Does the PWA work offline? Yes for cached routes and assets; live data requires connectivity and falls back to /offline.

Demo Mode

How do I disable demo mode for production? Set APP_MODE=production and VITE_APP_MODE=production in .env, rebuild, restart.

Can demo users delete records? No — demoWriteGuard blocks destructive server fns with HTTP 423.

Marketing & Product Analytics

TopAds ships a vendor-agnostic analytics layer. Superadmins pick the provider in Super Admin → Platform Settings → Analytics; application code never references a vendor SDK directly.

Providers

Only public, browser-visible identifiers are stored. Nothing here is a secret.

Options: Track page views, Require cookie consent (default on — the vendor script only loads after the visitor accepts the analytics cookie category), and Debug to console.

Architecture

• src/lib/analytics/config.ts — provider list, config shape, defaults, host resolution.
• src/lib/analytics/client.ts — runtime: loads the vendor script once, buffers events fired before load, dispatches per provider. Never throws.
• src/lib/analytics/events.ts — marketing event vocabulary plus ctaAttrs().
• src/lib/analytics/ui-events.ts — typed in-app product events (same pipeline).
• src/components/analytics/analytics-provider.tsx — mounted once in __root.tsx; boots the provider, sends page views on route change, and captures clicks on any element tagged with data-analytics-id.

Configuration is delivered through the public platform runtime config (settings row scope='platform', key='analytics'), validated server-side by AnalyticsSchema in src/lib/admin/platform-settings-validation.ts.

Event vocabulary

Instrumenting new surfaces

Declarative (preferred for links and buttons):

import { ctaAttrs } from "@/lib/analytics/events";

      <Link to="/auth" {...ctaAttrs("start-free-trial", "hero")}>Start free trial</Link>
      

Imperative, when you need computed props:

import { trackMarketing, trackPricingClick } from "@/lib/analytics/events";

      trackPricingClick(plan.code, "pricing", { interval: plan.interval });
      trackMarketing("cta_click", { cta_id: "billing-interval", location: "pricing", label: "year" });
      

Privacy

• No PII is sent: names, emails and phone numbers are never included in event props — only company size and the chosen contact method.
• With Require cookie consent on, nothing loads and nothing is sent until the visitor accepts analytics cookies; revoking consent stops dispatch on the next page load.
• Events are dropped silently when no provider is configured.

TopAds Color System v1.0.0

Enterprise-grade multi-shade token system. Every color the user sees comes from a token — no hex in components, no text-white, no palette gymnastics.

Two layers:

• Fixed shade ladders (theme-independent): bg-primary-500, text-accent-700, border-success-200. Same value under light and dark, like Tailwind's default palette.
• Semantic tokens (theme-aware): bg-primary, bg-background, text-muted-foreground. Flip automatically with .dark.

Prefer semantic tokens by default. Reach for fixed shades only when a specific chip, chart color, or gradient stop demands it.

Palettes

Each family exposes 11 shades: 50 · 100 · 200 · 300 · 400 · 500 · 600 · 700 · 800 · 900 · 950.

Utility classes generated: bg-{family}-{shade}, text-{family}-{shade}, border-{family}-{shade}, ring-{family}-{shade}, from-{family}-{shade} …

Semantic Token Map

Every slot the design system references maps to a concrete token. Change the token, not the callsite.

Backgrounds & Surfaces

Sidebar (dark rail in both themes)

Borders & Focus

Interaction States (theme-aware overlays)

Use them via arbitrary values sparingly, e.g. hover:bg-[color:var(--hover-overlay)], or wire into component variants.

Status

Muted variants for subtle backgrounds: bg-success-muted, bg-danger-muted, etc.

Badges (subtle chip variants)

Pair background + foreground — always use both, never mix and match.

<span className="bg-badge-success text-badge-success-foreground">Active</span>
      <span className="bg-badge-warning text-badge-warning-foreground">Pending</span>
      <span className="bg-badge-danger  text-badge-danger-foreground">Failed</span>
      

Variants: neutral · primary · accent · success · warning · danger · info.

Presence Dots

bg-status-online · bg-status-away · bg-status-busy · bg-status-offline

Avatars

Hash a stable user id to 0–7 and pick the pair:

const idx = (hashCode(user.id) % 8) + 1;
      <span className={`bg-avatar-${idx} text-avatar-${idx}-foreground`}>{initials}</span>
      

Eight hand-tuned hues (teal, violet, rose, amber, emerald, sky, coral, indigo) with pre-verified foreground contrast.

Charts

Eight fixed chart hues, ordered for perceptual distinction: bg-chart-1 … bg-chart-8. First slot is the brand accent so single-series charts stay on-brand.

Dark Theme

The .dark class on <html> flips only the SEMANTIC tokens (background, foreground, surface, primary, accent, muted, border, badge pairs, interaction overlays). The 11-step shade ladders stay identical, so bg-primary-500 renders the same steel in both themes — this is what makes chart palettes, gradient stops, and reference designs stable across themes.

Contrast is verified per token pair for WCAG AA (4.5:1 body, 3:1 large + non-text UI).

Light Theme

Default (:root). Cool near-white background, deep steel foreground, teal accent. Sidebar remains dark for a Linear-like split.

Rules of Use

1. Never hardcode a hex, rgb(…), oklch(…), text-white, or bg-black inside a component. Ever.
2. Prefer semantic. bg-card, text-foreground, border-border before bg-neutral-50.
3. Pairs are pairs. Always render bg-primary with text-primary-foreground; bg-badge-success with text-badge-success-foreground. Foregrounds are pre-contrasted.
4. Muted is a token, not opacity. Never fake muted text with text-foreground/60 — use text-muted-foreground.
5. State overlays (hover/active) tint on top of the surface — they never replace the semantic background.
6. Charts and avatars hash to fixed shades so the same entity keeps its color across sessions.
7. Adding a color = add the token in src/styles.css (both :root and .dark), map it under @theme inline, document it here. Never add it to a component.

The full list of raw tokens lives in src/styles.css. The TypeScript surface for JS-driven visuals (charts, SVGs) lives in src/shared/config/design-tokens.ts.

TopAds v1.0.0 — Component Library

Enterprise, reusable, theme-aware UI components. Every component supports light + dark themes automatically via design tokens (src/styles.css) — never hardcode colors, fonts, or sizes in a component.

Two layers:

• Primitives — shadcn/ui components under src/components/ui/*. Radix- backed, accessible, un-styled at semantics level. Do not modify these arbitrarily; extend via variants or shared wrappers.
• Shared — enterprise wrappers under src/shared/components/*. Composed from primitives with product-specific behavior (loading state, empty state, data table, timeline, search box, etc.).

Import from a single path across features:

import {
        ActionButton, SearchBox, Autocomplete, DatePicker, DateRangePicker,
        Timeline, Spinner, LoadingState,
        EmptyState, ErrorState, SuccessState,
        StatCard, StatusBadge, DataTable, FormField, ConfirmDialog, SideDrawer,
        Skeleton, notify,
      } from "@/shared/components";
      

Inventory

Rules of use

1. Theming is automatic. Every component reads semantic tokens (bg-*, text-*, border-*, ring-*). Never pass text-white, bg-black, or a hex — always a token or a variant.
2. Accessibility first. All overlays trap focus, all interactive controls have visible focus rings (ring-ring), all loading states include a role="status" announcement, all icon-only buttons include aria-label.
3. Composition over configuration. Prefer composing Card + PageHeader + DataTable over adding new props to a generic wrapper.
4. Loading states: use Skeleton for content-shaped placeholders, Spinner for inline waits, LoadingState for whole-pane loads, ActionButton loading for button-triggered async.
5. Feedback hierarchy:
   • Transient success/failure → notify (toast).
   • Blocking success → SuccessState (full pane).
   • Blocking error → ErrorState (full pane) or Alert (inline).
   • Empty query → EmptyState.
6. Forms use FormField (react-hook-form) — never bare <Input> in a form. FormField handles label / description / error / aria-describedby.
7. Data density: table rows use card-p-xs, feature cards use card-p-lg, marketing cards card-p-xl. Set on the wrapper, not on individual children.
8. Icons: 16 px (h-4 w-4) inside controls; 20 px (h-5 w-5) in headers; 24 px (h-6 w-6) in empty states. Use lucide-react only.

Related docs

• docs/architecture/DESIGN_SYSTEM.md — the design language.
• docs/architecture/COLOR_SYSTEM.md — semantic color tokens.
• docs/architecture/TYPOGRAPHY_SYSTEM.md — type scale + utilities.
• docs/architecture/LAYOUT_SYSTEM.md — layouts + spacing.

Dashboard Widgets

Location: src/shared/widgets/ — single barrel export @/shared/widgets.

Every widget:

• Uses only semantic tokens (--color-surface, --color-accent, --color-chart-N, …). No hardcoded hex.
• Inherits light/dark theme via CSS variables.
• Composes on top of the WidgetCard shell — border, header, hover elevation, footer slot.
• Provides a loading skeleton where a numeric value is the focus.
• Ships with TypeScript types for every prop and payload.

Catalog

Rules of use

1. Single import path. Never deep-import a widget file — always @/shared/widgets.
2. Compose, don't fork. New surfaces wrap WidgetCard; extend the barrel with new widgets only when the shape can't be expressed by existing props.
3. Grids belong to the page. Widgets do not manage their own outer grid — use layouts/primitives (grid-metrics, grid-bento, grid-cards) at the page level.
4. Loading states. Prefer widget-native loading where offered; otherwise wrap in SkeletonCard from @/shared/components.
5. Charts. Colors come from --color-chart-1..8. Never pass literal hex values.
6. Motion. Interactive widgets use duration-normal ease-emphasized and honor prefers-reduced-motion (handled globally in styles).

TopAds Design System v1.0.0

The visual and interaction language for every TopAds surface. Every page — marketing, product, admin, docs — obeys this document. Deviations require an ADR.

North star: the calm precision of Linear, the informational density of Stripe, the composure of Notion, the warmth of Intercom, the discipline of Vercel, the utility of GitHub. Never the generic SaaS look — no purple gradients on white, no stock Inter+Poppins, no interchangeable hero.

1. Design Principles

1. Content first, chrome second. UI recedes; data leads. If a control isn't earning its pixels, delete it.
2. Confident restraint. One accent color, one display voice, one motion curve. Repetition builds identity.
3. Density with air. High information density is fine — but every dense region must be bordered by generous negative space so the eye can rest.
4. Deterministic layout. Grids, gutters, and rhythm are fixed. Nothing floats freely.
5. Motion has meaning. Animation clarifies causality (this came from here) or state (this is loading). Never decorative.
6. Keyboard is a first-class citizen. Every interactive path must be reachable and completable without a pointer.
7. Dark mode is not a filter. Colors, elevation, and contrast are designed twice — once for each theme.
8. Enterprise feel comes from consistency, not ornament. No gratuitous gradients, glassmorphism, or emojis in product chrome.

2. Color Philosophy

Tokens live in src/styles.css under @theme; access them via semantic classes (bg-background, text-foreground, bg-primary) — never raw palette classes or hex.

Palette structure:

• Neutral spine (steel): the app is 85% neutral. A cool near-black paired with a paper-warm white. Neutrals carry structure — borders, dividers, backgrounds, body text.
• Single accent (teal): used sparingly for primary actions, active state, focus rings, and links. Never for decoration.
• Semantic status: success (emerald), warning (amber), danger (rose), info (sky) — muted, not saturated. Reserved for state, never brand.
• Chart palette: 8 hand-picked hues that harmonize with the accent — used only in data viz.

Contrast rules:

• Body text ≥ 4.5:1 against its surface (WCAG AA).
• Large text and non-text UI ≥ 3:1.
• Muted text (text-muted-foreground) is the floor for readable prose — never lighter.
• Every interactive state (hover, active, focus, disabled) has an explicit token; nothing is faked with opacity.

Elevation via color, not shadow. Cards and popovers step up the neutral scale (bg-card, bg-popover) rather than casting heavy shadows. Shadows are subtle and short-throw.

Never:

• Hardcoded hex or text-white / bg-black in components.
• Rainbow-of-accents. One accent, always.
• Purple-indigo gradient on white — banned by convention.

3. Typography Rules

• Display / headings: a distinctive geometric sans with real personality (defined by --font-display). Set tight (tracking-tight), heavy (600–700), and generous in size. Reserved for h1–h3 and hero copy.
• Body / UI: a refined humanist sans (--font-sans) tuned for on-screen reading at 14–16 px. Weight 400 body, 500 UI labels.
• Mono: for code, IDs, and tabular numbers (--font-mono). Always font-variant-numeric: tabular-nums for numeric columns.

Scale (12 steps, 2xs → 7xl): modular, not linear. Use tokens, never arbitrary sizes.

Rules:

• One h1 per page.
• Never skip heading levels.
• Line-height: 1.15 for display, 1.5 for body, 1.4 for UI labels.
• Max line length ≈ 70ch for prose.
• Numbers in tables, metrics, and money are tabular-nums, always.
• Never use ALL-CAPS as body copy. Reserved for micro-labels ≤ 12 px with wide tracking.
• Never lower opacity to imply hierarchy — use a lighter weight or a muted token.

4. Component Rules

Every component obeys:

1. Composed from tokens. No hardcoded colors, spacing, or radii. Only design-token classes.
2. State variants are exhaustive. Default, hover, active, focus-visible, disabled, loading, error, empty, success — each has a visual answer.
3. Focus is visible. focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2. No outline: none without a replacement.
4. Semantic HTML wins. A button is a <button>. A link is an <a>. Never <div onClick>.
5. Icon-only controls carry aria-label. Non-negotiable.
6. Loading has a shape. Every async surface has a skeleton that mirrors its final layout — never a generic spinner in place of content.
7. Empty states are opinionated. Icon + one-line title + one-line description + one primary action. No "no data" strings.
8. Errors are recoverable. Message + cause + action. Never a raw stack trace to the user.
9. Composition over configuration. Prefer children/slots to prop explosions (> 7 props is a smell).
10. Every reusable primitive ships: types, TSDoc, tests, and a design-tokens-only implementation.

Primary primitives (already in src/components/ui/ + src/shared/components/): Button, Input, Textarea, Select, Combobox, Checkbox, Radio, Switch, Slider, Badge, Avatar, Tooltip, Popover, Dialog, AlertDialog (ConfirmDialog), Sheet (SideDrawer), DropdownMenu, ContextMenu, Command (Palette), Tabs, Accordion, Table, DataTable, Skeleton, EmptyState, ErrorState, SuccessState, Toast, Breadcrumbs, Pagination, Progress, Separator, Card.

5. Accessibility Standards

WCAG 2.2 AA is the floor, not the ceiling.

• Color contrast meets AA for text and non-text UI. Verified per token in both themes.
• Keyboard: every path reachable by Tab; focus order matches visual order; no keyboard traps outside modal dialogs.
• Focus rings: always visible, always token-driven, offset from the element edge.
• ARIA: used only where semantics fall short. Never role="button" on a <button>.
• Screen readers: landmarks (<main>, <nav>, <header>, <footer>) on every page. One <main> per route, rendered in the layout that owns <Outlet />.
• Motion: every animation respects prefers-reduced-motion (already global in styles.css).
• Forms: every input has a visible label OR an aria-label. Errors are announced via aria-live="polite".
• Icon-only buttons: aria-label required.
• Tap targets: ≥ 44×44 px on touch; icon buttons bumped to min-h-11 min-w-11 when used as primary actions.
• Skip link to #main on every route.

6. Responsive Rules

Mobile-first. Base styles target ≥ 360 px; progressive enhancement at sm (640) / md (768) / lg (1024) / xl (1280) / 2xl (1536).

Breakpoint intent:

• < sm — single column, edge-to-edge, thumb-reachable primary action.
• sm – md — comfortable single column with side padding.
• md – lg — two-column layouts unlock; mobile nav drawer replaced by top bar.
• lg+ — sidebar + content + optional right rail; workspace switcher visible.

Layout invariants:

• Header rows with fixed + fluid content: grid grid-cols-[minmax(0,1fr)_auto] on mobile, promoted to flex at sm:. Text containers get min-w-0; icons/avatars get shrink-0; single-line headings get truncate.
• Full-height layouts use h-dvh, never h-screen.
• Tables collapse to card lists below md — never horizontal-scroll a table on mobile as the default.
• Modals become bottom sheets below sm.
• Touch targets ≥ 44 px on any surface reachable by touch.
• Images: explicit width / height (no CLS); modern formats first (AVIF → WebP → JPEG).

7. Animation Rules

One curve, one duration philosophy, one purpose: clarify state.

Durations (tokens):

• --duration-fast: 120ms — feedback (hover, press, toggle).
• --duration-base: 200ms — enter/exit for popovers, tooltips, menus.
• --duration-slow: 320ms — page transitions, drawer slides, dialog entrance.
• Never exceed 400 ms in product chrome.

Easings (tokens):

• --ease-out (default): decelerating — objects arrive gently.
• --ease-in-out: reserved for looped or reversible motion.
• Never use linear for UI motion (only for continuous loaders/progress).

Rules:

• Motion clarifies causality: an item enters from where it was invoked (menu drops from its trigger, drawer slides from its edge).
• Only one hero animation per page. Scattered micro-animations feel cheap.
• Skeletons shimmer at low contrast; never pulse aggressively.
• hover-scale maxes at 1.03; larger scaling feels toy-like on enterprise UI.
• Respect prefers-reduced-motion: replace transforms with opacity fades, disable auto-play.
• Never animate layout-critical properties (width, height, top) — animate transform and opacity.

8. Layout Rules

Grid: 12-column, 1440 px max content width, 24 px gutter on desktop, 16 px on mobile.

Application shell:

• Left sidebar 264 px (--sidebar-width), collapsible to 56 px icon rail.
• Top bar 56 px, sticky, translucent surface (bg-background/80 backdrop-blur).
• Content max-width 1200 px, centered when narrower than viewport.
• Optional right rail 320 px for context (activity, details, inspector).
• Footer only on marketing routes; never inside authenticated shell.

Spacing rhythm: 4 px base unit. Only these steps: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96. Any other value is a bug.

Radius rhythm: sm 6 · md 8 · lg 12 · xl 16 · 2xl 24. Inputs and buttons md; cards lg; modals xl. Never 9999px except on avatars and pill badges.

Section rhythm on marketing pages: vertical padding of 96 px desktop / 64 px tablet / 48 px mobile between top-level sections. Consistent, ruler-measurable rhythm — never eyeballed.

Elevation: four levels only.

• elev-0 — flat, on background.
• elev-1 — cards, table rows on hover.
• elev-2 — popovers, dropdowns.
• elev-3 — dialogs, drawers. Each level maps to a specific --shadow-* token and a specific surface color step. Never mix.

Composition patterns:

• Metric row — 3–4 KPI cards, equal width, tabular-nums numbers, one-line label above.
• Data view — filter bar → table/board → pagination. Filter bar sticks to top of scroll region.
• Detail view — title + status pill + actions → tabbed body (Overview / Activity / Settings) → right rail for meta.
• Empty first surface — every module ships with a hand-crafted empty state, never an unstyled blank.

Enforcement

• Design tokens live in one place (src/styles.css + src/shared/config/design-tokens.ts). ESLint rule bans hex literals and disallowed Tailwind classes (text-white, bg-black, palette classes, arbitrary spacing).
• Storybook is the visual contract; every primitive has an entry with all state variants.
• Axe + Playwright a11y checks run in CI on the top 10 routes.
• Any new component starts from a primitive and its variants — never a one-off from scratch.

The system is not a suggestion. It's the reason every TopAds page looks like it belongs to the same product.

Development Standards

Enterprise-grade coding standards for this codebase. These rules are enforced during code review and CI. When in doubt, optimize for readability, type-safety, and long-term maintainability over cleverness.

1. TypeScript Best Practices

• strict: true is non-negotiable. Never disable strictNullChecks, noImplicitAny, or strictFunctionTypes.
• Prefer type for unions / primitives / function signatures; interface for extensible object contracts (public component/service APIs).
• Never use any. Use unknown at boundaries and narrow via type guards or Zod. // @ts-ignore and // @ts-expect-error require a comment explaining why and a ticket link.
• No non-null assertions (!) except immediately after a proven runtime check.
• Use branded types for IDs: type UserId = string & { readonly __brand: 'UserId' } to prevent cross-ID mixups.
• Discriminated unions over boolean flags: { status: 'loading' } | { status: 'success'; data: T } | { status: 'error'; error: Error }.
• All external I/O (HTTP responses, server-fn inputs, localStorage, URL params) must be validated with Zod before entering the type system.
• Prefer readonly on arrays, tuples, and props by default. Mutate only when the mutation is the point.
• Explicit return types on every exported function. Inference is fine for internal helpers.
• No enums. Use as const object literals + type Foo = typeof Foo[keyof typeof Foo].
• Path aliases only: @/features/..., never ../../../features/....

2. React Best Practices

• Function components only. No class components.
• Server-first data fetching via TanStack Router loaders + ensureQueryData. Never useEffect + fetch for initial render.
• Components must be pure during render. Side effects live in useEffect, event handlers, or server functions.
• Keep components under ~200 LOC. Split when a component juggles unrelated concerns.
• Composition over props explosion. More than ~7 props is a smell — use children, slots, or context.
• Memoize deliberately: useMemo/useCallback only when profiler shows a win or when the value is a stable dependency for a downstream hook. Do not blanket-memoize.
• Stable keys in lists — never array index for reorderable data.
• No prop drilling past 2 levels — lift to context, route loader, or a query.
• Every interactive element must be keyboard-reachable and have a visible focus ring (focus-visible:ring).
• Error boundaries at every route; suspense boundaries around every async read.
• Never mutate props or state directly. Treat all state as immutable.

3. Tailwind Best Practices

• Design tokens only (see src/styles.css + src/shared/config/design-tokens.ts). No hardcoded colors (text-white, bg-[#123]), no ad-hoc arbitrary values for spacing/typography.
• Semantic classes (bg-background, text-foreground, border-border) over raw palette classes (bg-slate-900). This keeps light/dark mode consistent.
• Order utilities: layout → box model → typography → color → state → motion. Use Prettier's prettier-plugin-tailwindcss for auto-sort.
• Extract to a component when the same utility string repeats 3+ times. Do not extract to @apply prematurely.
• Never @import a remote URL in styles.css (Lightning CSS resolves from filesystem). Load fonts via <link> in __root.tsx.
• Responsive design is mobile-first: base styles = mobile, then sm: / md: / lg: progressively enhance.
• Dark mode uses the class strategy — every color must be theme-aware.

4. Naming Conventions

Files & Folders

• Folders: kebab-case (user-settings/, feature-flags/).
• React components: kebab-case.tsx (app-sidebar.tsx) — the export is PascalCase.
• Hooks: use-*.ts (use-current-user.ts).
• Utilities: kebab-case.ts (format-currency.ts).
• Types: co-locate in types.ts next to the module; shared types in src/shared/types/.
• Tests: *.test.ts / *.test.tsx co-located next to the source.
• Server functions: *.functions.ts (client-safe imports); server-only helpers *.server.ts.

Code

• Components / Types / Interfaces / Enums: PascalCase.
• Variables / functions / hooks: camelCase.
• Constants: SCREAMING_SNAKE_CASE for module-level primitives; PascalCase for as const object maps.
• Booleans: prefix with is / has / can / should (isLoading, hasPermission).
• Event handlers: handle* for definition, on* for props (onSubmit={handleSubmit}).
• Hooks: always start with use; return either a tuple [value, setValue] or an object with named fields — never mix.
• Generic type params: T, TValue, TError — descriptive when more than one.

Database

• Tables: snake_case, plural (user_profiles, workspace_members).
• Columns: snake_case (created_at, owner_id).
• Primary keys: id uuid (gen_random_uuid()).
• Foreign keys: <table_singular>_id (workspace_id, user_id).
• Timestamps: created_at, updated_at, deleted_at (soft delete).
• Booleans: is_* / has_* (is_archived).
• Enums: snake_case type name, snake_case values (app_role, subscription_status).
• Indexes: idx_<table>_<columns>.
• RLS policies: descriptive sentence-case name ("Users can read own profile").

API

• REST routes: plural nouns, kebab-case (/api/public/workspace-members).
• Server functions: verb-first (getUser, createWorkspace, archiveDeal).
• Query keys (TanStack Query): hierarchical array (['workspaces', workspaceId, 'members']).
• Zod schemas: <Name>Schema + inferred type <Name> (export type User = z.infer<typeof UserSchema>).

5. Commit Standards

Conventional Commits — enforced by CI:

<type>(<scope>): <subject>

      <body>

      <footer>
      

• Types: feat, fix, refactor, perf, docs, test, chore, build, ci, style, revert.
• Scope: feature or module (auth, billing, crm).
• Subject: imperative, lower-case, no trailing period, ≤ 72 chars.
• Breaking changes: feat(auth)!: … + BREAKING CHANGE: footer.
• One logical change per commit. No wip, no fix stuff.
• Reference issues in the footer: Refs: LOV-1234.

6. Linting & Formatting

• ESLint with @typescript-eslint/recommended-type-checked, react-hooks/recommended, jsx-a11y/recommended.
• Errors (block CI): unused vars, any, missing hook deps, unresolved imports, floating promises, console.log in production paths.
• Warnings (allowed but tracked): complexity > 15, function length > 80 LOC, file length > 400 LOC.
• Prettier is the single source of formatting truth. No manual formatting debates.
  • printWidth: 100, singleQuote: true, semi: true, trailingComma: 'all', arrowParens: 'always'.
  • Plugins: prettier-plugin-tailwindcss (class sorting).
• .editorconfig ensures LF line endings and 2-space indent across editors.
• Pre-commit: lint-staged runs ESLint + Prettier on staged files. Push is blocked on failure.

7. Documentation Rules

• TSDoc on every exported function, component, hook, and type. Minimum: one-line summary; add @param, @returns, @throws, @example when non-obvious.
• README.md per feature folder describing purpose, public API, and dependencies.
• Architecture decisions → ADR in docs/adr/NNNN-title.md (context, decision, consequences).
• Do not comment obvious code. Comment why, not what. If a comment explains what, refactor the code instead.
• No dead code. Delete it — git remembers.
• Keep docs/architecture/* in sync when structural changes land in the same PR.

8. Reusable Logic

• DRY, but not premature. Extract on the third occurrence, not the second.
• Custom hooks for stateful/effectful logic reused across components.
• Pure utilities in src/shared/lib/; no React, no I/O.
• Service layer owns cross-feature orchestration; repository layer owns data access. UI never talks to the database directly.
• Prefer composition (higher-order functions, hooks, render props) over inheritance.
• Every reusable primitive ships with: types, tests, TSDoc, and a Storybook entry (when UI).

9. Performance Guidelines

• Route-level code splitting is automatic via TanStack Router. Do not manually React.lazy route files.
• Lazy-load heavy, non-critical modules (charts, editors, maps) with React.lazy + Suspense.
• Images: modern formats (AVIF/WebP), explicit width/height, loading="lazy" below the fold, fetchpriority="high" on LCP.
• Bundle budget: initial JS ≤ 200 KB gzipped. CI fails on regression > 10%.
• Use useDeferredValue / useTransition for expensive derived UI.
• Virtualize lists over 100 items (@tanstack/react-virtual).
• Query caching: set sensible staleTime per query — never leave the default 0 for stable data.
• Debounce user input that triggers network calls (≥ 250 ms).
• Measure before optimizing. Ship a Lighthouse / Web Vitals baseline; regressions block release.

10. Security Guidelines

• Never commit secrets. Use the secrets manager. Publishable/anon keys are OK in code; service-role keys are server-only.
• RLS on every public-schema table. No exceptions. Explicit GRANT statements in the same migration.
• Roles live in a separate user_roles table — never on profiles. Check via SECURITY DEFINER function has_role().
• Validate all inputs with Zod at every trust boundary (server fn, API route, form submit).
• Escape by default — React does this for text; use DOMPurify for any dangerouslySetInnerHTML.
• CSP headers set at the edge. No inline scripts without nonces.
• Auth tokens in httpOnly cookies for SSR, localStorage only when necessary for SPA session recovery.
• Rate-limit all public endpoints and auth routes.
• Webhook handlers verify signatures with timingSafeEqual before processing.
• Dependency audit (bun audit / Snyk) runs on every PR.
• PII: minimize collection, encrypt at rest for sensitive fields, never log.
• Least privilege: server functions use the caller's session; only privileged flows import supabaseAdmin, and only after verifying role via has_role.

11. Testing Guidelines

• Testing pyramid: many unit tests, fewer integration, few E2E.
• Unit (Vitest): pure logic, hooks (@testing-library/react), Zod schemas. Fast, isolated, no network.
• Integration: components + their queries against a mocked API layer (MSW).
• E2E (Playwright): critical user flows only — signup, checkout, primary CRUD. Run against a seeded preview.
• Coverage floor: 80% lines on src/shared/, src/features/*/lib/, and all server functions. UI-only components exempt.
• Test behavior, not implementation. Query by role/label, not by data-testid unless necessary.
• Every bug fix ships with a regression test that fails before the fix.
• Snapshot tests only for stable, small outputs (Zod-generated types, formatters). Never for full component trees.
• Tests must be deterministic — no real dates, no random, no network. Freeze time with vi.useFakeTimers().

12. Maintainability Guidelines

• Feature folders (src/features/<feature>/{components,hooks,lib,api,types}) — code that changes together lives together.
• Cyclomatic complexity per function ≤ 10. Split when higher.
• Function length ≤ 50 LOC; file length ≤ 400 LOC (guideline, not hard rule).
• Single Responsibility at file and function level.
• Explicit dependencies: no global mutable singletons; inject via context, props, or function args.
• Deprecation: mark with @deprecated TSDoc + removal date. CI warns on usage.
• Feature flags (LaunchDarkly / config table) for risky rollouts — never long-lived branches.
• Backwards-compatible migrations: expand → migrate → contract. Never drop a column in the same release that stops writing to it.
• Refactor in small steps. A PR that touches > 20 files needs a written plan in the description.
• Boy-scout rule: leave the code cleaner than you found it, but keep refactors out of feature PRs — separate PRs, separate reviews.
• Ownership: every top-level folder has a CODEOWNERS entry.

Enforcement Matrix

Deviations require an ADR and reviewer sign-off. Standards evolve — propose changes via PR to this document.

Forms & Tables — Enterprise Standards

Two barrel exports:

• @/shared/forms — multi-step, autosave, upload, validation, messaging
• @/shared/tables — search, filters, sort, columns, bulk actions, export/import, cards, responsive view

Both consume only semantic tokens and inherit light/dark theming.

Forms (src/shared/forms/)

Rules

1. All validation goes through zod. Compose primitives from validation.ts. Never validate ad-hoc in components.
2. Inline validation on blur, submit validation on submit (via react-hook-form mode: "onTouched").
3. Field errors use <FormField.Error> from @/shared/components. Form errors use <FormBanner tone="danger">.
4. Success feedback: transient toast via notify.success() for save actions; persistent <FormBanner tone="success"> for stateful states (e.g. "verification email sent").
5. Autosave for anything longer than a single dialog. Show <AutosaveIndicator /> in the form header; call flush() before navigation.
6. Uploads always render FileDropzone/ImageDropzone. Never a bare <input type="file">.

Wizard skeleton

const steps = [
        { id: "profile", title: "Profile" },
        { id: "workspace", title: "Workspace" },
        { id: "invite", title: "Invite team", optional: true },
      ];

      <Wizard steps={steps}>
        <WizardProgress />
        <WizardSteps />
        <WizardStep id="profile">…</WizardStep>
        <WizardStep id="workspace">…</WizardStep>
        <WizardStep id="invite">…</WizardStep>
        <WizardNav onFinish={submit} />
      </Wizard>
      

Tables (src/shared/tables/)

DataTable, Column, and SortState continue to live in @/shared/components — the tables barrel intentionally reuses them.

Rules

1. One source of state. Use useTableControls per page. Do not sprinkle local useState for search/sort/page.
2. Selection is optional. Only render BulkActionsBar when the feature supports bulk operations.
3. Column visibility persists to localStorage per-feature key when meaningful; the toolbar itself is stateless.
4. Export exports the filtered set, not the full dataset — matches user intent.
5. Import always goes through zod validation per row and surfaces a FormBanner summary with error counts.
6. Responsive: below md, prefer ResponsiveDataView. Never let a table horizontal-scroll on phones without an explicit product decision.

Composition skeleton

const controls = useTableControls({
        rows,
        rowKey: (r) => r.id,
        searchFields: ["name", "email"],
        sortFns: { name: (a, b) => a.name.localeCompare(b.name) },
        filterFns: { status: (r, v) => r.status === v },
      });

      <TableToolbar
        search={controls.search}
        onSearchChange={controls.setSearch}
        activeFilterCount={controls.activeFilterCount}
        onClearFilters={controls.clearFilters}
        onExport={() => downloadCsv(controls.filteredRows, columns, "customers")}
      />

      <BulkActionsBar count={controls.selectedIds.size} onClear={controls.clearSelection}>
        <Button size="sm" variant="outline">Archive</Button>
      </BulkActionsBar>

      <ResponsiveDataView
        table={<DataTable columns={cols} rows={controls.pagedRows} rowKey={(r) => r.id} sort={controls.sort} onSortChange={controls.setSort} />}
        cards={<DataCards rows={controls.pagedRows} rowKey={(r) => r.id} primary={(r) => r.name} secondary={(r) => r.email} />}
      />
      

TopAds v1.0.0 — Layout System

Every layout, container, sidebar rail, header row, and section rhythm value in the app is a design token defined in src/styles.css (@theme inline). Never hardcode widths, heights, gutters, or z-index in components — always reference a token or use one of the semantic utilities below.

All values are on an 8-point grid. The base spacing unit is 0.25rem (4px); major layout stops are multiples of 8px.

1. Grid system

• 12-column grid — grid-bento utility. Combine with col-span-{1..12}.
• Auto-fit card grids — grid-cards-sm|md|lg (min 224 / 288 / 352 px).
• Metrics grid — grid-metrics (auto-fit, min 240 px).
• Two-pane — pane-list-detail (mobile stacks, ≥lg splits 22rem + 1fr).
• Three-pane — pane-inbox (folders / list / reader; progressively reveals).
• Canvas + inspector — pane-canvas-inspector (builder shell).
• Sub-nav + content — pane-subnav-content (settings, reports sub-modules).

Row of text + fixed widgets: always use grid-cols-[minmax(0,1fr)_auto] with min-w-0 on text and shrink-0 on icons. flex-wrap alone is not sufficient.

2. Container sizes

Every container applies responsive inline padding:

• --gutter-mobile: 16px
• --gutter-tablet: 24px (≥sm)
• --gutter-desktop: 32px (≥lg)
• --gutter-wide: 40px (≥2xl)

3. Sidebar widths

4. Header heights

Sticky rules:

• sticky-header — z 30, backdrop-blur, top: 0.
• sticky-subheader — z 29, top: var(--header-height).
• sticky-actionbar — z 20, bottom: 0.

5. Content widths

Use content-max-* tokens for any bespoke max-width. Body reading columns should never exceed 75 characters — use container-prose (max-w-prose / 65ch is available in Tailwind's default scale).

6. Card layouts

Cards use bg-card, border-border, rounded-lg, shadow-sm (elevation-sm). Nested cards drop the shadow.

7. Section layouts

Vertical rhythm utility ladder:

8. Spacing rules

• Every gap, padding, margin snaps to 4px multiples; use Tailwind's p-1..96 / gap-1..96 scale.
• Grid gaps: grid-gap-xs 8 / sm 12 / md 16 / lg 24 / xl 32.
• Vertical stack default: space-y-4 (16 px) for form rows, space-y-6 (24 px) for section groups, space-y-8 (32 px) for page-level stacks.
• Never mix pixel and rem raw values — always a token.

9. Sticky components

Z-index ladder tokens: --z-base 0, --z-raised 10, --z-sticky 20, --z-header 30, --z-drawer 40, --z-overlay 50, --z-modal 60, --z-popover 70, --z-toast 80, --z-tooltip 90, --z-command 100.

10. Responsive breakpoints

Rules:

• Mobile-first. Start every component at the smallest breakpoint and step up.
• Sidebar hides below lg; use MobileNav (drawer) instead.
• Three-pane collapses to two panes at xl-, one pane at md-.
• Tables collapse to card lists below md (see DataTable).
• Modals become bottom sheets below sm.
• Height: use 100dvh (h-app, min-h-app) — never 100vh on mobile.

11. Reusable layouts

Each layout in src/shared/layouts/ is a thin, token-only wrapper composed from the primitives (Container, Section, ListDetail, ThreePane, CanvasInspector, SubnavContent).

Mobile / Tablet / Desktop

The layouts are one system across all form factors. Behavior per breakpoint:

• Mobile (<md): sidebar → drawer, three-pane → single pane, cards stack, tables collapse to lists, modals become bottom sheets, tap targets ≥44 px.
• Tablet (md–lg): two panes, expanded filters row, sidebar still drawer.
• Desktop (≥lg): full sidebar, all panes visible, hover states enabled.

12. Rules of use

1. Never hardcode a pixel or rem value for width, height, gutter, sidebar, or z-index — always a token or utility.
2. One h1 per page. Layout headers already render the h1 — do not add another inside the body.
3. Use dvh, not vh. Mobile browsers change viewport height when the URL bar collapses; dvh respects that.
4. Row containing text + widget: grid-cols-[minmax(0,1fr)_auto] + min-w-0 + shrink-0 + truncate.
5. Sticky headers stack: header (30) → subheader (29) → filters may sit inside subheader. Do not create a third sticky row.
6. Reports and super-admin use container-wide (up to 1920 px). Everything else caps at 1440 px.
7. Card padding matches card weight: dense list rows use card-p-xs, feature cards card-p-lg, marketing cards card-p-xl.

Motion Design System

Location: src/shared/motion/ — single barrel @/shared/motion. Powered by Framer Motion, wired to the same duration/ease CSS variables shadcn primitives already use.

Principles

1. Motion is a signal, not decoration. Animate state changes (mount, focus, success), not idle UI.
2. Subtle by default. 150–320 ms, 4–16 px translations, 0.94–1 scale. Above 500 ms only for hero moments.
3. One motion per interaction. Never stack hover-scale + HoverLift + gradient hover on the same element.
4. Respect prefers-reduced-motion. Every helper honors it automatically. Opacity still fades — that isn't vestibular.
5. Framer Motion for stateful animation, CSS keyframes (already in shadcn) for pure enter/exit. Don't double-animate a Radix component.

Tokens

DURATION — instant | fast | normal | slow | slower | lazy (seconds; mirrors --duration-*). EASE — linear | in | out | inOut | emphasized | snappy | spring (cubic-bezier arrays). TRANSITION — presets: ui, snap, sheet, page, spring, softSpring. DISTANCE — enter offsets xs | sm | md | lg.

Variant presets (per surface)

Components

• PageTransition — wrap route content; keyed by pathname. Fades between routes.
• MotionStagger + MotionItem — orchestrated reveal for KPI rows, card grids, activity feeds. Do not use on data-dense tables.
• HoverLift — 2 px card lift on hover with press feedback. Replaces hover-scale for cards.
• SuccessCheck / ErrorCross — path-drawing check + shake for post-submit feedback.
• TypingIndicator — three-dot pulser for chat surfaces.
• LivePulse — pulsing ring for realtime/online status; also used inside RealtimeActivity widget.
• Shimmer — diagonal sweep inside skeletons. Slower + subtler than a spinner.
• CountUp — key-based tween for realtime KPI number updates.
• AnimatedBackdrop — for bespoke modal roots only. Prefer shadcn Dialog/Sheet.

Hooks

• useReducedMotionSafe() — boolean; SSR-safe default of false.
• useSafeVariants(v) — strips transforms when reduced-motion is set.
• motionProps(preset, extra?) — one-liner for variants + initial + animate + exit.

Surface guidance

• Buttons — rely on shadcn's built-in state transitions. Add gestures.buttonTap only for primary CTAs.
• Dropdowns / Popovers / Menus / Tooltips — Radix + shadcn already animate via data-[state] classes. Do not re-animate.
• Modal / Drawer — shadcn Dialog / Sheet provide the enter/exit. Use motion only for custom bespoke overlays.
• Sidebar — the Sidebar primitive animates width. Use variants.sidebarLabel to fade nav labels during collapse.
• Tables — animate arrivals with MotionStagger only when a table has < 25 rows; otherwise no motion.
• Loading — Spinner for < 1 s, Skeleton + Shimmer for > 1 s.
• Hover — HoverLift for cards, story-link for text links, whileHover={gestures.buttonHover} for CTAs. One and only one per element.
• Focus — never animate size on focus. Rely on focus-visible:ring-2 ring-ring from tokens.
• Charts — enable recharts' isAnimationActive at defaults; disable on realtime-updating charts to avoid re-animation on every tick.
• Realtime updates — use CountUp for numbers, LivePulse for presence, MotionItem preset="message" for arriving items in feeds/inboxes.
• Notifications / Toasts — sonner uses its own motion. Do not re-wrap.

Anti-patterns (do not ship)

• Stacked hover effects (scale + lift + glow) on the same element.
• Animating text weight / letter-spacing on hover.
• Bouncy springs on data-dense tables or long lists.
• Auto-playing hero animations without a user trigger.
• Fade durations > 500 ms on utility UI.

TopAds v1.0.0 — Navigation Experience

Fast, animated, keyboard-first navigation across every surface. All surfaces share tokens (--sidebar-*, --header-*, animations from --ease-* + --duration-*) and swap cleanly between light and dark themes.

Global state lives in LayoutProvider (src/shared/contexts/layout-context): sidebar collapse (persisted), mobile drawer state, and a global ⌘K / Ctrl+K listener for the command palette.

Surfaces

Behaviour

Sidebar — expanded ↔ collapsed

• Width: --sidebar-width (256 px) ↔ --sidebar-width-collapsed (68 px).
• Toggle from the topbar, the sidebar edge, or ⌘\ (project convention).
• Icon rail preserves every nav row; labels animate away (animate-fade-in).
• State persists in localStorage (topads.sidebar.collapsed).
• Tooltips (Tooltip primitive) reveal labels when collapsed.

Nested navigation

• Any node can have children. Trees render via NestedNavItem with Radix Collapsible: chevron rotates 90°, panel uses accordion keyframes.
• Auto-opens when a descendant matches the URL.
• Indent per depth: 12 px per level (multiples of 4).
• Collapsed sidebar hides sub-trees — hover shows a fly-out via Tooltip.

Workspace vs Organization

• Organization = tenant / billing owner (top level). One user can belong to many orgs.
• Workspace = a project inside an org. WorkspaceSwitcher scopes to the active org.
• Both switchers use Command inside Popover — same shape, distinct data source.
• Active org id persists per browser (topads.org.active.v1).

Quick search & command palette

• Every surface routes to the same palette (CommandPalette) via useLayout().setCommandOpen(true).
• Global ⌘K / Ctrl+K opens/toggles it (bound in LayoutProvider).
• Palette registers commands from NAV_ITEMS, recent pages, and feature modules (via a registry pattern — modules push their commands on mount).
• Opens with animate-scale-in on a Dialog backed by Radix.

Top navigation (AppTopbar)

• 56 px sticky header (--header-height), backdrop-blur, drops shadow on scroll.
• Contents: mobile menu trigger · search input (⌘K) · notifications · quick actions · theme · user menu.
• Sub-header row (48 px, sticky-subheader) hosts breadcrumbs, tabs, or filters — always sits directly under the header, z-index one below.

Notification center

• Right-aligned Popover with tabs (All / Unread / Mentions).
• Rows animate slide-in-right; unread dot pulses via animate-pulse-soft.
• Deep-links to the underlying entity.

Profile menu

• UserMenu DropdownMenu with avatar trigger.
• Sections: identity → settings shortcuts → theme → sign out.

Favorite pages

• Right-click any nav row → Pin to favorites (NavContextMenu).
• Also togglable via <FavoriteToggleButton path="/reports" /> in page headers — star fills with an animate-scale-in.
• Cap at 12; drag-reorder supported by useFavorites().reorder.
• Persisted in localStorage (topads.favorites.v1).

Recent pages

• Auto-tracked by useRecentPages(). MRU order, deduped, cap 8. Auth / error routes ignored.
• Rendered under the sidebar's "Recent" group.
• Persisted in localStorage (topads.recent.v1).

Breadcrumbs

• Populated by useBreadcrumbs (route matches + loader data) — always reflects the actual matched route.
• Renders in the sub-header row on desktop; hidden below md.

Context menu

• NavContextMenu wraps any nav row (sidebar, favorites, recents, bottom nav). Actions: Go to · Open in new tab · Copy link · Pin/Unpin.
• Opens with animate-scale-in, positioned by Radix.

Floating action button (FAB)

• FloatingActionButton fixed bottom-right. Speed-dial: primary "+" opens a stack of action rows with staggered fade-in (40 ms per step).
• Rotates 45° on open, closes on outside click / Esc / action click.
• Mobile position accounts for the bottom nav + safe-area inset.

Mobile bottom navigation

• Persistent on <md. Height: --commandbar-height (44 px) plus safe-area inset.
• 3–5 primary destinations. Active item shows a top accent bar (bg-accent) animated via fade-in; icon scales to 110 % (transition-transform).
• Overflow lives behind MobileNav (Sheet drawer).

Motion catalog

All animations come from tokens defined in src/styles.css. Do not hand-roll keyframes in components.

All animations respect prefers-reduced-motion via base CSS.

Keyboard shortcuts

⌘K is bound globally in LayoutProvider. G-prefix shortcuts are registered per nav item (NavItem.shortcut).

Rules of use

1. Never hardcode a sidebar or header width — always the --sidebar-* and --header-* tokens.
2. One sticky row per z-index level. Header (z 30) → sub-header (z 29) → action bar (z 20). Bottom nav shares z 30 but is bottom-anchored.
3. FAB and bottom nav coexist: FAB sits above the bottom nav on mobile via the safe-area calc — do not lift the FAB into the topbar.
4. Every nav row is wrappable in NavContextMenu. Do not build ad-hoc right-click menus for individual features.
5. Favorites and Recents are user-scoped state (localStorage). Never sync them to the server without an explicit user setting — they are meant to feel instant.
6. Animations respect the motion catalog above. Never write a bespoke keyframe for a nav element.

Production Readiness

Enterprise operations manual for this application. Every section maps to a real file, tool, or runbook — no aspirational content.

1. Environment Configuration

• .env.example is the canonical schema. Every env var used anywhere in the code must appear there.
• Three tiers:
  • VITE_* — client-visible, bundled at build time (publishable keys, public URLs).
  • Server-only (SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, LOVABLE_API_KEY, SENTRY_DSN, WEBHOOK_SIGNING_SECRET) — never sent to the browser, read only inside createServerFn handlers or .server.ts modules.
  • Build-time (APP_VERSION, APP_COMMIT) — baked in via Docker ARG.
• Secrets storage: Lovable Cloud secrets manager for runtime; Workspace → Build Secrets for bun install credentials. Never commit .env.
• Validation: all process.env.* reads happen inside handlers (never at module scope), and every server function validates its inputs with Zod.

2. Docker Support

• Dockerfile — multi-stage (deps → build → runtime), non-root user, Alpine base, HEALTHCHECK wired to /api/public/health.
• docker-compose.yml — single-node local/staging bring-up with CPU/memory caps and JSON log rotation.
• .dockerignore — excludes .git, node_modules, .env*, docs/, tests/.
• Image tagging: registry/app:<git-sha> and registry/app:<semver>. latest only for local.
• Runtime target: the Lovable-hosted deployment runs on Cloudflare Workers (edge). The Docker image exists for self-hosting, staging replicas, and CI end-to-end tests.

3. Build Optimization

• Vite 7 + TanStack Start production build (bun run build) — automatic route-level code splitting, tree-shaking, minification, CSS purge.
• Bundle budget: initial JS ≤ 200 KB gzipped; enforced by size-limit in CI.
• Source maps: uploaded to Sentry, stripped from the shipped bundle.
• Compression: Brotli + gzip at the edge (Cloudflare handles automatically).
• Asset hashing: immutable, content-hashed filenames → 1-year cache.

4. Security Headers

Applied at the edge (Cloudflare) via response headers or _headers file:

Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
      X-Content-Type-Options: nosniff
      X-Frame-Options: DENY
      Referrer-Policy: strict-origin-when-cross-origin
      Permissions-Policy: camera=(), microphone=(), geolocation=(), interest-cohort=()
      Content-Security-Policy: default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self' https://*.supabase.co wss://*.supabase.co https://*.sentry.io; frame-ancestors 'none'; base-uri 'self'; form-action 'self'
      Cross-Origin-Opener-Policy: same-origin
      Cross-Origin-Resource-Policy: same-origin
      

• CSRF: SameSite=Lax cookies + Origin header check on state-changing server routes.
• Rate limiting: 100 req/min/IP on /api/public/* (Cloudflare Rules).
• Bot protection: Cloudflare Turnstile on auth flows.

5. Performance Optimization

• Route-level code splitting — automatic via TanStack Router (autoCodeSplitting: true).
• Lazy load heavy modules: charts (recharts), rich editors, maps — React.lazy + Suspense.
• LCP preload on hero routes: head().links with rel="preload".
• useDeferredValue / useTransition for expensive filters.
• List virtualization at 100+ items (@tanstack/react-virtual).
• Query caching — sensible staleTime per query; TanStack Query dedupes concurrent reads.
• Debounce ≥ 250 ms on typeaheads.
• Web Vitals target: LCP < 2.5s, INP < 200ms, CLS < 0.1.

6. Image Optimization

• Source assets in src/assets/, built-time optimized via vite-imagetools:

  import heroAvif from './hero.jpg?format=avif';
        import heroWebp from './hero.jpg?format=webp';
        

• Dynamic images (user uploads, CMS) → Cloudflare Image Resizing.
• Explicit width / height on every <img> to prevent CLS.
• loading="lazy" below the fold; fetchpriority="high" on the LCP image.
• Modern formats first: AVIF → WebP → JPEG fallback.

7. Caching Strategy

8. Realtime Strategy

• Supabase Realtime for row-level updates (chat, notifications, live dashboards).
• Subscribe scoped to workspace/org, never global.
• Unsubscribe on component unmount — leaks are a production incident.
• Fall back to polling every 30s when the socket drops > 3 times.
• Presence via Realtime Presence channels, keyed by workspace + user.
• Rate: batch UI updates through requestAnimationFrame when > 10 events/sec.

9. Logging Strategy

• Structured JSON logs in production via src/shared/lib/logger.ts (logger.info, logger.warn, logger.error).
• Standard fields: level, event, timestamp, plus per-call context (userId, orgId, requestId).
• Never log PII, tokens, secrets, full request bodies, or auth headers.
• Retention: 30 days hot (Cloudflare Logpush → S3 / Datadog), 1 year cold in object storage.
• Every server function starts with const log = logger.child({ fn: 'name', userId }).

10. Monitoring Strategy

• Uptime: external HTTP probe against /api/public/health every 60s (BetterUptime / Pingdom).
• Readiness: /api/public/health/ready — deep check with DB round-trip; used by deployers, not load balancers.
• RUM: Web Vitals reported to the monitoring backend per navigation.
• APM: server-function latency P50/P95/P99, error rate, throughput.
• Alerts (PagerDuty):
  • Error rate > 1% for 5 minutes
  • P95 latency > 1s for 10 minutes
  • Health check failing 3× in 5 minutes
  • Database connection saturation > 80%
• Dashboards: one per bounded context (auth, billing, CRM), plus a top-level SLO board.

11. Error Reporting

• Sentry (or equivalent) initialized in src/router.tsx for client and in src/start.ts for server.
• Every route sets errorComponent + notFoundComponent; the root sets notFoundComponent and defaultErrorComponent.
• Server functions call reportError(err, { fn, userId }) from @/shared/lib/logger.
• Source maps uploaded on every deploy; releases tagged with APP_COMMIT.
• User-facing errors show a stable incident ID the user can share with support.

12. Backup Strategy

• Database (Supabase-managed):
  • Continuous WAL archiving with Point-In-Time Recovery (7-day window on Pro, extendable).
  • Nightly logical pg_dump to an off-region S3 bucket, encrypted at rest (SSE-KMS).
  • Weekly snapshot verified via automated restore into a staging project.
• File storage: Supabase Storage → cross-region replication enabled; lifecycle rules move cold objects to cheaper tier after 90 days.
• Configuration: infra-as-code in git (this repo + terraform/); secrets exportable via Cloud dashboard.
• Retention: 30 days daily, 12 months monthly, 7 years yearly (compliance).

13. Disaster Recovery

• RPO (data loss tolerance): ≤ 5 minutes.
• RTO (time-to-recover): ≤ 60 minutes for full-region outage.
• Playbooks in docs/runbooks/:
  • db-restore.md — PITR restore from timestamp
  • region-failover.md — swap to secondary region
  • key-rotation.md — rotate service role and signing keys
  • data-breach.md — legal + comms + technical steps
• DR drill quarterly: restore last night's backup into a fresh project, run smoke tests, decommission.
• Circuit breakers on all outbound integrations; graceful degradation when a dependency is down.

14. Health Checks

• Liveness — GET /api/public/health — 200 = process alive. No dependencies. Used by container orchestrator.
• Readiness — GET /api/public/health/ready — 200 = able to serve traffic (DB reachable). Used by deployers and load balancers.
• Startup — same as readiness; container HEALTHCHECK uses 15s start_period.
• Response includes: status, version, commit, timestamp, dependency-level checks with latency.

15. Scalable Configuration

• Stateless workers — every server instance is disposable. No in-memory sessions, no on-disk uploads.
• Horizontal scaling at the edge (Cloudflare Workers scale to zero and up automatically).
• Database: connection pooling via Supabase pooler; long-running queries offloaded to background jobs.
• Rate limiting per user + per IP (Cloudflare + application-layer for authenticated routes).
• Feature flags for gradual rollouts (FEATURE_* env vars → later a proper flag service).
• Multi-tenancy enforced by RLS at the DB layer + organization_id on every tenant row.
• Async work: long tasks pushed to Supabase pg_cron or a queue (never block a request > 3s).

16. Developer Experience

• One-command bootstrap: bun install && bun dev.
• .env.example covers every var; missing vars fail fast with a clear message.
• Type-safe throughout: strict TypeScript, Zod at trust boundaries, generated Supabase types.
• Pre-commit hooks (lint-staged): ESLint + Prettier on staged files.
• CI matrix: typecheck, lint, unit tests, build, bundle-size, dependency audit — all required to merge.
• Storybook for visual components; Playwright for E2E.
• Docs live in the repo (docs/architecture/, docs/runbooks/) — reviewed like code.
• CODEOWNERS enforces reviewer coverage on every top-level folder.

17. Deployment Readiness

Pre-flight checklist — every item must be green before a production deploy:

• All tests pass (bun test, Playwright E2E)
• Typecheck passes (tsgo)
• Lint passes (bun lint)
• Bundle size within budget
• Dependency audit clean (no criticals)
• Migrations reviewed and applied on staging first
• Feature flags configured for gradual rollout
• Sentry release created and source maps uploaded
• Health check green on staging
• Smoke test suite green on staging
• Rollback plan documented in the PR
• On-call engineer paged for the window

Deploy flow: git push → CI → staging → smoke test → production (manual approval) → post-deploy verification (5-min error-rate watch).

Rollback: every deploy is atomic. lovable rollback (or re-deploy previous git SHA) restores the last known good version in < 60 seconds. Database migrations MUST be backward-compatible (expand → migrate → contract) so rollbacks never require a schema revert.

Foundation Complete

Phase 1 (foundation) is done. The application now has:

• Software architecture, routing, layout, design tokens, UI standards, dev standards
• Core enterprise schema (orgs, RBAC, billing, audit, notifications, files, sessions, API keys, settings, activities) with RLS
• Production configuration: env, Docker, health checks, logging, security, monitoring hooks

Phase 2 builds domain modules (CRM, campaigns, automations, reports, billing UI, admin) on top of this foundation.

TopAds Architecture

Feature-based, domain-driven, multi-tenant SaaS. Designed to scale horizontally to millions of users on a stateless edge runtime with Postgres + RLS.

Layers

src/
      ├── routes/           TanStack Router file-based routes (URL surface)
      ├── features/         Feature modules (domain logic, isolated)
      │   ├── auth/
      │   ├── dashboard/
      │   ├── crm/          { inbox, contacts, companies, deals }
      │   ├── marketing/    { campaigns, automation }
      │   ├── ai-assistant/
      │   ├── reports/
      │   ├── settings/
      │   ├── billing/
      │   └── super-admin/
      ├── shared/           Cross-feature reusable code
      │   ├── components/   Design-system + composite UI
      │   ├── hooks/        Reusable hooks
      │   ├── services/     API clients, messaging adapter, AI gateway
      │   ├── store/        Global client state (zustand)
      │   ├── contexts/     React contexts
      │   ├── providers/    App-level provider composition
      │   ├── layouts/      Shell layouts (app, marketing, admin)
      │   ├── types/        Shared TypeScript types
      │   ├── constants/    App-wide constants
      │   ├── utils/        Pure utilities
      │   ├── config/       Runtime config, feature flags
      │   └── lib/          Third-party wrappers
      ├── assets/           Static assets (images, icons, fonts)
      └── integrations/     Auto-generated integrations (Supabase)

      supabase/
      ├── migrations/       SQL schema migrations (source of truth)
      └── functions/        Edge functions (webhooks, external callbacks)
      

Rules

1. Feature isolation — a feature never imports from a sibling feature. Cross-feature communication happens through shared/ or route composition.
2. API access — every feature exposes typed server-fn wrappers under features/<name>/api/. Components never call Supabase directly.
3. Multi-tenant — every domain table is scoped by workspace_id with RLS enforcing membership.
4. Types — every feature owns its types/ folder; only truly shared contracts live in shared/types.
5. Server logic — createServerFn for app-internal calls; src/routes/api/public/* for webhooks; Supabase edge functions only when an external caller must land inside the Supabase network.

TopAds — Routing Architecture

File-based routing on TanStack Router v1. Every URL surface is exactly one of: public, guest-only, authenticated (workspace), admin (workspace-role gated), or super-admin (platform-role gated).

Route classes

Pathless layouts (_authenticated, _super-admin) add no URL segment, so the URLs stay clean: /dashboard, /admin, /admin/workspaces.

Current URL surface

Public
        /                     Landing
        /features             Feature marketing
        /pricing              Plans
        /about                Company
        /contact              Contact channels
        /legal/privacy        Privacy policy
        /legal/terms          Terms of service
        /403                  Forbidden
        /maintenance          Scheduled maintenance (auto-refresh)
        /sitemap.xml          SEO sitemap

      Guest-only
        /auth                 Sign-in / sign-up

      Authenticated (workspace)
        /dashboard            Overview
        /inbox                Unified inbox
        /contacts             Contacts list
        /contacts/$contactId  Contact detail  (dynamic)
        /companies            Companies
        /deals                Sales pipeline
        /campaigns            Marketing campaigns
        /automations          Workflow builder
        /ai-studio            AI features
        /analytics            Live metrics
        /reports              Reporting
        /team                 Members & roles
        /settings             Workspace settings
        /billing              Plan & invoices

      Super-admin (platform-role gated)
        /admin                Overview
        /admin/workspaces     All tenant workspaces
        /admin/users          Platform users
      

Guards

Authentication guard (managed) — src/routes/_authenticated/route.tsx Runs client-side (ssr: false) because the Supabase session lives in localStorage. Redirects to /auth when no session. All authenticated URLs inherit this — no per-page checks required.

Guest guard — src/routes/auth.tsx beforeLoad reads the session and redirects signed-in visitors to /dashboard. Prevents the "sign-in loop after login" bug.

Workspace-role guard (permissions) — _workspace-admin pathless layout Reads the active workspace's workspace_members.role via useWorkspacePermissions() (hook that queries the has_workspace_role security-definer function). Non-owner/admin are redirected to /403.

Platform-role guard — _super-admin pathless layout Reads user_roles.role via usePlatformRole(). Only superadmin and support pass; everyone else lands on /403.

Defense in depth: UI guards drive visibility only. Every server function that a guarded route calls repeats the check server-side (requireSupabaseAuth + assertRole), and RLS enforces the final layer at the database.

Error, 404, 403, maintenance

• 404 unmatched URL — root notFoundComponent in __root.tsx + router defaultNotFoundComponent in router.tsx.
• 404 missing resource — a route's loader throws notFound(); the route's own notFoundComponent receives the params (see contacts.$contactId.tsx).
• 403 — dedicated /403 route. Guards navigate({ to: '/403', replace: true }) on failed permission checks.
• Maintenance — dedicated /maintenance route with <meta http-equiv="refresh" content="60"> for auto-recovery. Toggled by an env flag / feature flag in a future edge middleware.
• Route errors — every route with a loader defines errorComponent; the router provides a defaultErrorComponent fallback. Loader retry uses router.invalidate() + reset() together — reset() alone does not re-run the loader.

Nested routes

Two conventions:

1. Dot-nested leaves (flat filesystem, one segment per dot): _authenticated/contacts.$contactId.tsx → /contacts/$contactId.
2. Pathless layouts (grouping without adding to URL): _authenticated/_super-admin.tsx groups /admin, /admin/workspaces, /admin/users under one gate.

Parent layouts always render <Outlet /> so children mount. Never gate <Outlet /> on pathname.

Dynamic routes

• Segments use $name — never :name or template strings.
• Detail routes fetch in the loader via context.queryClient.ensureQueryData(...) and read in the component with useSuspenseQuery(...). Route params reach the loader through ({ params }).
• Optional segments use {-$param} (e.g. /{-$locale}/about).
• Splat routes use bare $ (e.g. docs/$.tsx → _splat).

Lazy loading & code splitting

Enabled by default via TanStack Router's Vite plugin (autoCodeSplitting: true):

• component, errorComponent, pendingComponent, notFoundComponent are split out of each route module and lazy-loaded.
• loader, beforeLoad, validateSearch, head, and route context stay in the main critical chunk so navigation and preloading are instant.
• Never export a component from a route file — exported functions bypass splitting. Components stay as internal function XPage().
• For heavier client-only libraries inside a route (map, editor), use React.lazy behind <ClientOnly> — don't import the browser-only module at module scope.

Preloading & scroll

Router defaults (in src/router.tsx):

defaultPreload: "intent",     // preload on hover/focus
      defaultPreloadStaleTime: 0,    // Query owns freshness
      scrollRestoration: true,
      

Every <Link> benefits automatically. Use preload="viewport" for below-the-fold prefetches when needed.

Breadcrumbs

Route files opt in with staticData: { breadcrumb: "Contacts" }. useBreadcrumbs() walks the current match chain and returns { label, to }[]; <Breadcrumbs /> renders it.

Dynamic routes can override with a computed label from loaderData via an inline <Breadcrumbs items=...> prop (planned) or by naming the route's staticData and enriching in the page shell.

Error boundaries — placement

1. Router-level default — defaultErrorComponent, catches any un-handled loader/component error.
2. Root — __root.tsx errorComponent handles catastrophic failures (bad providers, etc.) and reports via reportLovableError.
3. Route-level — every route with a loader owns its own errorComponent so a single feature failure never blanks the shell.
4. Component-level — <ErrorBoundary> wrappers inside features that render external widgets or heavy async subtrees.

Scaling this router

• Add a new authenticated feature → drop src/routes/_authenticated/<slug>.tsx. Zero wiring.
• Add a new sub-page → dot-nest: <slug>.<sub>.tsx. Its URL is /<slug>/<sub> automatically.
• Add a new access class → new pathless layout under the appropriate parent with its own beforeLoad guard.
• Introduce SSR for a public route → remove ssr: false; ensure the loader uses only public server fns.
• Rate-limit or i18n prefix → wrap the whole tree in an _optional-locale layout ({-$locale}) or add a Cloudflare Worker route middleware for rate limits — routing stays the same.

The current tree already accommodates hundreds of routes without restructuring: features are independent files, guards are single pathless layouts, and TanStack's plugin handles the split/preload/tree generation.

TopAds — Software Architecture

Enterprise, multi-tenant, edge-first SaaS. Layered architecture with strict boundaries: each layer talks only to the one directly beneath it (or to explicit cross-cutting layers: logging, monitoring, errors). No layer reaches "up".

┌─────────────────────────────────────────────────────────────────┐
      │                    PRESENTATION (React 19)                       │
      │   Routes · Layouts · Feature Components · Design System          │
      └───────────────▲───────────────────────────────▲─────────────────┘
                      │ hooks / query                 │ realtime channels
      ┌───────────────┴────────────┐   ┌──────────────┴─────────────────┐
      │   STATE MANAGEMENT         │   │       REALTIME LAYER            │
      │  TanStack Query (server)   │   │  Postgres CDC · presence · WS   │
      │  Zustand (client/UI)       │   │                                 │
      └───────────────▲────────────┘   └──────────────▲─────────────────┘
                      │                                │
      ┌───────────────┴────────────────────────────────┴─────────────────┐
      │                    BUSINESS LOGIC (features/*)                   │
      │  Use-cases · domain rules · orchestration · validators (Zod)     │
      └───────────────▲──────────────────────────────────────────────────┘
                      │
      ┌───────────────┴──────────────────────────────────────────────────┐
      │                        SERVICE LAYER                              │
      │  MessageProvider adapter · AI Gateway · Billing · Notifications   │
      │  Storage · Email · Webhooks · Search                              │
      └───────────────▲──────────────────────────────────────────────────┘
                      │
      ┌───────────────┴──────────────────────────────────────────────────┐
      │              API LAYER (createServerFn + api/public/*)            │
      │   Auth middleware · input validation · rate-limit · RPC contract  │
      └───────────────▲──────────────────────────────────────────────────┘
                      │
      ┌───────────────┴──────────────────────────────────────────────────┐
      │                     REPOSITORY LAYER                              │
      │  Typed data-access modules · pagination · RLS-aware queries       │
      └───────────────▲──────────────────────────────────────────────────┘
                      │
      ┌───────────────┴──────────────────────────────────────────────────┐
      │              DATABASE (Postgres · RLS · pg_cron · pgvector)       │
      └──────────────────────────────────────────────────────────────────┘

      Cross-cutting: Authentication · Permissions · Caching · Logging ·
      Monitoring · Error Handling · Notifications · Storage
      

1. Component Architecture (Presentation)

Location: src/features/*/components, src/shared/components, src/routes/*, src/shared/layouts.

Three tiers:

1. Design-system primitives (shared/components/ui) — shadcn/Radix wrappers, no business logic, fully themable via CSS tokens.
2. Composite components (shared/components/*) — reusable building blocks (DataTable, KanbanBoard, FilterBar, EmptyState, ChannelBadge).
3. Feature components (features/<domain>/components) — bound to a domain (e.g. InboxThreadList, DealPipelineColumn, CampaignComposer).

Rules

• Components are pure view + interaction. They read data via hooks, never call supabase.* directly.
• Presentational vs container split: containers own hooks and state; presentational components take props.
• Every feature exposes a public surface via features/<name>/index.ts; internal files are not imported cross-feature.
• Routes (src/routes) compose layouts + feature containers; they own SEO head() and loader wiring.

2. Business Logic Layer

Location: src/features/*/hooks, src/features/*/utils, src/features/*/api/*.functions.ts (handler bodies).

Encapsulates use-cases and domain rules:

• assignConversation(threadId, agentId) — validates workspace membership, checks agent capacity, writes assignment, emits event.
• scoreLead(contactId) — computes a lead score from signals (recency, message volume, tags).
• canSendCampaign(campaign, workspace) — plan-limit + template-approval + rate-window rules.

Rules

• Domain logic lives here — not in components, not in repositories.
• Input is validated with Zod at the entry point of every server function.
• Pure where possible; side effects delegated to the Service layer.

3. Service Layer

Location: src/shared/services/*.

Adapters over external systems, each behind an interface so implementations are swappable.

Rules

• Services are stateless factories/objects; they never import features or repositories.
• Selection of implementation happens once in shared/providers/services.ts from shared/config.
• Retries, timeouts, and circuit-breaker behavior live here — not in features.

4. Repository Pattern

Location: src/features/*/api/repositories/*.ts (server-only helpers, .server.ts when they hold secrets).

One repository per aggregate root: ContactsRepository, ConversationsRepository, MessagesRepository, DealsRepository, CampaignsRepository, AutomationsRepository, WorkspacesRepository, MembersRepository, BillingRepository, AuditRepository.

Each exposes a typed API:

interface ContactsRepository {
        findById(id: string): Promise<Contact | null>;
        list(params: ListContactsParams): Promise<Page<Contact>>;
        create(input: NewContact): Promise<Contact>;
        update(id: string, patch: Partial<Contact>): Promise<Contact>;
        softDelete(id: string): Promise<void>;
      }
      

Rules

• Repositories are the only place that speaks SQL / PostgREST.
• They accept the Supabase client from context (context.supabase for user-scoped, supabaseAdmin for privileged) — never construct one themselves.
• They do not enforce authorization (RLS does) — they enforce shape (pagination bounds, allowed sort keys, projection).
• Return DTOs, not raw provider rows. Map at the boundary.

5. API Layer

Location: src/features/*/api/*.functions.ts and src/routes/api/public/*.

Two entry types:

• createServerFn — typed RPC for the app's own client. Default choice.
• Server routes under src/routes/api/public/* — webhooks (Meta, Stripe/Paddle), cron, third-party integrations. Signature-verified.

Every server function follows the same pipeline:

requireSupabaseAuth  ──▶  input validation (Zod)  ──▶  permission check
                          ──▶  use-case (business)      ──▶  repository call(s)
                          ──▶  side-effects (services)  ──▶  audit log
                          ──▶  DTO return
      

Rules

• Public endpoints (unauthenticated createServerFn or api/public/*) are opt-in and explicitly documented.
• Rate limiting is applied per workspace + IP at this layer.
• No business logic inline — orchestrate only.

6. State Management

Server state: TanStack Query — the single source of truth for anything that came from the API. Keys are stable (['contacts', workspaceId, filters]), invalidation is explicit.

Client state: Zustand slices in shared/store/:

• uiStore — sidebar collapse, modals, command palette.
• workspaceStore — active workspace, active channel.
• presenceStore — realtime presence cache.
• draftsStore — persisted composer drafts (localStorage).

Form state: React Hook Form + Zod resolver, scoped to the form.

Rules

• Never mirror server data into Zustand. If it came from the server, it stays in Query.
• No global Redux-style singletons; each store is a self-contained slice.

7. Authentication Layer

Location: src/features/auth, src/integrations/supabase/* (managed), src/routes/_authenticated/route.tsx (managed gate).

• Supabase Auth (email/password + Google OAuth via the Lovable broker).
• Session persisted client-side; server functions receive it as a bearer via functionMiddleware (attachSupabaseAuth).
• requireSupabaseAuth middleware on every protected server fn — validates JWT, injects supabase, userId, claims.
• OAuth redirect_uri points to a public callback route, then navigates to the intended destination after session hydration.
• Sign-out clears TanStack Query cache, cancels in-flight queries, then signOut(), then navigate({ to: '/auth', replace: true }).

8. Permission Layer

Roles (per workspace): owner, admin, manager, agent, viewer. Platform roles (global): superadmin, support.

Storage: workspace_members(workspace_id, user_id, role) — never on profiles. Global roles in user_roles(user_id, role app_role).

Enforcement — defense in depth:

1. DB (authoritative): RLS policies use SECURITY DEFINER helpers is_workspace_member(ws, user) and has_workspace_role(ws, user, roles[]). Every domain table is scoped by workspace_id.
2. API: server functions call assertRole(context, workspaceId, ['owner','admin']) before privileged writes; superadmin actions call has_role(userId, 'superadmin') before importing supabaseAdmin.
3. UI: usePermissions() hook drives visibility of controls — presentational only, never a security boundary.

9. Realtime Layer

Location: src/shared/services/realtime/, feature-scoped subscriptions in features/*/hooks.

• Postgres CDC via Supabase Realtime for messages, conversations, deals, presence.
• One channel per resource-scope, e.g. workspace:{id}:inbox, conversation:{id}.
• Subscriptions live inside useEffect with teardown; never at module or component-body scope.
• Payloads flow into TanStack Query via queryClient.setQueryData for the affected key — no duplicate stores.
• RLS applies to Realtime too: policies gate which rows any subscriber receives.

Presence (typing, agent-online) uses Realtime's presence primitive, cached in presenceStore.

10. Notification Layer

Location: src/shared/services/notifications/.

Fan-out design:

Event ──▶ NotificationRouter ──▶ [InAppChannel, EmailChannel, PushChannel, WebhookChannel]
                                    ▲
                                    └── per-user preferences + workspace policy
      

• Events are emitted from the Business layer (emit('conversation.assigned', payload)).
• notifications table stores in-app entries; Realtime pushes them to the recipient's session.
• Email uses the platform provider; webhooks are signed (HMAC-SHA256) with per-workspace secrets.
• Digest/quiet-hours logic lives in the router, not in emitters.

11. Storage Layer

Location: src/shared/services/storage/.

• Supabase Storage buckets: avatars (public), attachments (private, signed URLs), imports (private, TTL), exports (private, TTL).
• Uploads go through server functions that:
  1. Validate MIME + size against workspace plan.
  2. Scan for malware hooks (pluggable).
  3. Write metadata to attachments table with workspace_id.
  4. Return a signed URL scoped by expiry.
• Direct client uploads use short-lived signed upload URLs — never long-lived service credentials.

12. Database Layer

Postgres with strict conventions:

• Every domain table has id uuid pk, workspace_id uuid not null references workspaces(id) on delete cascade, created_at, updated_at, and a tg_set_updated_at trigger.
• CREATE TABLE in public is always followed by GRANT + ENABLE RLS + policies in the same migration.
• Soft-delete via deleted_at timestamptz for user-recoverable entities; partial indexes exclude soft-deleted rows.
• Indexes: (workspace_id, created_at desc) on hot lists; GIN on tsvector search columns; pgvector for AI embeddings.
• pg_cron for retention, digest emails, campaign schedulers.
• Migrations are the source of truth; no ad-hoc schema changes.

13. Logging Layer

Location: src/shared/services/logging/.

• Structured JSON logs with fixed fields: ts, level, event, workspace_id, user_id, request_id, duration_ms, error.
• Server-side: emitted from server-fn middleware wrapping every handler.
• Client-side: only warn / error are shipped, sampled, and stripped of PII.
• Audit events (security-relevant: role change, export, sign-in from new device) go to an append-only audit_log table with RLS restricting reads to workspace admins + platform superadmins.

14. Monitoring Layer

Location: src/shared/services/monitoring/.

• Health: /api/public/health returns db + provider reachability.
• Metrics counters per server fn: requests_total, errors_total, latency_ms_p95, provider_calls_total.
• Realtime dashboards in Super Admin: MAU/DAU, message volume, campaign throughput, AI token spend per workspace.
• Alerts on error-rate spikes and provider failures fire through the Notification layer to a platform-ops channel.

15. Caching Layer

Tiered:

Rule: cache keys always include workspace_id to prevent cross-tenant bleed.

16. Error Handling Layer

Location: src/shared/lib/errors.ts, route errorComponent/notFoundComponent, server-fn middleware.

• Typed error hierarchy: AppError → ValidationError, AuthError, PermissionError, NotFoundError, ConflictError, RateLimitError, ProviderError, InternalError.
• Server functions convert unknown errors into InternalError and log the original — clients never see raw provider errors or stack traces.
• Every route with a loader defines errorComponent + notFoundComponent; root defines notFoundComponent + defaultErrorComponent.
• Client boundary: ErrorBoundary around each feature shell, plus a global one in __root.tsx.
• Retries: only for idempotent GETs with exponential backoff, capped; never for POST/PATCH/DELETE.

Module Communication — end-to-end flow

Example: agent sends a WhatsApp reply.

1. Inbox composer (component)
         └── calls hook useSendMessage()  ── React Hook Form + Zod

      2. Hook invokes server fn sendMessage()   [API layer]
         └── functionMiddleware attaches bearer

      3. sendMessage() handler:
         a. requireSupabaseAuth              → context.supabase, userId
         b. Zod validates payload            [Business validator]
         c. assertRole(ctx, wsId, ['owner','admin','manager','agent'])   [Permission]
         d. ConversationsRepository.findById(threadId)                    [Repository]
         e. MessageProvider.send(...)         [Service — Meta/Mock/OnPrem]
         f. MessagesRepository.insert(...)                                [Repository]
         g. AuditLogger.record('message.sent', ...)                       [Logging]
         h. NotificationRouter.emit('message.sent', ...)                  [Notification]
         i. return DTO

      4. Postgres trigger publishes CDC row → Realtime channel
         conversation:{id}

      5. Other agents' clients receive the payload → queryClient.setQueryData
         updates the thread in place; unread counters recompute.  [State + Realtime]

      6. Failures:
         - ValidationError → 400 to caller, form field errors
         - ProviderError   → 502, retry banner in UI, logged with correlation id
         - Any error       → structured log + metric increment + audit entry
      

Example: superadmin suspends a workspace.

UI action ─▶ server fn suspendWorkspace()
                ─▶ requireSupabaseAuth
                ─▶ has_role(userId, 'superadmin')   [Permission — global]
                ─▶ dynamic import supabaseAdmin      [Admin service role]
                ─▶ WorkspacesRepository.setStatus('suspended')
                ─▶ NotificationRouter.emit('workspace.suspended')
                ─▶ AuditLogger.record(...)
                ─▶ Realtime CDC broadcasts to affected workspace sessions
                   → clients invalidate queries → app shell renders suspended state
      

Enterprise Principles Applied

• Separation of concerns — each layer has one responsibility and one direction of dependency.
• Dependency inversion — features depend on service interfaces, not implementations; providers wire concretes at composition root.
• Multi-tenancy by construction — workspace_id is a first-class column and appears in every RLS policy, cache key, log entry, and metric label.
• Defense in depth — auth at edge, RLS at DB, permission checks in code, UI gating for UX only.
• Observability by default — every server fn is wrapped with logging, metrics, and audit hooks; nothing opts in ad-hoc.
• Idempotency and safety — mutations accept an optional idempotency_key; retries are bounded and only for safe verbs.
• Failure isolation — provider outages degrade a single feature (banner + queued retry), never the whole app.
• Scalability — stateless edge runtime, Postgres as the durable core, CDN + query cache for reads, pg_cron + queues for async work; horizontal scale is a config change, not a rewrite.

TopAds v1.0.0 — Typography System

Premium, enterprise-grade typography for the entire TopAds app. All values are defined as design tokens in src/styles.css (@theme inline block) and exposed as Tailwind v4 utilities. Never hardcode font-family, font-size, font-weight, line-height, or letter-spacing — always use a token or a semantic utility below.

The system is 8-point aligned: every size, line-height, and vertical rhythm value is a multiple of 4px (0.25rem), with major stops at 8px multiples.

1. Fonts — three roles

All three families are loaded via <link> tags in src/routes/__root.tsx. Never @import a font URL inside src/styles.css.

Rule: one display font per screen. Never mix Space Grotesk with a third family. Inter carries every product surface; Space Grotesk is reserved for moments of scale (hero, giant metric, empty state).

2. Type scale (8-pt aligned)

Every size ships with paired line-height and letter-spacing tokens so the utility (e.g. text-lg) is already correctly kerned. The rem column is the source of truth — the raw --text-* custom property declared in src/styles.css under @theme. All utilities (text-sm, text-body-md, the <Text> primitive) derive their font-size from these variables, so editing a row here means editing exactly one place.

Correction (2026-07): --text-sm was previously 0.813rem (~13px), which broke the 8-pt rhythm and drifted from the Tailwind default. It is now 0.875rem (14px). Do not restore the old value — the tests/e2e/typography-tokens.spec.ts guard will fail if it drifts.

3. Weights

Use only the tokens below — never a numeric literal like font-[550].

Rule: the product default weight is 400 for body and 500 for labels. Never use 300 or lighter in the product UI — it fails contrast at small sizes.

4. Line heights

5. Letter spacing

Rule: large text needs negative tracking, small uppercase text needs positive tracking. This is baked into every semantic utility below — you rarely need to set tracking manually.

6. Semantic role utilities

These are the utilities you use in components. They bundle family + size + weight + line-height + tracking so the type stays consistent across the app.

Display — marketing & hero (Space Grotesk, fluid)

text-display-2xl · text-display-xl · text-display-lg · text-display-md · text-display-sm

Fluid via clamp() — scales between mobile and desktop without breakpoints.

Heading — product UI (Inter)

text-heading-h1 · text-heading-h2 · text-heading-h3 · text-heading-h4 · text-heading-h5 · text-heading-h6

One h1 per page. Prefer semantic elements plus the matching utility.

Body

text-body-lg · text-body-md · text-body-sm · text-body-xs

text-body-md is the default reading size (16/26). text-body-sm is the default UI size (14/20).

Label — form + control labels

text-label-lg · text-label-md · text-label-sm

Caption — meta / helper text (muted)

text-caption · text-caption-sm

Eyebrow — uppercase section kickers

text-eyebrow — 12px semibold, +0.14em tracking, uppercase, muted.

Button typography

text-button-xs · text-button-sm · text-button-md · text-button-lg · text-button-xl

Line-height is 1 on every button so vertical padding is deterministic. Pair with the --size-button-* tokens.

Navigation typography

text-nav-primary — top bar links text-nav-secondary — sub-nav text-nav-section — uppercase group heading

Sidebar typography

text-sidebar-brand — logo wordmark text-sidebar-section — group heading (uppercase, muted on dark rail) text-sidebar-item — nav row text-sidebar-badge — counters (tabular)

Dashboard typography

text-metric-xl (48) · text-metric-lg (36) · text-metric-md (30) · text-metric-sm (24) text-metric-delta — 12px semibold, tabular text-table-header — 11px uppercase, +0.06em, muted text-table-cell — 14px regular, tabular numerals

All metric and table utilities enable font-variant-numeric: tabular-nums so digits align in columns.

Code typography

text-code-inline — inline <code> with subtle chip background text-code-block — code fences and pre blocks text-code-sm — small mono captions text-kbd — keyboard shortcut chip

Numeric helpers

font-numeric-tabular · font-numeric-lining · font-numeric-slashed · font-feature-ligatures

7. Responsive typography

Two strategies, use both:

1. Fluid display — every text-display-* utility uses clamp() and scales continuously between the smallest phone and the largest desktop. Use these on hero surfaces. No breakpoint prefixes needed.

2. Stepped headings — for product UI, step the utility per breakpoint:

   <h1 className="text-heading-h2 md:text-heading-h1">Dashboard</h1>
         <p className="text-body-sm md:text-body-md">…</p>
         

Body text never scales fluidly — it scales in defined steps to preserve line length (measure). Target a measure of 60–75 characters (max-w-prose = 65ch).

8. Rules of use

1. Never write font-[…], text-[14px], or a hex color for text-*. Always use a token utility.
2. One h1 per page. Everything else steps down.
3. text-wrap: balance is already applied to headings via base styles; apply text-pretty to body paragraphs for cleaner rag.
4. Tabular numerals on every metric, price, count, timestamp, and table number column — either via the semantic utility or font-numeric-tabular.
5. Line-height 1 on any single-line control (button, badge, tag, nav item). Do not use larger line-heights for those.
6. Uppercase text needs tracking. Never uppercase without a +tracking-* utility — text-eyebrow, text-nav-section, text-table-header, and text-sidebar-section already include it.
7. Dark on dark, light on light — always render type over its intended surface token so contrast tokens carry through both themes.
8. Marketing uses Space Grotesk display; the product uses Inter. Do not mix the two on the same surface unless the layout is intentionally editorial.
9. Long-form reading — use text-body-md + leading-relaxed + max-w-prose. Never let a paragraph exceed 75 characters.

9. Implementation checklist

• --font-sans, --font-heading, --font-display, --font-mono tokens
• 14-step size scale with paired line-height + letter-spacing
• 9-step weight ladder
• 6-step leading + 7-step tracking ladders
• Fluid display utilities (clamp())
• Semantic role utilities (display, heading, body, label, caption, eyebrow, button, nav, sidebar, dashboard, code, kbd)
• Tabular numerals on data views
• Loaded via <link> in root route (never @import URL in CSS)
• Base styles: antialiasing, feature-settings, text-wrap: balance on headings

UI System Review — Foundation Ready

Audit of the shared UI foundation across design system, reusability, responsiveness, accessibility, dark mode, and enterprise SaaS standards. The UI infrastructure is complete and ready for business modules to build on top. No CRM / feature code has been added.

Scope reviewed

• src/styles.css — tokens, theme, motion, focus, print
• src/components/ui/* — shadcn primitives (46 components)
• src/shared/components/* — cross-app primitives
• src/shared/layouts/* — Auth, Dashboard, CRM, Inbox, Settings, Reports, Marketing, Automation, Admin, SuperAdmin shells + primitives
• src/shared/widgets/* — 18 dashboard widgets
• src/shared/forms/*, src/shared/tables/* — enterprise forms & tables
• src/shared/motion/* — Framer Motion presets, reduced-motion aware
• src/components/app/* — navigation shell (sidebar, top nav, command palette, notifications, breadcrumbs, FAB, mobile bottom nav, workspace switcher, recent/favorites)

Consistency scorecard

Components confirmed present

Forms: Button, Input, Textarea, Checkbox, Radio, Switch, Select, Slider, InputOTP, Label, Form (react-hook-form bridge), Autocomplete, SearchBox, DatePicker, DateRangePicker, FileDropzone, ImageDropzone, Wizard, AutosaveIndicator, FormBanner.

Overlays: Dialog, AlertDialog, Sheet, Drawer, Popover, HoverCard, DropdownMenu, ContextMenu, Menubar, Tooltip, Command (palette), SideDrawer, ConfirmDialog.

Structure: Card, Accordion, Tabs, Collapsible, Separator, ScrollArea, Resizable, AspectRatio, Table, Pagination, Breadcrumb, NavigationMenu, Sidebar, PageHeader, Section.

Feedback: Alert, Toast (Sonner via notify), Progress, Skeleton, Spinner, LoadingState, EmptyState, ErrorState, SuccessState, Timeline, Badge, StatusBadge.

Data: DataTable, ResponsiveDataView, DataCards, AdvancedFilters, BulkActionsBar, TableToolbar, Chart (recharts), ChartWidget.

Widgets: 18 reusable dashboard widgets (@/shared/widgets).

Added in this pass

Five enterprise-SaaS staples that were missing from the shared barrel:

• Kbd — keyboard shortcut chip (⌘ K) for menus / command palette hints
• CopyButton — icon + label variants, toast confirmation, 1.5s check state
• InfoTooltip — focusable, keyboard-accessible inline help affordance
• SegmentedControl — accessible radiogroup with arrow-key navigation
• LabeledDivider — "OR" / date-section separators for feeds and forms

All exported from @/shared/components.

How to consume

Every foundation piece is reachable from three barrels:

import { Button, Card, Dialog /* … shadcn */ } from "@/components/ui/…";
      import {
        ActionButton, CopyButton, Kbd, InfoTooltip, SegmentedControl,
        LabeledDivider, StatusBadge, PageHeader, DataTable, notify,
      } from "@/shared/components";
      import { DashboardLayout, CRMLayout /* … */ } from "@/shared/layouts";
      import { StatisticCard, ChartWidget /* … */ } from "@/shared/widgets";
      import { Wizard, FileDropzone } from "@/shared/forms";
      import { useTableControls, TableToolbar } from "@/shared/tables";
      import { PageTransition, HoverLift, DURATION } from "@/shared/motion";
      

Rules for business modules

1. Never introduce hex, text-white, bg-gray-*, or purple/indigo gradients. Use tokens.
2. Never rebuild a primitive that exists in @/shared/* or @/components/ui/* — extend via props, or add a variant to the shared source.
3. Every icon-only button needs aria-label.
4. Every table over ~6 columns must use ResponsiveDataView.
5. Every form with >1 step must use Wizard; every long form must use useAutosave + AutosaveIndicator.
6. Every dashboard tile must be a @/shared/widgets composition.
7. Route metadata (title, description, og:*) is required on every new page, per docs/architecture/ROUTING.md.

Foundation is complete. Business modules can begin.

TopAds · UI Development Standards

These standards make every screen feel like Stripe and Intercom: quiet confidence, tight typography, meaningful motion, obvious affordances, and zero rough edges. Every UI PR is reviewed against this document.

Prime directives

1. Use design tokens. Never hardcode hex, oklch, px shadows, or arbitrary durations.
2. Every interactive element has an accessible name, a visible focus state, and a keyboard path.
3. Every async surface has four states: loading, empty, error, success. All four ship at the same time.
4. Motion carries meaning. If it doesn't communicate causality, remove it.

1. Reusable components

Two-tier system, enforced by folder:

Rules:

• If a screen re-implements a pattern already in src/shared/components/, that is a review block.
• New primitives require a design-token entry — never a one-off literal.
• Every primitive has a matching TypeScript prop interface, forwardRef when it renders a DOM node, and stable data-* hooks for testing (data-slot, data-state).
• Composables are composed, not configured. Prefer <Card><Card.Header /><Card.Body /></Card> over a 20-prop config bag.

2. Accessibility (WCAG 2.2 AA is the floor)

• Semantic HTML first. Reach for <button>, <a>, <nav>, <main>, <header>, <footer>, <dialog> before adding ARIA. ARIA is a patch, not a foundation.
• One <main> per page. It lives in the layout that renders <Outlet />, never inside a page component.
• Landmarks. Every screen has header / nav / main / footer landmarks. Sidebar uses <nav aria-label="Primary">.
• Alt text. Every <img> has alt. Decorative images use alt="". Icons that repeat visible text use aria-hidden.
• Never aria-hidden="true" on a container with focusable children.
• Never onClick on <div>. If a <button> is not right, use <a>.
• Live regions for async status: aria-live="polite" on the toaster, "saved" ticks, and inline validation summaries.
• Contrast. Use text-foreground / text-muted-foreground. Never text-muted-foreground/50 (drops below 4.5:1).
• Icon-only buttons always have aria-label.
• Skip link — the app shell must include <a href="#main" class="sr-only focus:not-sr-only">Skip to content</a>.

3. Keyboard navigation

• Tab order matches visual order. Never tabIndex > 0.
• Every interactive element is reachable and operable with keyboard only.
• Focus is never lost. After a modal closes, focus returns to the trigger. After a drawer closes, focus returns to the row that opened it.
• Global shortcuts (registered in LayoutProvider):
  • ⌘K / Ctrl+K — command palette
  • ⌘/ — keyboard shortcuts help
  • g d, g i, g c, g a — go to Dashboard / Inbox / Contacts / AI Studio
  • ? — help
  • Esc — close topmost overlay
• In lists / tables: ↑ ↓ moves selection, Enter activates, Space toggles selection, ⌘A selects all, Del opens confirm delete.
• In dialogs: Esc closes; focus is trapped inside; the first focusable element receives focus after the transition ends.

4. ARIA labels

• Icon-only trigger → aria-label describing the action ("Open notifications", not "Bell").
• Grouped controls → role="group" + aria-labelledby.
• Custom widgets (segmented controls, kanban columns) → the matching Radix primitive rather than hand-rolled ARIA.
• Toggle buttons → aria-pressed. Expandable → aria-expanded + aria-controls.
• Sort headers → aria-sort="ascending" | "descending" | "none".
• Errors → the field's aria-describedby points at the message; aria-invalid="true" when appropriate.

5. Responsive design (mobile-first)

Breakpoints match --breakpoint-* tokens:

Rules:

• Mobile-first. Author base styles for mobile; add md:/lg: for larger surfaces.
• Tap targets ≥ 44×44. size="icon" shadcn buttons get min-h-11 min-w-11 for primary tap targets.
• Content max width — page content maxes at container-app (1440), long-form text at container-prose (65ch).
• Grids collapse gracefully: grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4. Never rely on fixed columns.
• Header rows with mixed content use grid-cols-[minmax(0,1fr)_auto] + min-w-0 on text; flex flex-wrap alone clips on narrow screens.
• Full-height layouts use min-h-dvh and h-dvh, never h-screen (iOS URL bar bug).

6. Loading skeletons

• Skeleton matches the shape it replaces — same width, height, radius, gap.
• Use <Skeleton> from src/shared/components/skeleton.tsx. Never build ad-hoc <div class="animate-pulse bg-muted">.
• Threshold: show a skeleton only when the wait is > 200 ms (React Suspense + delayed transition). Under 200 ms → don't show anything; the flicker is worse than the wait.
• Never show a spinner and a skeleton together.
• Skeletons announce nothing to AT users. Provide a matching <span className="sr-only" role="status">Loading…</span> when the surface is the whole page.

7. Empty states

Every list, table, and container that can be empty ships an <EmptyState>. Structure:

1. Illustrative icon (single, monochrome, 32-40 px).
2. Sentence-case headline naming the missing thing ("No campaigns yet").
3. One-line description explaining why and what next.
4. One primary CTA. Optional secondary "Learn more".

Do not show empty states for filter results — use a smaller <EmptyState variant="filter"> that offers "Clear filters".

8. Error states

Two layers:

1. Inline — a form field or row-level failure. Use the field's error slot; describe what went wrong and how to fix it.
2. Boundary — a whole surface failed. Use <ErrorState> with a specific message ("We couldn't load your inbox"), a retry button, and a support link.

Rules:

• Never show a raw error message. Map errors to user-facing copy via mapError() in src/shared/utils/errors.ts.
• Retry re-runs the loader (router.invalidate() + reset()), does not just clear the boundary.
• Log the raw error to the monitoring service before replacing it with copy.

9. Success states

• Toast (top-right) for background actions. Auto-dismiss 4 s. Never for destructive undo (use action toast, 8 s).
• Inline saved state for forms — a subtle green check that fades after 2 s.
• Full-page <SuccessState> only after a multi-step wizard completes; always includes the next step CTA.
• Optimistic updates: apply UI change immediately, roll back on error with an action toast ("Couldn't save. Try again.").

10. Micro animations

Only these primitives, all from src/styles.css:

Do not add ad-hoc @keyframes. Extend the token system in styles.css under @theme.

11. Hover effects

• Buttons — 8 % darker background OR hover:shadow-md. Never both.
• Cards — hover:border-border-strong hover:-translate-y-0.5 transition-all duration-normal ease-emphasized. Only for clickable cards.
• Rows — hover:bg-muted/60. Not hover:bg-accent (reserved for selection).
• Icons — never grow on hover in body copy. Reserved for CTAs (hover-scale).
• Links — story-link underline animation for editorial contexts. In app chrome, use text-foreground on hover, no underline.
• Every hover has a keyboard-equivalent focus-visible state. If you can hover it, you can Tab to it.

12. Focus effects

• Use the focus-ring utility: 2 px outline in var(--ring) + 4 px ambient glow at 25 % opacity.
• Never outline-none without a replacement. If truly needed, use outline-hidden (Tailwind v4) which preserves forced-colors mode.
• shadcn primitives already ship focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2. Extend, don't replace.
• Focus is :focus-visible-scoped so mouse clicks don't trigger the halo.

13. Motion guidelines

Meaningful motion only. Follow these rules per interaction:

Rules:

• Respect prefers-reduced-motion — already handled globally in styles.css.
• Enter animation is longer than exit; users judge exit as a delay.
• No parallax, no scroll-jack, no auto-carousel over 5 s.
• Never animate top / left / width / height — only transform and opacity.
• Stagger children by 30 – 60 ms; never over 100 ms.
• Feature-heavy motion (Kanban drag, chart tooltips) uses motion/react (Framer Motion). Everything else uses CSS.

14. Modal guidelines (Dialog)

Use shadcn's Dialog (Radix).

• When: irreversible confirmation, focused single task (< 30 s), critical announcement.
• Never: for navigation, for content the user needs alongside a page.
• Structure: Title (verb, sentence case), 1-line Description, form body, footer with Cancel (secondary) on the left and the primary action on the right.
• Destructive confirmations use variant="destructive" on the primary button and re-state the noun ("Delete campaign 'Spring promo'?").
• Width: max container-lg (32 rem). Larger surfaces should be drawers or pages.
• Focus: first focusable element gets focus after the entrance animation. Focus returns to the trigger on close.
• Escape: Esc closes unless the form is dirty — then confirm.
• Async: the primary button shows a spinner while the action runs; the whole dialog stays open. Never close-then-toast, close only on success.

15. Drawer guidelines (Sheet)

Use shadcn's Sheet (Radix Dialog with side transform).

• When: contextual details for a selected row, secondary navigation, filter panels, mobile nav.
• Side: right for details ("Contact detail"), left for navigation.
• Width: w-full sm:max-w-md lg:max-w-lg. Never wider than half the viewport on desktop.
• The drawer has its own scroll region — never nest the app scroll inside it.
• Include a sticky header (title + close) and, when actions exist, a sticky footer with a solid background so it survives long scroll content.
• On mobile: full-width, side="bottom" for filter/quick-action drawers.
• Selection state on the parent list is preserved while the drawer is open.

16. Table guidelines

Use <DataTable> from src/shared/components/data-table.tsx.

• Column widths are declared explicitly; text truncates with .truncate, numeric aligns right with text-tabular-nums.
• Sort headers use aria-sort and a directional caret. Only one column at a time.
• Selection — checkbox in the first column, master toggle in the header. Selected rows get bg-accent-muted.
• Bulk actions — appear in a floating action bar above the table, not below.
• Pagination — 25 / 50 / 100 page sizes; footer shows "1–25 of 1,284". Cursor-based on the server.
• Empty, loading (skeleton rows), error states are all handled by <DataTable>, never re-implemented.
• Density — default. A size="compact" variant is available for admin tables.
• Row height is fixed to preserve rhythm; do not put multi-line content in cells — open a drawer.

17. Form guidelines

Use react-hook-form + zod for every form. Compose fields with <FormField> from src/shared/components/form-field.tsx.

• Label always visible; placeholders are hints, not labels.
• Description below the label explains constraints; error replaces the description on invalid input.
• Grouping: 1 column on mobile; 2 columns for balanced short fields on desktop.
• Submit disabled until the form is isValid; button shows a spinner while submitting; entire form is disabled during submit.
• Validation on blur, not on change. Re-validate on change after first error.
• Autofocus the first field on load only when the form is the entire page task; never inside a scrolled area.
• Autocomplete attributes are mandatory (name, email, new-password, one-time-code, off).
• Async validation — debounce 300 ms; show a subtle spinner in the field's suffix.
• Multi-step wizards persist form state in the URL search params so refresh doesn't wipe progress.

18. Dashboard guidelines

• 12-column grid on desktop, 2-column on tablet, 1-column on mobile. Gaps gap-6 desktop, gap-4 mobile.
• KPI cards (<StatCard>) — 4 across at lg, 2 across at sm. Each shows metric, label, delta with directional arrow + color.
• Deltas: green text-success for positive, red text-danger for negative on "good-when-up" metrics. Invert for "good-when-down" (churn, response time). Include the timeframe ("vs last 7d") always.
• Every chart uses the semantic chart palette chart-1..chart-8. No custom hexes.
• Charts render skeletons that mirror their shape; empty states show a stub line at zero with an explanation.
• Cards are bg-surface border border-border rounded-xl shadow-sm p-5.
• Above the fold on a 1440 desktop must contain: KPIs + one primary chart + one activity list. Nothing else.
• Filter bar (date range, workspace, segment) is sticky under the topbar on scroll.

Review checklist

Before shipping a UI change:

• All colors, shadows, spacing, radii, fonts come from tokens.
• Every interactive element has an accessible name and visible focus state.
• Keyboard: Tab, Enter, Esc, arrow keys all work.
• Loading, empty, error, success states are all wired.
• Motion respects prefers-reduced-motion.
• Layout survives 320 px and 2560 px.
• No h-screen, no text-*/50 on light backgrounds, no arbitrary hexes, no onClick on div.
• No hardcoded strings that will need i18n later — route through t() if the project has i18n.

Backend Audit — TopAds (Lovable Cloud / Postgres)

Date: 2026-07-27 Scope: schema (288 public tables), indexes, RLS, functions/triggers, extensions, edge functions, realtime, migrations, runtime hot paths.

Database health snapshot

The rolled-back count is the standout. It's cumulative, not a rate — but at that magnitude it indicates a hot path that constantly hits a conflict or a denied-by-RLS insert (webhook idempotency retries, outbox claim races, or client writes stopped by RLS WITH CHECK). Worth tracing once the priority- 1 items below are in.

Findings by priority

P1 — Real security weakness (fix)

plugin_downloads INSERT is unauthenticated-in-effect. Policy Anyone signed in logs downloads is FOR INSERT TO authenticated WITH CHECK (true). Any signed-in user can log a download for any user_id, plugin_id, or spoof download counts (which feed recompute_plugin_installs / recompute_plugin_rating). Scope to user_id = auth.uid().

P1 — Function search_path mutable (fix)

Five plpgsql helpers do not pin search_path, which lets a malicious same-schema object shadow calls to now(), pg_catalog.*, etc. All are trigger functions and safe to lock down:

• public.touch_updated_at()
• public.ai_settings_touch()
• public.kb_articles_tsv_update()
• public.set_updated_at()
• public.enforce_single_default_ai_provider()

P2 — SECURITY DEFINER functions callable by anon (fix)

The Data API exposes every EXECUTE-to-anon function as a public POST endpoint. Most of the ~40 SECURITY DEFINER functions in public are legitimately anon-callable (RLS helpers such as has_role, has_permission, is_workspace_member, is_org_member, is_inbox_member, is_super_admin — RLS policies depend on them). The following should NOT be reachable without a session — they are cron/worker/internal helpers:

_wa_cron_post(text, jsonb)
      run_retention_policies()
      outbox_claim_batch(text, int)
      export_jobs_claim_batch(text, int)
      dispatch_notification_push()
      seed_default_ai_provider()
      cleanup_rate_limit_buckets()
      cleanup_whatsapp_qr_sessions()
      claim_expired_media(int)
      recompute_plugin_installs()
      recompute_plugin_rating()
      increment_webhook_failure(uuid)
      enforce_rate_limit(text, int, int, uuid)
      mark_media_accessed(uuid, text)
      log_security_event(uuid, text, text, text, text, jsonb)
      next_document_number(uuid, text)
      assign_ticket_number()
      

Revoke EXECUTE from PUBLIC and anon; keep service_role (and authenticated for any the app truly needs). pg_cron / edge functions run as service_role, so cron jobs keep working.

P2 — Overly-permissive write policy (noise, not a leak)

rate_limit_buckets.service manages rate limits is ALL USING(true) WITH CHECK(true) TO service_role. service_role already bypasses RLS, so this policy grants nothing extra. Not a security issue; the linter flags the true predicate shape. Optional cleanup: drop the policy and rely on the role-based bypass.

P2 — Client hot paths pulling entire tables (client bug)

Top-2 offenders in pg_stat_statements:

1843 calls  SELECT organizations.* FROM organizations ORDER BY created_at ASC LIMIT ? OFFSET ?
      2043 calls  SELECT workspaces.*    FROM workspaces    ORDER BY created_at ASC LIMIT ? OFFSET ?
      

These are unfiltered .from('workspaces').select('*').order('created_at') calls from the client — no workspace_id / member filter, no column projection. Response times are fine today (~4ms) because both tables are tiny, but this is O(N) per request and will degrade as tenants grow. Action: in the client hooks that load workspaces/organizations, filter to the current user's memberships and project only needed columns.

P3 — Missing indexes on foreign keys

pg_constraint shows 150+ FK columns with no supporting index across almost every domain (billing_*, booking_*, chatbot_*, commerce_*, campaign_*, bi_*, ticket_*, wa_*, plugin_*, workflow_*, message_*, etc). Impact today is low because rows/table are small; impact grows with tenant data. Batch-add btree indexes on the highest-write / cascading-delete FKs first (a few examples):

addresses(workspace_id)
      attachments(workspace_id), attachments(attached_by)
      campaign_dispatch_queue(workspace_id, recipient_id, contact_id, variant_id)
      campaigns(created_by, contact_list_id, segment_id, template_id)
      commerce_cart_items(cart_id, product_id)
      commerce_order_items(product_id)
      commerce_orders(cart_id, conversation_id)
      communications(organization_id, performed_by)
      companies(created_by, organization_id)
      booking_appointments(event_type_id, reschedule_of)
      booking_reminders(appointment_id, rule_id, template_id)
      

Full list is in the queued migration below (behind approval so the DBA can prune).

P3 — Extensions installed in public

pg_trgm, pg_net, vector, btree_gist all live in public. Standard Supabase warning. Moving them requires re-typing every dependent column (vector, tsvector) and is disruptive. Recommendation: accept.

P4 — RLS enabled without policies (deny-all, intentional)

5 tables: messenger_oauth_states, webhook_endpoint_secrets, instagram_oauth_states, oauth_refresh_tokens, oauth_authorization_codes. All are internal / OAuth secrets touched only by service_role in edge functions. Deny-all-to-users is correct. No action.

P4 — RLS coverage

Every user-facing table has RLS enabled (spot-checked against pg_class). No table returned in a "RLS disabled with public grants" query. Good baseline.

Storage / Realtime / Edge Functions / Migrations

• Storage / Realtime / auth schemas: not touched (managed by Supabase, per agent rules). No changes required.
• Edge Functions: existing set continues to deploy; policy for this stack is "maintain only, no new". provider_logs / ai_audit_logs show ingest, suggesting logs are wired. Nothing to fix from the schema side.
• Migrations: no broken/half-applied migrations detected — schema is internally consistent (all FKs resolve, no orphaned RLS policies referencing missing columns).

Recommended migration (needs your approval)

Below is the safe, minimal migration that addresses P1 + P2:

-- 1) Tighten plugin_downloads INSERT
      DROP POLICY IF EXISTS "Anyone signed in logs downloads" ON public.plugin_downloads;
      CREATE POLICY "Users log their own downloads"
        ON public.plugin_downloads FOR INSERT TO authenticated
        WITH CHECK (user_id = auth.uid());

      -- 2) Pin search_path on user trigger functions
      ALTER FUNCTION public.touch_updated_at()              SET search_path = public;
      ALTER FUNCTION public.ai_settings_touch()             SET search_path = public;
      ALTER FUNCTION public.kb_articles_tsv_update()        SET search_path = public;
      ALTER FUNCTION public.set_updated_at()                SET search_path = public;
      ALTER FUNCTION public.enforce_single_default_ai_provider() SET search_path = public;

      -- 3) Lock cron/worker SECURITY DEFINER helpers to service_role
      REVOKE EXECUTE ON FUNCTION public._wa_cron_post(text, jsonb)              FROM PUBLIC, anon, authenticated;
      REVOKE EXECUTE ON FUNCTION public.run_retention_policies()                FROM PUBLIC, anon, authenticated;
      REVOKE EXECUTE ON FUNCTION public.outbox_claim_batch(text, integer)       FROM PUBLIC, anon, authenticated;
      REVOKE EXECUTE ON FUNCTION public.export_jobs_claim_batch(text, integer)  FROM PUBLIC, anon, authenticated;
      REVOKE EXECUTE ON FUNCTION public.dispatch_notification_push()            FROM PUBLIC, anon, authenticated;
      REVOKE EXECUTE ON FUNCTION public.seed_default_ai_provider()              FROM PUBLIC, anon, authenticated;
      REVOKE EXECUTE ON FUNCTION public.cleanup_rate_limit_buckets()            FROM PUBLIC, anon, authenticated;
      REVOKE EXECUTE ON FUNCTION public.cleanup_whatsapp_qr_sessions()          FROM PUBLIC, anon, authenticated;
      REVOKE EXECUTE ON FUNCTION public.claim_expired_media(integer)            FROM PUBLIC, anon, authenticated;
      REVOKE EXECUTE ON FUNCTION public.recompute_plugin_installs()             FROM PUBLIC, anon, authenticated;
      REVOKE EXECUTE ON FUNCTION public.recompute_plugin_rating()               FROM PUBLIC, anon, authenticated;
      REVOKE EXECUTE ON FUNCTION public.increment_webhook_failure(uuid)         FROM PUBLIC, anon, authenticated;
      REVOKE EXECUTE ON FUNCTION public.enforce_rate_limit(text, integer, integer, uuid) FROM PUBLIC, anon, authenticated;
      -- (Kept anon-executable: has_role, has_permission, is_workspace_member,
      --  is_org_member, is_inbox_member, is_super_admin — required by RLS.)
      

An index migration (P3) is deferred until you say which subsystem to target first (billing? chatbot? commerce?) — 150+ indexes at once is more churn than this DB needs today.

What I did NOT change

• Did not apply any migration — production DB is unchanged.
• Did not touch auth, storage, realtime, supabase_functions, vault schemas (managed by Supabase).
• Did not modify extensions or their placement in public.
• Did not alter client hooks (the workspaces/organizations select-all is a frontend concern; happy to fix on request).

Payment Gateway Webhooks

Endpoint: POST /api/public/webhooks/billing/:provider (:provider = stripe | paddle)

Configure in the gateway dashboard:

• Stripe → https://<your-domain>/api/public/webhooks/billing/stripe
• Paddle → https://<your-domain>/api/public/webhooks/billing/paddle

Secrets (per gateway): STRIPE_WEBHOOK_SECRET, PADDLE_WEBHOOK_SECRET, plus STRIPE_SECRET_KEY / PADDLE_API_KEY (+ optional PADDLE_ENV=live) for snapshot refresh after a renewal charge.

Pipeline

1. Verify signature — provider adapter (src/lib/billing/providers/*). Stripe: t=…,v1=… HMAC over t.body. Paddle: ts=…;h1=… HMAC over ts:body with a 5-minute replay window. Failure → 401, no side effects.
2. Deduplicate — billing_events (provider, provider_event_id). Redelivery returns 200 {dedup:true}.
3. Persist raw event to billing_events.
4. Normalize — src/lib/billing/webhook-normalize.server.ts maps the provider object to a canonical SubscriptionSnapshot or payment record and resolves:
   • organization_id: event metadata → billing_customers → existing subscriptions.provider_subscription_id
   • internal plan_code: plan_gateway_prices.external_price_id (then external_product_id, then a literal plan-code match) → plans.code
5. Route — src/lib/billing/webhook-router.server.ts applies side effects.
6. Log delivery to payment_gateway_webhook_deliveries (status, latency, signature result) for the Super Admin health panel.

Unresolvable events (unknown org, unmapped price) are ack'ed 200 and marked ignored: <reason> in billing_events.error — providers must not retry these forever. Real processing failures return 400 so the gateway retries.

Handled events

Status mapping into subscription_status: Stripe unpaid → past_due, incomplete_expired → incomplete; Paddle cancelled → canceled.

Cancellations: cancel_at is set for scheduled (end-of-period) cancels; status = canceled + canceled_at when the gateway terminates the subscription.

Replay

Super Admin → Payment Gateways → webhook health can replay failed deliveries. Replay calls the same routeProviderEvent, so behaviour is identical to a live delivery.

Appointment Booking — Enterprise Architecture

TopAds's scheduling stack is designed for multi-tenant SaaS, real-time updates, high write throughput, timezone correctness, and clean integration with the AI, Workflow, and Omnichannel platforms.

Module Map

Data Model

9 tables, all workspace_id-scoped with RLS + explicit GRANTs.

booking_event_types ── booking_event_type_hosts ─┬─> booking_appointments
                                                       │       │
      booking_availability_schedules                   │       └─> booking_reminders
         └── booking_availability_slots                │
      booking_availability_overrides ──────────────────┘
      booking_pages · booking_waitlist
      

Double-booking is a database-level impossibility, enforced by EXCLUDE USING gist (host_id WITH =, tstzrange(start_at, end_at, '[)') WITH &&) scoped to status IN ('pending','confirmed'). Concurrent writes race harmlessly: one INSERT wins with 201, the other gets 409 slot_taken.

Request Lifecycle — Public Booking

POST /api/public/booking/book
        ├─ Zod validate + resolve event_type by id or slug
        ├─ Load hosts + strategy + 7d load counts
        ├─ Filter hosts busy at [start_at, end_at)   -> eligible[]
        ├─ selectHost(strategy, eligible, loads)     -> host_id
        ├─ provisionMeeting(location_kind)           -> { join_url, external_ids }
        ├─ INSERT booking_appointments               -> gist gate or 201
        └─ (async) schedule reminders + fire workflow trigger
      

Every step is stateless. Horizontal scale = spin up more Workers.

Availability Engine

Pure function computeAvailability({schedule, overrides, existing, event_type, from, to, tz}):

1. Enumerate candidate windows from weekly booking_availability_slots.
2. Subtract is_blocked=true overrides.
3. Union is_blocked=false overrides (ad-hoc availability).
4. Subtract booking_appointments (pending + confirmed) with buffers applied.
5. Slice into duration_minutes slots respecting min_notice_minutes and max_advance_days.
6. dedupeSlotsByStart() removes duplicates when multiple hosts collide.

Timezone handling: schedules store times in the host's IANA timezone; the engine converts every window into UTC before intersection. The public booking page renders slots in the visitor's browser timezone using the same UTC anchor.

Round Robin & Team Scheduling

selectHost({ strategy, hosts, loads, eligibleHostIds, preferredHostId }):

• round_robin — fewest bookings in last 7 days wins; ties → priority → oldest.
• priority — lowest priority int.
• random — uniform over eligible hosts.
• collective — primary owner = highest priority; caller writes attendees.
• specific — caller passes preferredHostId.

Busy hosts are filtered out before the strategy runs, so no strategy can produce a colliding booking (belt-and-suspenders alongside the gist gate).

Meeting Provider Layer

Every provider satisfies the same interface:

interface MeetingProvider {
        kind: MeetingLocationKind;
        createMeeting(a: AppointmentDraft): Promise<MeetingArtifact>;
        cancelMeeting?(external_ids: Record<string, string>): Promise<void>;
      }
      

Ships with in_person, phone, whatsapp, custom, zoom, google_meet, microsoft_teams. The OAuth-backed providers currently return deterministic placeholder URLs — swap for real Zoom/Meet/Teams API calls behind the same interface once the workspace links the connector; no booking-engine change required.

Calendar Sync

getCalendarProviderForHost(host_id) resolves a CalendarSyncProvider that can list busy blocks and push events. The default noopSync returns empty busy blocks and no-op push, so the engine works without any linked calendar. Real Google Calendar / Outlook adapters plug in via the App User Connector flow, and the availability engine automatically consumes their listBusy() output on the next slot computation.

Reminder Engine

Reminders live in booking_reminders with send_at, channel, status. The tick endpoint claims a batch of queued rows whose send_at has elapsed, hands each off to the appropriate outbox (message_outbox for email/WhatsApp/SMS), and marks them sent or leaves them queued with last_error for retry.

Schedule via pg_cron:

SELECT cron.schedule(
        'booking-reminders-tick',
        '* * * * *',
        $ SELECT net.http_post(
             url := 'https://project--<project-id>.lovable.app/api/public/booking/reminders-tick',
             headers := '{"Content-Type":"application/json","apikey":"<anon-key>"}'::jsonb,
             body := '{}'::jsonb
           ); $
      );
      

AI Integration

Three tools exposed to the AI Conversation Engine:

• list_meeting_slots({ event_type_slug, from_date?, days? }) — returns the availability window and existing bookings so the LLM can propose times.
• book_meeting({ event_type_id, start_at, end_at, customer_* }) — creates a real confirmed appointment, respecting round-robin and conflict rules.
• cancel_meeting({ appointment_id, reason? }).

Every tool call is audit-logged to ai_tool_executions. RLS scopes the underlying queries to the caller's workspace.

Workflow Integration

Registered in NODE_REGISTRY:

• Triggers: trigger.booking.created, trigger.booking.cancelled, trigger.booking.rescheduled, trigger.booking.no_show.
• Actions: action.booking.create, action.booking.cancel, action.booking.send_link.

Triggers fire from the booking engine after successful state transitions (via workflow_queue inserts by the same server function), so any authored automation — "on booking, send WhatsApp confirmation, wait 24 h, send reminder, wait 1 h, escalate to CSM" — composes with the rest of the platform.

Realtime

Realtime is enabled on booking_appointments and booking_reminders. The admin dashboard subscribes on mount to reflect new bookings, cancellations, and reminder deliveries within seconds without polling.

Multi-tenancy & Security

• Every table has workspace_id NOT NULL and RLS restricting reads/writes to is_workspace_member(workspace_id, auth.uid()).
• Explicit GRANTs on every public-schema table.
• manage_token is a per-appointment nonce for anonymous reschedule/cancel links — the token is the only auth for the public manage endpoint.
• Public API validates every payload with Zod before hitting the DB.
• The public booking page renders no PII from other workspaces; slot lookup is anon-safe because the query only sees the event type by id/slug.

Scaling Notes

• Availability computation is pure and cache-friendly (key: event_type_id + date window + host set version). Cache in Cloud KV or bi_metric_cache when hot event types dominate traffic.
• The gist exclusion constraint makes the DB the single source of truth for conflicts — no distributed lock needed.
• Reminder tick is idempotent and horizontally-safe (atomic claim via status='queued' -> 'sending').
• Booking pages and slot lookups are anon and cacheable at the CDN edge with a short TTL (Cache-Control: public, max-age=30, s-maxage=30).

Roadmap Slots (interface-ready)

• Real Zoom / Google Meet / Microsoft Teams API calls behind the existing MeetingProvider interface.
• Real Google Calendar / Outlook busy-block ingest behind CalendarSyncProvider.
• Team availability intersection for collective strategy.
• Payment-gated bookings (Stripe intent held until confirmation).
• iCal (.ics) attachment on confirmation emails.

Appointment Booking & Scheduling — Phase 19

Calendly / Cal.com-class scheduling built into TopAds.

Surfaces

• Admin dashboard — /booking with four tabs: Overview (KPIs + upcoming), Meeting types (CRUD + share links), Availability (weekly schedule editor), Appointments (list, filter, cancel, no-show, reschedule).
• Public booking page — /book/$slug with month picker, timezone-aware slot grid, customer form, instant confirmation.
• Public API — under /api/public/booking/*:
  • GET /slots?event_type_id=...&from=&to= (or slug=)
  • POST /book — creates the appointment

Data model

Guarantees

• No double booking: a database-level EXCLUDE USING gist (host_id, tstzrange(start_at,end_at)) constraint on booking_appointments rejects overlapping active bookings for the same host.
• Timezone-safe: all persisted times are UTC; customer timezone is captured and used for display.
• RLS: workspace members see their workspace's data. Anonymous users can read only active event types and pages, and can create bookings solely through the public POST route (which uses supabaseAdmin after validating the event type).
• Realtime: booking_appointments and booking_reminders publish on supabase_realtime.

Availability engine (src/lib/booking/availability-engine.server.ts)

Pure function that:

1. Loads the event type + associated hosts and schedules.
2. Applies min-notice and max-advance bounds to the requested window.
3. Loads per-host date overrides and existing pending/confirmed bookings.
4. Iterates day-by-day, slices weekly hours into duration-sized slots, subtracts buffers + busy time, and outputs {host_id, start_at, end_at} list.
5. dedupeSlotsByStart collapses per-host slots into a single per-time offering for round-robin.

Public booking flow

Customer opens /book/$slug
        → GET /api/public/booking/slots (via anon publishable key)
        → picks time, fills form
        → POST /api/public/booking/book
            • re-validates event type via supabaseAdmin
            • inserts booking; gist exclusion prevents race
        → confirmation screen
      

Next-phase extensions

• Calendar sync (Google / Outlook via App User Connectors) — calendar-sync.server.ts.
• Reminder cron (pg_cron → /api/public/hooks/booking-reminders) dispatching through the omnichannel send router.
• AI Assistant tools list_available_slots / book_appointment in src/lib/ai/tools/.
• Workflow builder booking.* triggers.
• Live Chat widget openBooking(slug) runtime API.
• Analytics tab (Recharts) for source channels, host performance, no-show funnel.

Button component — variant rules

Source of truth: src/components/ui/button.tsx (variant list) and src/styles.css (semantic tokens + @utility btn-hero-ghost). Visual regression: /dev/buttons + tests/e2e/buttons-visual.spec.ts.

Do not hardcode colors, opacities, or transition durations in variant class lists. Route styling through semantic tokens (--primary, --accent, --muted, --hero-*) and shared motion tokens (--duration-normal, --ease-out). Never use bg-white/20, bg-white/90, border-white/20, or similar raw-opacity utilities inside a Button variant — those bypass theming and drift over time.

Shared behavior (all variants)

• Cursor: pointer at rest, not-allowed when disabled.
• Motion: control-motion utility (transition on color/bg/border/shadow/transform using --duration-normal + --ease-out, adds --shadow-md on hover, no vertical lift). Reuse this utility on any new interactive primitive instead of hand-rolling transition-* / hover:-translate-* classes.
• Icons: [&_svg]:size-4 (no hover translate).
• Focus: focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 (heroGhost overrides this with --hero-ring / --hero-ring-offset).
• Disabled: opacity-50, no pointer events, no hover lift.

Variant color rules

heroGhost — dark hero / gradient surface

Ghost button designed for the fixed dark hero gradient. Implemented as the single @utility btn-hero-ghost in src/styles.css; the Button variant is just heroGhost: "btn-hero-ghost". Do not inline the Tailwind class cluster back into the variant.

Rules (must stay consistent):

• Rest: transparent background, --hero-foreground text, 1px border in --hero-border.
• Hover: solid --hero-surface background (opaque white — never bg-white/20 or bg-white/90), --primary text, border matches surface.
• Active: same solid --hero-surface background, --primary text. Hover and active share the same fill and text color by design.
• Focus-visible: double ring using --hero-ring-offset (inner) and --hero-ring (outer). Do not fall back to the default --ring.
• Motion: transitions use --duration-normal and --ease-out. The shared vertical lift / shadow / icon slide from the base class apply unchanged.

Tokens (defined for both light and dark themes in src/styles.css):

--hero-foreground        text at rest
      --hero-foreground-muted  secondary hero text (not used by button)
      --hero-border            resting border
      --hero-border-strong     reserved for emphasized hero borders
      --hero-surface           solid fill for hover + active (opaque white)
      --hero-ring              focus ring outer color
      --hero-ring-offset       focus ring inner/offset color
      

If a new hero-surface state is needed (e.g. a pressed-darker fill), add a new token — do not introduce a raw bg-white/NN utility.

Adding or changing a variant

1. Edit the variant string in src/components/ui/button.tsx, or, for token-driven variants like heroGhost, edit the @utility block in src/styles.css.
2. If new colors are needed, add semantic tokens (--*) in both :root and .dark in src/styles.css. Never hardcode hex / oklch / rgb values in the component.
3. Update the table above.
4. Run the checks in the next section.

Verification

# Enforce variant uniformity (shared base classes, no forbidden literals).
      node scripts/check-button-uniformity.mjs

      # Enforce forbidden font-feature-settings (unrelated but part of prebuild).
      node scripts/check-forbidden-font-features.mjs

      # Unit test — variant shape.
      bunx vitest run tests/unit/button-uniformity.test.ts

      # Visual regression across variants × states × themes.
      bunx playwright test tests/e2e/buttons-visual.spec.ts
      

Update baselines only when the change is intentional and the diff has been reviewed.

TopAds — CodeCanyon Feature Bullets

Ready-to-paste feature bullets for the CodeCanyon listing. Use the short list for the top of the page and the grouped list for the full description.

Short bullet list (for the fold/hero area)

• Multi-tenant WhatsApp CRM with workspace isolation
• Unified Omnichannel Inbox (WhatsApp, Instagram, Messenger, Telegram, Email, SMS, Live Chat)
• Visual no-code Workflow & Automation builder
• AI Reply Assistant, RAG Knowledge Base, and AI Chatbot Builder
• Sales CRM with pipelines, deals, quotes, and invoices
• Marketing campaigns, broadcasts, A/B testing, and drip sequences
• WhatsApp Commerce: catalog, orders, payment links, promotions
• Client Portal, Helpdesk, SLAs, and appointment booking
• White-label branding, PWA, and Super Admin dashboard
• REST API, webhooks, SDKs, and Developer Center

Grouped feature bullets (for the full description)

Core Platform

• Multi-tenant SaaS architecture with isolated data per workspace
• 7 role-based permission levels (Owner, Admin, Manager, Agent, Sales, Marketer, Developer)
• Row-Level Security (RLS) on every database table
• Full audit logging and immutable security events
• TOTP 2FA, password policies, breach detection, and session pinning
• HMAC-signed webhooks and API rate limiting
• White-label branding per workspace (logo, colors, domain, email sender)
• Progressive Web App (PWA) with installable experience and push notifications
• Super Admin dashboard for tenant, plan, and platform health management
• Developer Center with REST API, OAuth, tokens, and API explorer

Omnichannel Inbox

• Unified inbox for WhatsApp, Instagram, Messenger, Telegram, Email, SMS, and Live Chat
• Real-time conversation updates via Supabase Realtime
• Search, filters, date ranges, unread toggle, and bulk actions
• Star, pin, resolve, archive, and assign with keyboard shortcuts
• Message status indicators: sending, delivered, read, failed
• Retry and discard controls for failed messages
• Attachments, media previews, thumbnails, and upload progress
• Persistent conversation read state across devices and sessions

WhatsApp Cloud API

• Official Meta WhatsApp Cloud API integration
• WABA (WhatsApp Business Account) management
• Message templates library with CRUD, drafts, and approval status
• 6-step template wizard with header, body, footer, buttons, and variables
• Secure inbound webhook processing with HMAC-SHA256 verification
• Auto-reply engine for inbound WhatsApp messages
• E.164 phone normalization and configurable contact matching rules
• Bulk contact re-matching and conversation re-linking
• WhatsApp Commerce catalog sync and product collections
• Media upload, download, and CDN-ready re-hosting

CRM & Sales

• Contact and company management with custom fields, tags, and notes
• Customer activity timeline and engagement metrics
• AI-generated customer insights and summary
• Sales pipelines with Kanban board, deal stages, and forecasting
• Quotes, invoices, and order management
• Duplicate, soft-delete, and restore-from-trash flows
• Lead scoring and AI sales assistant
• Tasks and reminders with due-date notifications

Marketing

• Campaign wizard with segmentation, templates, and scheduling
• Broadcast campaigns with enqueue, pause, resume, and cancel
• A/B testing, drip sequences, and delivery analytics
• Append recipients to running or scheduled campaigns without duplicates
• Campaign performance dashboard

Automation & Workflows

• Visual no-code workflow builder (React Flow)
• Pre-built omnichannel trigger, action, delay, and condition nodes
• Async duplicate-name validation before workflow creation
• Execution ceilings, reliability dashboard, and error recovery
• Chatbot lifecycle webhooks with delivery logs
• Routing rule tester with sample contact simulation

AI & Chatbots

• AI provider engine with multiple provider support
• AI reply assistant and conversation intelligence
• RAG-powered Knowledge Base with pgvector and document collections
• Visual chatbot builder with marketplace templates
• 3-step install flow with permissions, workspace selection, and diff preview
• Real-time test chat immediately after creation
• Soft-delete, trash, restore, and bulk actions
• Role-based chatbot permissions

Client Portal & Widgets

• Embeddable live chat widget (420×600px) with minimize/maximize
• Appearance customizer with live browser preview
• Widget analytics: messages, response times, conversion funnels
• Install snippet generator (HTML, NPM, React, JSON)
• Widget scheduling with timezone-aware active hours
• Client Portal inbox with search, filters, and date range
• Unread indicators and notification sounds
• File and image attachments with drag-and-drop

Helpdesk & Bookings

• Ticket management with SLA tracking and priority queues
• Helpdesk routing and automated assignment
• Appointment booking and scheduling assistant
• Knowledge base articles for self-service

Commerce

• Products, inventory, brands, promotions, and shipping
• Orders, payment links, and checkout flow
• CSV product import and export
• WhatsApp Catalog integration and sync

Business Intelligence

• Analytics dashboards for conversations, campaigns, and widgets
• KPI grids and conversion funnels
• Platform health and API latency analytics

Settings & Billing

• Settings pages: General, Members, Security, Billing, Data
• Profile photo upload with cropping and avatar sync
• Role-based invitation flow
• Billing integration ready for Paddle
• Data export, retention policies, and workspace deletion controls

Single-line list (for tags/summary fields)

Multi-tenant SaaS, WhatsApp CRM, Omnichannel Inbox, Sales CRM, Marketing Automation, Workflow Builder, AI Chatbots, RAG Knowledge Base, WhatsApp Commerce, Client Portal, Helpdesk, Live Chat Widget, Booking System, White-Label, PWA, Super Admin, REST API, Webhooks, TanStack Start, React 19.

TopAds — Versioned Changelog

Canonical changelog for the CodeCanyon listing and in-app update feed. Version format: MAJOR.MINOR.PATCH with semver-style milestones.

v1.0.0 — Initial CodeCanyon Release

Release date: 2026-07-22 Status: Stable / Production-ready

Core platform

• Multi-tenant workspace architecture with isolated PostgreSQL data per workspace
• Row-Level Security (RLS) enabled on every public table
• Role-based access control via user_roles + has_role() security-definer function
• 7 built-in roles: Owner, Admin, Manager, Agent, Sales, Marketer, Developer
• Audit logging and immutable security events
• Session pinning, account lockouts, and TOTP 2FA support
• HMAC-signed webhooks with SHA-256 verification
• Rate limiting (per-key and per-IP token buckets)
• IP allowlists and CORS whitelist per tenant
• Encrypted secrets at rest; no secrets in the repo
• White-label branding: logo, colors, domain, and email sender per workspace
• Progressive Web App (PWA) with installable experience and push notifications
• Super Admin dashboard for tenant, plan, and platform health management
• Docker + docker-compose bundle for self-hosting
• Health check endpoint at /api/public/health

WhatsApp Cloud API

• Official Meta WhatsApp Cloud API integration with WABA management
• Message templates library (CRUD, drafts, categories, approval status)
• 6-step template wizard with header, body, footer, buttons, and variables
• Secure webhook processing with HMAC-SHA256 signature verification
• Auto-reply engine for inbound WhatsApp messages
• E.164 phone normalization and contact matching rules
• Bulk contact re-matching job
• WhatsApp commerce catalog sync and product collections
• Media upload, download, and CDN-ready re-hosting
• Async delivery outbox and status tracking

Omnichannel inbox

• Unified inbox supporting WhatsApp, Instagram, Messenger, Telegram, Email, SMS, and Live Chat
• Conversation list with search, filters, date range, and unread toggle
• Real-time updates via Supabase Realtime with workspace-scoped channels
• Star, pin, resolve, archive, and assign with keyboard shortcuts
• Message sending states: sending, delivered, read, failed with retry
• Attachments, media previews, thumbnails, and upload progress
• Optimistic UI updates and persistent conversation read state
• Bulk re-link conversations action

CRM & sales

• Contact and company management with custom fields, tags, notes, and tasks
• Customer activity timeline and engagement metrics
• AI-generated customer insights using Gemini 1.5 Flash
• Sales pipelines with Kanban board, deal stages, and forecasting
• Quotes, invoices, and order management
• Duplicate action and restore-from-trash flow
• Lead scoring and AI sales assistant
• Birthday reminders and task due-date notifications

Marketing

• Campaign wizard with segmentation, templates, and scheduling
• Broadcast campaigns with enqueue, pause, resume, and cancel
• A/B testing framework and drip sequences
• Append recipients to running or scheduled campaigns without duplicates
• Campaign analytics dashboard

Automation & workflows

• Visual no-code workflow builder (React Flow)
• Omnichannel trigger and action nodes
• Async validation for duplicate workflow names
• Execution ceilings and reliability dashboard
• Chatbot lifecycle webhooks with delivery logs
• Routing rule tester with sample contact simulation

AI & chatbots

• AI provider engine supporting multiple providers
• AI reply assistant and conversation intelligence
• RAG-powered Knowledge Base with pgvector
• Visual chatbot builder and marketplace
• Chatbot install flow with permissions and workspace selection
• Template diff preview and compatibility signals
• Test chat flow immediately after creation
• Soft-delete + trash with restore and bulk actions
• Role-based chatbot permissions

Client portal & widgets

• Embeddable live chat widget (420×600px) with minimize/maximize
• Appearance customizer with live preview
• Widget analytics dashboard with Recharts KPIs
• Install snippet generator (HTML, NPM, React, JSON)
• Widget scheduling with timezone-aware active hours
• Client Portal with inbox, tickets, bookings, and documents
• Unread indicators and notification sounds
• File and image attachments in chat
• Real-time unread counts via Supabase Realtime
• Persistent conversation read state across devices

Helpdesk & bookings

• Ticket management with SLA tracking and priority queues
• Helpdesk routing and automated assignment
• Appointment booking and scheduling assistant
• Knowledge base articles for self-service

Commerce

• Products, inventory, brands, promotions, and shipping
• Orders, payment links, and checkout
• CSV import for products
• WhatsApp Catalog integration

Business intelligence

• Analytics dashboards for conversations, campaigns, and widgets
• KPI grids and conversion funnels
• Platform health and API analytics

Settings & billing

• Settings pages: General, Members, Security, Billing, Data
• Profile photo upload with cropping and Supabase Storage persistence
• Invitation flow with role-based workspace invites
• Billing integration ready for Paddle (Merchant of Record)
• Data export, retention policies, and workspace deletion controls

Documentation

• Complete developer documentation portal at /docs/index.html
• 12 sections: Introduction, Installation, Build & Deployment, Structure, Configuration, Features, Demo Mode, Setup Wizard, Changelog, Troubleshooting, FAQ, and API Reference
• Full-text search, copy-to-clipboard code blocks, and responsive mobile menu
• CodeCanyon preview image and listing asset pack

v1.0.1 — Inbox & UI Polish

Release date: 2026-07-29 (planned)

Fixed

• Real-time listeners now strictly tenant-scoped to prevent cross-workspace updates
• Optimistic updates for conversation read state zero out unread dots immediately
• UI layout fixes for /inbox badge counts and header quick-actions
• Standardized max-w-7xl page wrappers across settings and commerce modules
• Fixed blank pages in Settings caused by DB column mismatches

Improved

• Keyboard shortcuts now active across inbox, global search, and command palette
• Attachment dialogs converted to modal dialogs for better UX
• Delete message confirmation modal added
• Date/time pickers migrated to shadcn/ui components across 20+ files
• Icon/avatar sizes standardized to w-9 h-9

v1.1.0 — Commerce & Campaign Hardening

Release date: 2026-08-12 (planned)

Added

• Full commerce order lifecycle with status transitions
• Inventory adjustment history and low-stock alerts
• Promotion math engine with discount stacking rules
• Shipping provider integration hooks
• Brand management with logo upload
• CSV export for products and orders
• Campaign recipient segmentation by tags and custom fields

Fixed

• Commerce and campaign sub-pages no longer render blank due to route conflicts
• WhatsApp Templates drafts page now fetches real data with loading/error states
• Campaign enqueue logic allows appending to running/scheduled campaigns safely

v1.2.0 — Chatbot Marketplace & Permissions

Release date: 2026-08-26 (planned)

Added

• Chatbot marketplace hero stats and real-time counts
• Compatibility panel showing WhatsApp plans, languages, and data policies
• Install template dialog with 3-step flow (permissions → workspace → install)
• Diff panel comparing new installation to existing chatbots with the same name
• Re-enable action for disabled template bots
• Role-based chatbot permissions enforced in UI and API
• Webhook lifecycle events for chatbot created/updated/paused/restored/deleted

v1.3.0 — Integrations & Settings

Release date: 2026-09-09 (planned)

Added

• Integrations marketplace with top-level tabs and category counts
• Provider detail and install pages with back navigation
• Connect/disconnect flow for OAuth and API key integrations
• Per-integration webhook configuration, event selection, and secret rotation
• Audit logging for install, connect, disconnect, and webhook events
• Settings parent menu with General, Members, Security, Billing, and Data
• Profile photo upload with cropping and header avatar sync

v1.4.0 — Client Portal & Helpdesk

Release date: 2026-09-23 (planned)

Added

• Full client portal chat inbox with search, filters, and date range
• Message sending states and retry for failed sends in portal and widget
• Image and file attachments with upload progress and previews
• Unread message indicators and notification sounds in widget
• Persistent conversation read state across devices
• Helpdesk SLA management and routing rules tester
• Knowledge Base articles for client self-service

v1.5.0 — Documentation & Onboarding

Release date: 2026-10-07 (planned)

Added

• Complete documentation portal (/docs/index.html)
• API reference section with endpoints, examples, and webhook verification
• Copy-to-clipboard buttons on all code blocks with toast feedback
• Full-text search across all documentation sections
• Documentation link added to sidebar and app header
• Setup wizard with validation, security locks, and recovery SQL
• CodeCanyon preview image and listing asset pack

Roadmap

• Native mobile apps (Expo project scaffold already included in /mobile/)
• Plugin SDK and marketplace extension submission flow
• Advanced BI with custom reports and scheduled exports
• Two-way email sync (Gmail / Microsoft 365)
• Voice / call channel integration
• Advanced AI agents with tool use
• Marketplace add-on store for chatbot templates

Versioning policy

• MAJOR — breaking architectural changes, new major channel rewrites, or migration-required schema updates
• MINOR — new feature modules, new integrations, or significant UX redesigns
• PATCH — bug fixes, security patches, and small UI/UX improvements
• Deprecations are announced at least one minor version in advance
• Public API versions are maintained for at least 12 months after deprecation

TopAds — CodeCanyon Listing Asset Pack

A complete, copy-paste ready listing pack for the TopAds multi-tenant WhatsApp & Omnichannel CRM platform. Built by WRAPCODERS.

1. Item Title

TopAds — Multi-Tenant WhatsApp CRM, Omnichannel Inbox, Marketing & Automation SaaS

Alternative title options

• TopAds — WhatsApp Business API CRM + Marketing Automation Platform
• TopAds — Omnichannel Inbox, Sales CRM, Chatbots & Commerce SaaS
• TopAds — White-Label Customer Communication & Automation Platform

2. Short Description (tagline, 150 chars max)

A complete WhatsApp-first, multi-tenant CRM with omnichannel inbox, sales pipelines, marketing campaigns, AI chatbots, workflows, and commerce.

Alternative short descriptions

• Enterprise-grade WhatsApp CRM with omnichannel inbox, marketing automation, and AI chatbots.
• White-label customer communication platform: CRM, campaigns, workflows, chatbots, and commerce.
• The all-in-one SaaS for sales, support, and marketing teams that live on WhatsApp.

3. Full Description (HTML)

<h2>TopAds — The Complete WhatsApp-First Customer Communication Platform</h2>

      <p>TopAds is a production-ready, multi-tenant SaaS platform that unifies sales, support, marketing, and commerce into one collaborative workspace. Built on the official Meta WhatsApp Cloud API and 15+ channel integrations, it gives agencies, SaaS founders, and enterprise teams a white-label foundation to onboard clients, automate conversations, and close more deals.</p>

      <h3>What you get</h3>
      <ul>
        <li><strong>Unified Omnichannel Inbox</strong> — WhatsApp, Instagram, Messenger, Telegram, Email, SMS, Live Chat, and more in one thread-aware timeline.</li>
        <li><strong>Sales CRM & Pipelines</strong> — Kanban deals, quotes, invoices, lead scoring, and AI-assisted sales insights.</li>
        <li><strong>Marketing & Campaigns</strong> — Broadcast campaigns, A/B testing, drip sequences, segmentation, and delivery analytics.</li>
        <li><strong>No-Code Workflow Builder</strong> — Visual automation with React Flow, omnichannel triggers, routing rules, and execution analytics.</li>
        <li><strong>AI Layer</strong> — Reply assistant, conversation intelligence, RAG-powered knowledge base, and AI chatbot builder.</li>
        <li><strong>WhatsApp Commerce</strong> — Catalog sync, product collections, orders, payment links, promotions, and shipping.</li>
        <li><strong>Client Portal</strong> — Branded self-service portal with conversations, tickets, bookings, and documents.</li>
        <li><strong>Helpdesk & SLAs</strong> — Ticket routing, priority queues, SLA timers, and team workload dashboards.</li>
        <li><strong>Developer Center</strong> — REST API, webhooks, personal access tokens, SDKs, and API explorer.</li>
        <li><strong>Super Admin & Multi-tenancy</strong> — Workspace isolation, RBAC, plans, billing, and platform health monitoring.</li>
      </ul>

      <h3>Why TopAds?</h3>
      <p>Unlike single-purpose WhatsApp tools, TopAds is a complete operating system for customer relationships. Every module is workspace-scoped, role-aware, and built to scale from one operator to thousands of tenants. The UI is built with React 19, TanStack Start, Tailwind CSS v4, and shadcn/ui — modern, fast, and easy to theme.</p>

      <h3>Perfect for</h3>
      <ul>
        <li>Agencies reselling WhatsApp CRM services</li>
        <li>SaaS founders launching a customer-communication product</li>
        <li>E-commerce teams needing WhatsApp orders and campaigns</li>
        <li>Support teams replacing Zendesk/Intercom with a self-hosted alternative</li>
        <li>White-label entrepreneurs looking for a complete starter platform</li>
      </ul>

      <h3>Tech stack</h3>
      <ul>
        <li>React 19 + TanStack Start v1 + TanStack Router + TanStack Query</li>
        <li>Tailwind CSS v4 + shadcn/ui + Radix UI primitives</li>
        <li>TanStack Server Functions on Cloudflare Workers runtime</li>
        <li>PostgreSQL 15+ with Row-Level Security (RLS)</li>
        <li>Managed auth (email, Google OAuth, TOTP 2FA)</li>
        <li>Supabase Realtime + Postgres CDC</li>
        <li>AI Gateway (Gemini, GPT) + pgvector RAG</li>
        <li>Paddle billing integration</li>
        <li>Vite 7 + Bun</li>
      </ul>

      <h3>Built-in documentation</h3>
      <p>The package ships with a complete developer documentation portal (<code>/docs/index.html</code>) covering installation, build & deployment, configuration, features, API reference, setup wizard, troubleshooting, FAQ, and changelog.</p>

      <h3>License</h3>
      <p>Regular License is suitable for a single end product. Extended License is required for SaaS / multi-client resale where the app itself is the product.</p>
      

4. Key Features Bullets

Core platform

• Multi-tenant workspace architecture with isolated data per tenant
• Role-based access control (RBAC) with 7 roles: Owner, Admin, Manager, Agent, Sales, Marketer, Developer
• Row-Level Security (RLS) on every public table with workspace-scoped policies
• Audit logging, immutable security events, and activity timelines
• TOTP 2FA, password policies, breach detection, and session pinning
• White-label branding: logo, colors, domain, email sender per workspace
• Progressive Web App (PWA) with installable experience and push notifications
• Super Admin dashboard for tenant, plan, billing, and platform health management
• Developer Center with REST API, OAuth, webhooks, SDKs, and API explorer
• Plugin / integration marketplace with install, connect, disconnect, and webhook flows

Omnichannel inbox

• Unified inbox for WhatsApp, Instagram, Messenger, Telegram, Email, SMS, and Live Chat
• Conversation list with search, filters, date range, unread toggle, and bulk actions
• Real-time message updates via Supabase Realtime with workspace-scoped channels
• Star, pin, resolve, archive, and assign conversations with keyboard shortcuts
• Message status indicators: sending, delivered, read, failed with retry
• Attachments, media previews, thumbnails, and upload progress
• Contact identity matching with E.164 phone normalization and bulk re-matching
• Optimistic UI updates and persistent conversation read state

WhatsApp Cloud API

• Official Meta WhatsApp Cloud API integration (WABA management)
• Message templates library with CRUD, drafts, categories, and approval-aware status
• 6-step template wizard with header, body, footer, buttons, variables, and preview
• Secure webhook processing with HMAC-SHA256 signature verification
• Auto-reply engine for inbound WhatsApp messages
• Contact lookup and configurable matching rules for CRM mapping
• WhatsApp commerce catalog sync, orders, and product collections
• Media upload, download, and CDN-ready re-hosting

CRM & sales

• Contact and company management with custom fields, tags, and notes
• Customer activity timeline, engagement metrics, and AI-generated insights
• Sales pipelines with Kanban board, deal stages, and weighted forecasting
• Quotes, invoices, and order management with duplicate and trash flows
• Lead scoring and AI sales assistant for predictive insights
• Task and reminder system with due-date notifications
• Birthday reminders and customer engagement tracking

Marketing

• Campaign wizard with audience segmentation, template selection, and scheduling
• Broadcast campaigns with enqueue, pause, resume, and cancel controls
• A/B testing framework, drip sequences, and delivery analytics
• Can append recipients to running or scheduled campaigns without duplicates
• Campaign analytics dashboard with sent, delivered, read, and failed metrics

Automation & workflows

• Visual no-code workflow builder built on React Flow
• Pre-built nodes for omnichannel triggers, actions, delays, conditions, and routing
• Async validation to warn if a workflow name is already taken
• Execution ceilings, reliability dashboard, and error recovery
• Chatbot lifecycle webhooks with HMAC signing and delivery logs
• Routing rules engine with sample-contact testing simulator

AI & chatbots

• AI provider engine supporting multiple providers via AI Gateway
• AI reply assistant and conversation intelligence
• Knowledge Base (RAG) with pgvector, document uploads, and collections
• Visual chatbot builder with template marketplace
• Chatbot install flow with permissions, workspace selection, and diff preview
• Test chat flow immediately after creation
• Soft-delete + trash behavior with restore and bulk actions
• Chatbot scheduling and enable/disable controls

Client portal & widgets

• Embeddable live chat widget with appearance customizer and real-time preview
• Widget analytics: message counts, response times, conversion funnels
• Install snippet generator (HTML, NPM, React, JSON)
• Widget scheduling with timezone-aware active hours
• Client Portal with inbox, tickets, bookings, and documents
• Unread indicators, message sounds, and auto-mark-as-read
• File and image attachments with drag-and-drop and upload progress

Helpdesk & bookings

• Ticket management with SLA tracking, priority, and queues
• Helpdesk routing rules and automated assignment
• Appointment booking and scheduling assistant
• Booking analytics and resource management

Commerce

• Products, inventory, brands, promotions, and shipping management
• Orders, payment links, and checkout flow
• CSV import for products
• WhatsApp Catalog integration and sync

Business intelligence

• Analytics dashboards for conversations, campaigns, chatbots, and widgets
• KPI grids, conversion funnels, and response-time metrics
• Platform health dashboard and API analytics

5. What's Included

• Full source code (React 19 + TanStack Start + TypeScript)
• Server functions and public API routes (TanStack Start)
• Supabase migrations and database schema with RLS policies
• Docker & docker-compose files for local and production deployment
• Developer documentation portal (/docs/index.html)
• CodeCanyon preview image (/codecanyon-preview.jpg)
• README with installation steps
• ENV example file
• Postman / OpenAPI-compatible API reference in documentation

6. Requirements

• Node.js 18+ or Bun 1.0+
• PostgreSQL 15+ (recommended: managed Postgres with pgvector extension)
• A Supabase-compatible backend or self-hosted Postgres
• Meta Business account for WhatsApp Cloud API
• Paddle account for billing (optional, can be disabled)
• SMTP / email provider for transactional email
• Cloudflare account (recommended for Workers deployment)

7. Installation / Quick Start

1. Extract the archive and run bun install
2. Copy .env.example to .env and fill in your database, auth, and API keys
3. Run supabase db push to apply migrations and seed roles
4. Run bun run dev to start the local dev server
5. Open http://localhost:8080 and complete the setup wizard
6. For production, run bun run build and deploy via Docker or Cloudflare Workers

Full step-by-step guides are in /docs/index.html.

8. Tags / Keywords

whatsapp crm, omnichannel inbox, whatsapp marketing, saas platform, multi tenant, customer communication, sales crm, marketing automation, chatbot builder, workflow automation, react start, tanstack start, white label, client portal, helpdesk, ecommerce, meta api, business api, paddle billing, ai assistant, rag knowledge base

9. Pricing Notes (internal)

• Regular License: $79
• Extended License: $499
• Category: PHP Scripts → Miscellaneous (list React/TanStack Start as tech stack)

10. Author / Branding

• Author: WRAPCODERS
• Product: TopAds
• Website: https://wrapcoders.com/
• Support: https://wrapcoders.com/support
• Demo: https://wrapcoders.com/topads-demo

TopAds v3.4.6 — CodeCanyon Release Notes

Product: TopAds — Multi-tenant WhatsApp CRM & Omnichannel SaaS Platform
Version: v3.4.6
Release Date: 2026-07-27
Author: WRAPCODERS
Support: https://wrapcoders.com/support

Release Overview

v3.4.6 is a production-hardened, enterprise-ready release focused on security, stability, performance, and CodeCanyon commercial quality. This release ships the final audit remediation pass — zero Critical or High severity defects remain open.

Release Status: ✅ Ready for Production Deployment

What's New

🛡️ Enterprise Security Hardening

• Zero open Critical/High security findings after full OWASP Top 10 audit.
• XSS protection across all public-facing surfaces:
  • Markdown links now enforce an http(s) / mailto / tel / relative allowlist and block javascript: and executable schemes.
  • OAuth callback endpoints (/api/public/webhooks/messenger, /api/public/webhooks/instagram) now HTML-escape all interpolated query parameters and response bodies.
  • Same-origin redirect guards prevent protocol-based open redirects (javascript:, data:).
• Auth bypass closed: /reset-password now strictly requires a valid PASSWORD_RECOVERY event or recovery marker; a fallback error state handles invalid/expired links.
• Plugin sandbox hardened: plugin entryUrl is restricted to https: only, preventing arbitrary code execution via untrusted sources.
• Security headers added/verified: x-content-type-options: nosniff, referrer-policy: no-referrer, CSP baseline.
• Supabase RLS verified across all public tables; roles isolated in dedicated user_roles table with has_role() SECURITY DEFINER checks.

⚡ Performance & Stability

• Auth event filtering in __root.tsx and use-idle-logout.tsx now ignores TOKEN_REFRESHED and INITIAL_SESSION, eliminating hourly router thrashing and idle-timer resets.
• TanStack Query cache optimized: branding, roles, and feature flags pinned to staleTime: Infinity.
• Asset delivery hardened: hashed assets served with Cache-Control: public, max-age=31536000, immutable and correct MIME types in Node/cPanel deployments.
• Vite base normalized to / so production URLs match the real domain.

🐛 Critical & High Bug Fixes

🎨 Visual & Responsive Polish

• Landing / Marketing header no longer overlaps on mobile viewports; logo and nav actions properly truncated/hidden at < sm.
• min-h-dvh adopted on public shells to fix iOS Safari viewport clipping.
• MarketingShell now uses the official landing-logo.png caduceus logo consistently across sub-pages.
• Admin sidebar scroll behavior stabilized with ScrollArea.
• rounded radius token standardized across UI surfaces.

🔧 Backend Reliability

• Database audit completed; migration prepared to:
  • Tighten plugin_downloads INSERT policy to user_id = auth.uid().
  • Pin search_path on 5 trigger functions to prevent catalog shadowing.
  • Revoke EXECUTE from PUBLIC/anon on 15 cron/worker SECURITY DEFINER helpers.
• Rolled-back transaction root cause identified and tracked; webhook idempotency and RLS conflict paths documented for ongoing monitoring.
• FK index backlog documented (150+ columns) with safe, prioritized rollout plan.

Files Changed in v3.4.6

src/components/docs/markdown.tsx
      src/routes/reset-password.tsx
      src/routes/_authenticated/developer.api-security.tsx
      src/lib/plugins/module-loader.ts
      src/routes/api/public/webhooks/messenger/callback.ts
      src/routes/api/public/webhooks/instagram/callback.ts
      src/routes/__root.tsx
      src/hooks/use-idle-logout.tsx
      src/hooks/use-tenant-brand.ts
      src/routes/s.$token.tsx
      src/routes/index.tsx
      src/components/app/marketing-shell.tsx
      vite.config.ts
      app.js
      app.cjs
      docs/index.html
      docs/final-production-audit.md
      docs/backend-audit.md
      docs/security-audit.md
      docs/performance-audit.md
      

System Requirements

• Node.js: 20.x or 22.x LTS
• PostgreSQL: 15+ with pgvector extension
• Supabase project with Auth, Storage, Realtime enabled
• Recommended hosting: Cloudflare Workers (default), Node standalone, Docker, or cPanel with Passenger
• Mobile: Expo SDK 52+ (optional native companion app)

How to Update from v3.3.x

1. Backup your database and .env file before updating.
2. Download v3.4.6 from CodeCanyon and replace application files.
3. Run the new database migrations:

   supabase db push
         # or
         bun run db:migrate
         

4. Install dependencies:

   bun install
         

5. Build the production bundle:

   bun run build
         

6. Restart the application server.
7. Verify /api/public/health returns 200 OK.

For detailed upgrade instructions, see /docs/upgrade.md in the documentation portal.

Pre-Flight Checklist Before Going Live

• Run bunx tsgo --noEmit — 0 TypeScript errors
• Run bun run build — production build succeeds
• Verify .env values: SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, LOVABLE_API_KEY, WEBHOOK_SECRET
• Enable Supabase HIBP password check (Cloud → Auth → Settings)
• Register WhatsApp webhook URL with Meta and confirm verification challenge returns 200
• Snapshot database as rollback baseline
• Smoke-test /, /auth, /pricing, /docs, and one authenticated dashboard route

Post-Launch Backlog (Non-Blocking)

The following items are tracked for the first two point releases and do not affect launch:

• Batch-add aria-label to ~164 icon-only buttons.
• Implement @tanstack/react-virtual for Contacts / Deals / Tickets large tables.
• Apply FK-index migration across 150+ foreign key columns.
• Convert duplicate logo PNGs to WebP for smaller bundle.
• Add MFA enforcement toggle for super-admins.
• Add rel="noopener noreferrer" to remaining external target="_blank" links.

Support

For installation, deployment, or bug reports, open a ticket at https://wrapcoders.com/support and include:

1. Your purchase code
2. Clear steps to reproduce
3. Relevant error messages, screenshots, or logs
4. Version number shown in the app footer (should read v3.4.6)

Product: TopAds
Version: v3.4.6
Release Date: 2026-07-27
Author: WRAPCODERS
Website: https://wrapcoders.com
Support: https://wrapcoders.com/support

TopAds — CodeCanyon Release Checklist

Phase 15 deliverables. This file is the shipping playbook for publishing TopAds on CodeCanyon as an enterprise-grade, self-hosted SaaS platform.

1. Security Hardening

• Row-Level Security enabled on every public table (workspace-scoped).
• Role-based access via user_roles + has_role() security-definer function (no privilege escalation).
• HMAC-signed webhooks (SHA-256, timing-safe compare).
• Rate limiting (per-key and per-IP token buckets).
• IP allowlists and CORS whitelist per tenant.
• Encrypted secrets at rest; no secrets in the repo.
• OWASP API Top-10 review (auth, injection, mass-assignment, misconfig).
• Password policy: length ≥ 12, complexity, breach check (HIBP), rotation.
• Optional TOTP 2FA for all users.
• Full audit log with immutable trail.
• Automated dependency vulnerability scanning.
• Session pinning to IP+UA hash; account lockouts after failed attempts.

2. Compliance

• GDPR: data export, right to erasure, consent tracking, retention policies.
• SOC 2: access controls, change management (Git), incident response.
• HIPAA: BAA template (activate per healthcare tenant).
• Cookie consent banner; documented cookie inventory.
• Data Processing Agreement (DPA) template in /docs/compliance/.
• Subprocessor list in trust center.
• Privacy policy, Terms of Service, Refund policy templates in /docs/legal/.