Abhiron v6.8.9 Production

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

Overview

Abhiron unifies WhatsApp, Instagram, Messenger, Telegram, Email, SMS, Live Chat, TikTok direct messages and Facebook, YouTube, LinkedIn and TikTok comments 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.

Version 6.8.9 adds tenant-owned OpenAI/Gemini keys, social comments in the Inbox, TikTok direct messages with an AI chatbot, long-lived YouTube connections and unified notifications. See the changelog and detailed release notes below.

The reference library near the end of this page contains historical design and audit snapshots. For the pending Lovable Cloud removal, follow the unreleased change record and current deployment guide.

Features Summary

Tech Stack

Installation Guide

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

System Requirements

1. Environment Setup

Clone the repository and copy the example environment file:

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

2. Install Dependencies

# with bun (recommended)
bun install

# or npm
npm install

3. Database Setup

Abhiron 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

npm install --legacy-peer-deps   # the repository's .npmrc sets this already
npm run dev                      # hot-reload dev server
npm run lint                     # eslint
npx tsgo --noEmit -p tsconfig.json   # type check

Production Build

NITRO_PRESET=node-server npm run build    # standalone server in .output/
node .output/server/index.mjs             # start it (PORT and HOST from the environment)

There is no npm start script. What npm run build produces depends on NITRO_PRESET; without it you get a standalone Node server bundle. See Deployment Overview for the full table.

Pick your deployment guide

Common Deployment Issues

Deployment Overview & Choosing a Target

A Abhiron installation has three moving parts. You deploy the first two and then wire them together:

                    +-------------------------------+
   Browser  ------> |  Abhiron app  (one host of your |  ------> Supabase
   (React SPA +     |  choice: Docker/VPS, Netlify, |           - Postgres (data, RLS)
    server render)  |  Vercel, Cloudflare, cPanel)  |           - Auth, Realtime, Storage
                    +-------------------------------+           - Vault, pg_cron, pg_net
                       ^          ^          ^                         |
   Meta / Twilio /     |          |          |  HTTPS POST             |
   Telegram / Stripe --+          |          +------ pg_cron ----------+
   (webhooks)                     |                  (background jobs)
                                  |
                   optional: WhatsApp QR worker (separate long-running service)

1. Supabase — the database and authentication. Always required. See Supabase Setup.
2. The app — a stateless Node/edge application. Pick one target from the table below.
3. Wiring — scheduled jobs (pg_cron → app) and provider webhooks (provider → app).
4. Optional — the WhatsApp QR worker, which needs a long-running process and can never run on a serverless host.

Which target should I use?

How the build target is chosen

The build is always npm run build. What it produces is decided by the NITRO_PRESET environment variable, read by vite.config.mts. Set it before the build runs. If it is not set, the build produces a standalone Node server bundle. The preset is baked into the build output; switching targets means rebuilding.

Setting the variable for a single command:

# Linux / macOS / WSL / CI
NITRO_PRESET=node-server npm run build

# Windows PowerShell
$env:NITRO_PRESET = "node-server"; npm run build

Three URLs must agree

Whatever host you choose, the same public origin (scheme + host, no path, no trailing slash) is used in three places. A mismatch is the most common cause of "login works but jobs do not" style problems.

Recommended order of operations

1. Create and configure Supabase (Supabase Setup). Note the URL and keys.
2. Prepare the environment variables (reference). Generate secrets with openssl rand -hex 32.
3. Deploy the app to your chosen target and confirm /api/public/health returns 200.
4. Open /setup once to create the Super Admin.
5. Configure scheduled jobs (two Vault secrets plus INTERNAL_CRON_TOKEN).
6. Register provider webhooks for the channels you use.
7. Run the go-live checklist and open Release Readiness.

Demo mode versus production mode

APP_MODE (server) and VITE_APP_MODE (client bundle) select the behaviour. production is the default and is what real customers should use: no demo accounts, no seeded sample data, no write guards. demo shows one-click demo logins and blocks destructive writes, which is right for a public showcase site only. Both variables must agree, and VITE_APP_MODE is fixed at build time. See Environment Mode System.

Environment Variable Reference

Copy .env.example as a starting point. Two kinds of variable exist and they behave differently on every host:

• Build-time (VITE_*, NITRO_PRESET): read while npm run build runs and baked into the output. They are public. Never put a secret in a VITE_* variable. Changing one requires a rebuild.
• Runtime: read by the server while it runs. Secrets live here. On serverless hosts these must be set in the provider's environment/secret store, and they usually take effect only after the next deploy.

Required

Optional, by feature

Supabase (Backend) Setup

Supabase provides the database, authentication, realtime updates and file storage. Abhiron does not use Supabase Edge Functions (supabase/functions/ is intentionally empty); all server logic runs inside the app you deploy elsewhere.

Option A: Supabase Cloud (recommended)

1. Create the project

1. Create a project at supabase.com. Choose a region close to the host that runs the app (each request makes several round trips to the database).
2. Save the database password in your password manager. You need it for the CLI.
3. For production, use a paid plan. Free projects pause after a period of inactivity and have no daily backups; check the current plan limits before launch.

2. Enable extensions

Dashboard → Database → Extensions. Enable pg_cron, pg_net, pg_trgm, vector, pgcrypto and btree_gist. supabase_vault is installed by default. The migrations also run CREATE EXTENSION IF NOT EXISTS, but enabling them first avoids permission surprises.

3. Apply the schema

Standard way (Supabase CLI):

npx supabase login
npx supabase link --project-ref YOUR_PROJECT_REF     # the ref is in the dashboard URL
npx supabase db push                                  # applies supabase/migrations in order (asks for the DB password)

supabase/config.toml in the repository contains the development project's id. Ignore it or replace it with your own ref; link is what selects the target.

Password-less alternative (Windows PowerShell): scripts/push-migrations.ps1 applies every migration over the REST API with the service-role key, then records the versions so a later supabase db push sees them as applied. It needs a one-time helper function that you create in the SQL editor and that the script removes at the end:

create or replace function public.__bootstrap_exec(sql text) returns void
language plpgsql security definer set search_path = public as $$ begin execute sql; end $$;
revoke all on function public.__bootstrap_exec(text) from public, anon, authenticated;
grant execute on function public.__bootstrap_exec(text) to service_role;

# SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are read from .env
.\scripts\push-migrations.ps1 -DryRun          # review the plan first
.\scripts\push-migrations.ps1 -Skip 0          # blank project: apply everything

Verify:

select count(*) from supabase_migrations.schema_migrations;                       -- equals the number of files in supabase/migrations
select count(*) filter (where not c.relrowsecurity) as tables_without_rls
  from pg_class c join pg_namespace n on n.oid = c.relnamespace
 where n.nspname = 'public' and c.relkind = 'r';                                    -- expect 0
select id from storage.buckets order by id;                                        -- the nine buckets

4. Copy the API values

Dashboard → Project Settings → API:

5. Configure authentication

• URL Configuration: set Site URL to your public origin and add https://your-domain/** (plus any preview domains) to Redirect URLs. Confirmation, invitation and reset links use these.
• Email: decide whether new users must confirm their email address. In production configure custom SMTP (Authentication → SMTP). Supabase's built-in mailer is for testing and is heavily rate limited.
• Social login: the Google and Apple buttons use Supabase Auth OAuth. Configure each provider in Supabase Auth and register the Supabase callback URL with the provider. These buttons call supabase.auth.signInWithOAuth directly.

6. Storage and Realtime

Nothing to create: the buckets come from migrations and Realtime is on by default. If you need uploads larger than the default, raise the limit in Project Settings → Storage. Keep the buckets private; the app serves files with signed URLs.

7. Create the first Super Admin

Deploy the app, then open /setup. The wizard creates the Super Admin, applies branding, configures SMTP and locks the installation. It refuses to run again once a Super Admin exists or setup is marked complete. If you reuse a database that ever ran in demo mode, review and run scripts/purge-demo-data.sql first to remove demo accounts and sample data.

8. Backups and safety

• Turn on backups (Dashboard → Database → Backups); point-in-time recovery is an add-on on paid plans. The in-app Backup Management screen does not create real backups.
• Never expose the service-role key. If it leaks, roll it in the dashboard and update every deployment.
• Restrict database access under Database → Network Restrictions if your hosts have fixed IP addresses.

Option B: Self-hosted Supabase

You can run Supabase yourself with the official Docker stack. Abhiron then needs the same features: Postgres with pg_cron, pg_net, pgcrypto, pg_trgm, vector, btree_gist and the Vault extension, plus Auth, Realtime, Storage and the REST API behind one gateway URL. Set SUPABASE_URL to that gateway and apply the migrations with supabase db push --db-url or the SQL files directly. Self-hosting is not covered by our testing; follow the official self-hosting guide and treat backups, upgrades and TLS as your responsibility.

Upgrading the database

1. Take a backup or snapshot.
2. Apply the new migrations first (npx supabase db push).
3. Then deploy the matching app version.

Migrations only move forward. To roll back, restore the backup taken in step 1 rather than editing the schema by hand.

Deploying to Netlify

Abhiron is server-rendered (TanStack Start on Nitro). With the Nitro netlify preset the build produces static assets in dist/ and a single Netlify Function (server) that handles pages, server functions (/_serverFn/*) and the public API and webhook routes (/api/public/*).

What is in the repository

1. Prerequisites

• A Netlify account and Node 22 LTS locally.
• A Supabase project with all migrations in supabase/migrations/ applied.
• The Netlify CLI, run through npx. Log in once: npx netlify-cli login.

2. Create and link the site

cd /path/to/abhiron
npx netlify-cli sites:create --name my-abhiron     # or: npx netlify-cli link  (existing site)
npx netlify-cli status                            # confirm the linked site and account

The account you are logged in as must own the site. If deploy fails with JSONHTTPError: Not Found, the linked site belongs to a different Netlify account: run npx netlify-cli unlink, then create or link a site under the current account.

3. Environment variables

There are two separate places, and they are not interchangeable:

Server functions run in the Netlify Function, so anything they read at runtime must be a Netlify environment variable, not just a netlify.toml value.

# import everything from your local .env, then fix the values that differ per environment
npx netlify-cli env:import .env
npx netlify-cli env:set APP_ORIGIN https://my-abhiron.netlify.app
npx netlify-cli env:set APP_MODE production

4. Deploy

npx netlify-cli deploy --prod

The CLI reads netlify.toml, builds locally (about 8 minutes on a laptop: vite build plus the Nitro step), and uploads dist/ and the function. Run it from the repository root, where package.json lives.

Git-based deploys. Connecting a GitHub/GitLab repository also works. Netlify then runs the build itself and sets NETLIFY=true, so the Netlify preset is selected automatically. The repository root must contain package.json and netlify.toml; if the app lives in a subfolder, set Base directory to it and keep netlify.toml inside that folder.

5. Scheduled jobs

Outbox, webhook delivery, workflows, reminders and syncs are driven by Postgres pg_cron calling /api/public/hooks/* on your deployment. Configure the target once per environment as described in Scheduled Jobs (pg_cron). Until you do, all of them are no-ops.

6. Verify

curl -s -o /dev/null -w "%{http_code}\n" https://my-abhiron.netlify.app/        # expect 200
npx netlify-cli logs --source functions --function server --since 15m            # expect no ERR_MODULE_NOT_FOUND

Then sign in as a platform admin and open Release Readiness. "Scheduled jobs call this deployment" should read Pass once APP_ORIGIN, the Vault URL and the token all agree.

Limits to plan for

Troubleshooting

Scheduled Jobs (pg_cron)

Background work is triggered from the database. pg_cron jobs call the helper public._wa_cron_post(path, body), which sends an HTTP POST with an x-cron-token header to /api/public/hooks/* on your deployment. This applies to every hosting option (Netlify, VPS, Docker, cPanel).

The helper reads its target from Supabase Vault. Nothing is hard-coded in the database:

If either secret is missing, blank or not a valid URL, the helper does nothing (it returns NULL and posts nothing). Release Readiness reports this as a failed check. It is deliberately not an error, so a fresh install never posts to the wrong host.

Set it up

Generate a token once and put the same value in both places without ever displaying it. PowerShell:

$b = New-Object byte[] 32; [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b)
$t = ($b | ForEach-Object { $_.ToString('x2') }) -join ''
npx netlify-cli env:set INTERNAL_CRON_TOKEN $t     # app side (any host: set INTERNAL_CRON_TOKEN there)
Set-Clipboard $t                                    # then paste into the SQL below

Linux/macOS: t=$(openssl rand -hex 32), then use $t for both.

In the Supabase SQL editor (runs as postgres):

select vault.create_secret('https://my-abhiron.netlify.app', 'abhiron_cron_base_url');
select vault.create_secret('PASTE_TOKEN_HERE',             'abhiron_cron_token');

To change a value later, update the existing secret by name (creating it again fails with a duplicate-key error):

select vault.update_secret((select id from vault.secrets where name = 'abhiron_cron_base_url'), 'https://new-origin.example.com');
select vault.update_secret((select id from vault.secrets where name = 'abhiron_cron_token'),    'PASTE_NEW_TOKEN_HERE');

Verify

• Release Readiness → DevOps → Scheduled jobs call this deployment = Pass. The server compares a SHA-256 of the Vault token with your INTERNAL_CRON_TOKEN; the token itself is never returned.
• Function or server logs show POST /api/public/hooks/... requests every minute with status 200 (401 means the tokens differ, 404/500 means the URL or deployment is wrong).
• select count(*) from cron.job where active; lists the scheduled jobs.

Note: the data-retention purge (run_retention_policies()) is not scheduled by default because it deletes data. Compliance Center shows "Retention (not running)" until you schedule it yourself.

Docker, VPS & Multiple Servers

This is the most flexible target: the same build runs on a single VPS, several servers behind a load balancer, or any container platform. The build uses NITRO_PRESET=node-server, which produces a standalone HTTP server. The bundled Dockerfile already sets it.

A. Docker Compose on a single server (app + nginx)

The repository ships a production stack: the app (2 replicas by default) behind an nginx reverse proxy that terminates TLS, adds security headers and rate limits.

1. Prepare the server

# Ubuntu 22.04 / 24.04
sudo apt update && sudo apt install -y ca-certificates curl git ufw
curl -fsSL https://get.docker.com | sudo sh                 # Docker Engine + compose plugin
sudo ufw allow OpenSSH && sudo ufw allow 80,443/tcp && sudo ufw enable
docker compose version

Create a DNS A record (and AAAA if you use IPv6) for your domain that points to the server.

2. Get the code and configure

git clone YOUR_REPOSITORY_URL abhiron && cd abhiron
cp .env.example .env.production
nano .env.production        # fill in Supabase, secrets, APP_ORIGIN=https://app.example.com, APP_MODE=production

VITE_* values in this file are passed to the image as build arguments, so they must be correct before you build.

3. TLS certificates

The proxy expects deploy/certs/fullchain.pem and deploy/certs/privkey.pem. With Let's Encrypt, request them before starting the stack (port 80 must be free):

sudo apt install -y certbot
sudo certbot certonly --standalone -d app.example.com
sudo cp /etc/letsencrypt/live/app.example.com/fullchain.pem deploy/certs/
sudo cp /etc/letsencrypt/live/app.example.com/privkey.pem   deploy/certs/

Renewal: run sudo certbot renew --deploy-hook "cp /etc/letsencrypt/live/app.example.com/*.pem /path/to/abhiron/deploy/certs/ && docker compose -f /path/to/abhiron/docker-compose.yml exec proxy nginx -s reload" from a cron/systemd timer. If the standalone renewal cannot bind port 80 while the proxy is running, use --pre-hook/--post-hook to stop and start the proxy, or terminate TLS elsewhere (Cloudflare proxy, a cloud load balancer, Caddy).

The catch-all server_name _ in deploy/nginx/conf.d/abhiron.conf serves any domain, so no host edit is needed. The first server block there only redirects legacy hostnames and can be deleted.

4. Build and start

docker compose --env-file .env.production up -d --build
docker compose ps
curl -fsS https://app.example.com/api/public/health          # {"status":"ok",...}
curl -fsS https://app.example.com/api/public/health/ready    # checks the database

5. Operate

B. A single Docker container (no compose)

docker build -t abhiron \
  --build-arg VITE_SUPABASE_URL=https://YOUR_REF.supabase.co \
  --build-arg VITE_SUPABASE_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY .
docker run -d --name abhiron --restart unless-stopped -p 3000:3000 --env-file .env.production abhiron

The container listens on port 3000 (override with PORT) and reports health at /api/public/health. Put any reverse proxy or load balancer in front of it for HTTPS.

C. Without Docker (Node + systemd + nginx or Caddy)

# Node 22 LTS (NodeSource)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash - && sudo apt install -y nodejs
sudo useradd --system --create-home --home-dir /opt/abhiron abhiron
sudo -u abhiron git clone YOUR_REPOSITORY_URL /opt/abhiron/src   # or copy a prebuilt .output
cd /opt/abhiron/src
sudo -u abhiron npm ci --legacy-peer-deps
sudo -u abhiron env NITRO_PRESET=node-server VITE_SUPABASE_URL=https://YOUR_REF.supabase.co \
  VITE_SUPABASE_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY npm run build

Store the runtime secrets in a root-owned file that only the service can read, for example /etc/abhiron/abhiron.env (mode 600) with one KEY=value per line, including PORT=3000 and HOST=127.0.0.1. Then create /etc/systemd/system/abhiron.service:

[Unit]
Description=Abhiron
After=network-online.target
Wants=network-online.target

[Service]
User=abhiron
WorkingDirectory=/opt/abhiron/src
EnvironmentFile=/etc/abhiron/abhiron.env
ExecStart=/usr/bin/node .output/server/index.mjs
Restart=always
RestartSec=3
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload && sudo systemctl enable --now abhiron
journalctl -u abhiron -f
curl -fsS http://127.0.0.1:3000/api/public/health

Put a reverse proxy in front. Caddy obtains and renews certificates automatically:

# /etc/caddy/Caddyfile
app.example.com {
    reverse_proxy 127.0.0.1:3000
}

nginx with certbot:

server {
    listen 80;
    server_name app.example.com;
    client_max_body_size 50m;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 60s;
    }
}
# then: sudo certbot --nginx -d app.example.com

PM2 also works: pm2 start .output/server/index.mjs --name abhiron --interpreter node, followed by pm2 save && pm2 startup.

D. Several servers behind a load balancer

The app keeps no state on the server. Sessions are Supabase tokens, data and files are in Supabase, and shared rate-limit counters live in the database. That makes horizontal scaling straightforward:

• Run the same build and the same environment variables on every server (identical SESSION_SECRET and WEBHOOK_SECRET in particular).
• Use any load balancer (nginx upstream, HAProxy, Caddy, a cloud load balancer). Sticky sessions are not needed. Health check: GET /api/public/health. Use /api/public/health/ready for readiness gates.
• Terminate TLS at the load balancer and forward X-Forwarded-Proto, X-Forwarded-For and Host.
• Point APP_ORIGIN, the Supabase Site URL and abhiron_cron_base_url at the load balancer's public URL, not at one server.
• Realtime connections go from the browser straight to Supabase, so they do not load the app servers.
• Scheduled jobs arrive through the same public URL. The database sends each job call once per schedule and the load balancer hands it to a single server.
• The WhatsApp QR worker must stay a single instance; scale everything else.
• Scale the database with a larger Supabase compute size or read replicas before adding many more app servers; it is normally the first bottleneck.

# nginx load balancer in front of several app servers
upstream abhiron_app {
    server 10.0.0.11:3000 max_fails=3 fail_timeout=30s;
    server 10.0.0.12:3000 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

E. Kubernetes, Cloud Run, ECS, Fly.io, Railway, Render, DigitalOcean App Platform

Any platform that runs a container works with the Docker image. The settings you need are the same everywhere:

# Kubernetes skeleton
apiVersion: apps/v1
kind: Deployment
metadata: { name: abhiron }
spec:
  replicas: 2
  selector: { matchLabels: { app: abhiron } }
  template:
    metadata: { labels: { app: abhiron } }
    spec:
      containers:
        - name: app
          image: registry.example.com/abhiron:6.8.9
          ports: [{ containerPort: 3000 }]
          envFrom: [{ secretRef: { name: abhiron-env } }]
          livenessProbe:  { httpGet: { path: /api/public/health,       port: 3000 }, periodSeconds: 30 }
          readinessProbe: { httpGet: { path: /api/public/health/ready, port: 3000 }, periodSeconds: 15 }
          resources: { requests: { cpu: 250m, memory: 256Mi }, limits: { cpu: "1500m", memory: 1Gi } }

Running on several providers at once

Because the app is stateless you can run the same build on more than one provider (for example a VPS in one country and a container platform in another) and put DNS failover or a global load balancer in front. Rules: they share one Supabase project, use identical secrets, and abhiron_cron_base_url must name the public URL that reaches a healthy instance, because the database has a single cron target.

Deploying to Vercel

Before you start

• The Vercel Hobby plan is for personal, non-commercial use. Commercial deployments need Pro.
• Function request bodies are limited to about 4.5 MB. Uploads that pass through the app (rather than going straight to Supabase Storage) larger than that will fail.
• Function run time is capped by your plan. Long scheduled jobs must finish inside it (see Netlify limits for the same consideration).

Dashboard flow (Git)

1. Push the repository to GitHub/GitLab/Bitbucket and choose Add New → Project in Vercel.
2. Framework Preset: Other. Build Command: npm run build. Leave Output Directory empty (Nitro writes .vercel/output).
3. Install Command: npm install (the repository contains both package-lock.json and bun.lock; setting it explicitly avoids the wrong package manager being picked).
4. Node.js version: 22.x (Project Settings → General).
5. Add every variable from the reference under Settings → Environment Variables for Production (and Preview if you use previews). VITE_* variables must exist before the build.
6. Deploy. Vercel sets VERCEL=1, and vite.config.mts then selects the vercel preset automatically.

CLI flow

npx vercel login
npx vercel link
npx vercel env add SUPABASE_SERVICE_ROLE_KEY production      # repeat for every variable
npx vercel --prod                                            # builds on Vercel and deploys

# or build locally and upload the result
npx vercel pull --yes --environment=production
npx vercel build --prod
npx vercel deploy --prebuilt --prod

Then

1. Add your custom domain (Project → Settings → Domains) and update APP_ORIGIN, the Supabase Site URL and the Vault URL.
2. Configure Scheduled Jobs. You do not need Vercel Cron; the database calls the app.
3. Verify /api/public/health and read the function logs in the Vercel dashboard if a page returns 500.

The QR worker cannot run on Vercel. Host it separately (QR worker).

Deploying to Cloudflare Workers

1. Build locally

npm ci --legacy-peer-deps
npm run build

This creates the complete deployable artifact under .output/, including .output/server/wrangler.json. Run this step on the developer machine (or a dedicated CI runner), not on the production/origin server. The deployment step below does not compile the application.

2. Configure one project and deploy the prebuilt artifact

CLOUDFLARE_WORKER_NAME=my-project
CLOUDFLARE_DOMAIN=app.example.com
CLOUDFLARE_ZONE_NAME=example.com

npx wrangler login
npm run deploy:cloudflare

Set the three values once in local .env (or .env.local). The worker name selects the Cloudflare project, the domain is its single custom hostname, and the zone contains that hostname. The centralized deployment script replaces the generated route list with exactly this one domain, writes a temporary deployment config, uploads the prebuilt artifact, and then deletes the temporary config.

Each client changes only these three local environment values, then uses the same two short commands: npm run build and npm run deploy:cloudflare.

3. Variables and secrets

npx wrangler secret put SUPABASE_SERVICE_ROLE_KEY --name abhiron     # repeat for each secret
npx wrangler secret put INTERNAL_CRON_TOKEN --name abhiron
npx wrangler secret put SESSION_SECRET --name abhiron
npx wrangler secret put WEBHOOK_SECRET --name abhiron

Non-secret values (SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, APP_ORIGIN, APP_MODE) can be added under Workers → your Worker → Settings → Variables. VITE_* values are read at build time, so export them before npm run build. The app reads process.env; with nodejs_compat and a compatibility date of 2025-04-01 or later, Workers populate process.env from variables and secrets. Confirm with /api/public/health/ready and Release Readiness after the first deploy.

4. Domain and scheduled jobs

• The deploy command assigns the requested custom domain automatically (the zone must be on Cloudflare). Update APP_ORIGIN, the Supabase Site URL and the Vault URL to the same origin.
• Configure Scheduled Jobs. No Cloudflare Cron Trigger is required.
• Cloudflare bot protection or WAF rules can challenge server-to-server requests. If the cron or webhook calls return 403 or a challenge page, add a WAF skip rule for the paths /api/public/hooks/* and /api/public/webhooks/*.

Cloudflare in front of a VPS

Cloudflare can also simply proxy a server you run yourself (Docker/VPS). Use SSL mode Full (strict) with a certificate on the origin and apply the same WAF skip rule. This keeps every capability of a normal server without the Worker limits.

The QR worker cannot run on Workers. Host it separately (QR worker).

cPanel / Shared Hosting (Node.js Selector)

1. Build on your own machine or in CI, not on the shared host:

   DEPLOY_TARGET=node npm run build      # same as NITRO_PRESET=node-middleware

2. Upload the whole .output/ folder, app.cjs (or app.js) and package.json to the application root (not public_html).
3. In Setup Node.js App: Node.js version 22, Application startup file = app.cjs, application URL = your domain.
4. Add the runtime variables in the panel's environment section, or place a .env file next to app.cjs (it reads one). If the panel offers Run NPM Install, run it, then Restart.
5. Open the site and check /api/public/health. Then continue with Scheduled Jobs and Webhooks.

Node 18 does not work. The QR worker cannot run in the same app; if your host allows a second Node app on a subdomain you can run it there (see QR worker).

WhatsApp QR Worker (optional)

The QR worker keeps long-lived WhatsApp Web sockets, so it is a separate, stateful service. It is only needed if you connect WhatsApp by scanning a QR code; the official WhatsApp Cloud API needs no worker. It cannot run on Netlify, Vercel or Cloudflare. Use a VPS, a container platform with a persistent disk, or a cPanel Node app.

1. Generate three shared secrets (the same values go on both sides): openssl rand -hex 32 for each of WA_QR_WORKER_TOKEN, WA_QR_WORKER_SIGNING_SECRET, WA_QR_WEBHOOK_SECRET.
2. Configure the worker (qr-worker/.env, copied from qr-worker/.env.example): the three secrets, PORT=8787, and Abhiron_WEBHOOK_URL=https://app.example.com/api/public/whatsapp/qr-webhook. The example file contains a sample host that you must replace with your own app URL.
3. Run it with Docker (mount a persistent volume for the WhatsApp credentials):

   cd qr-worker
   docker build -t abhiron-wa-qr-worker .
   docker run -d --name wa-qr --env-file .env -p 8787:8787 \
     -v $PWD/data:/app/data --restart unless-stopped abhiron-wa-qr-worker

   or with PM2 (npx pm2 start ecosystem.config.cjs && npx pm2 save).
4. Expose it over HTTPS on its own hostname, for example https://wa.example.com, proxied to 127.0.0.1:8787 (nginx or Caddy as in Docker/VPS). curl https://wa.example.com/health must return {"ok":true,...}.
5. Configure the app with WA_QR_WORKER_URL=https://wa.example.com and the same three secrets, then redeploy the app.
6. Open Admin → WhatsApp Status and run the health check, or start a QR session from the WhatsApp panel.

Webhooks & Provider Setup

After the app is live on its public HTTPS URL, register these callback URLs with each provider. Replace https://app.example.com with your origin. Webhooks must reach the app directly; do not put them behind a login or an interactive bot challenge.

Meta (WhatsApp, Messenger, Instagram) checklist

1. In the Meta app dashboard add the callback URL and the same verify token you set in the app environment.
2. Subscribe to the message events for the product (messages, message status).
3. Add the OAuth redirect URIs to the app's Valid OAuth Redirect URIs.
4. Make sure META_APP_SECRET/WHATSAPP_APP_SECRET is set. If it is missing the webhook returns HTTP 500 app secret not configured and messages arrive only after a manual sync.
5. Send a test message and confirm it appears in the inbox.

The endpoints /api/public/hooks/* are not provider webhooks. They are called only by the database jobs described in Scheduled Jobs and require the cron token.

Go-Live, Updates & Rollback

Go-live checklist

Updating to a new release

1. Read the changelog and back up the database.
2. Apply new migrations: npx supabase db push.
3. Rebuild and deploy the app with the same preset as before:
   • Docker: git pull && docker compose --env-file .env.production up -d --build
   • systemd: pull, npm ci --legacy-peer-deps, build with NITRO_PRESET=node-server, sudo systemctl restart abhiron
   • Netlify: npx netlify-cli deploy --prod (or push to the connected branch)
   • Vercel: push to the production branch or npx vercel --prod
   • Cloudflare: build, then npx wrangler deploy
4. Check health, then Release Readiness.

For zero-downtime on several servers, update them one at a time behind the load balancer, waiting for /api/public/health/ready on each.

Rolling back

• App: redeploy the previous release (previous image tag or commit; on Netlify and Vercel, promote an earlier deploy from the dashboard).
• Database: migrations only go forward. If a migration must be undone, restore the backup taken before it (Supabase Backups or point-in-time recovery), then redeploy the matching app version. Keep old and new app versions compatible with the current schema when you can.

Common problems on any host

Project Structure

abhiron/
├── 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.mts             # 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.

Workspace Customization

Workspace owners and admins open Settings → Customization → Customization to manage appearance and brand touchpoints. Visual Design groups Brand colors, Theme library, Other colors, Typography, Layout and Default mode. Brand Touchpoints groups Identity & logos, Login page, Email and Domain.

Brand colors has its own Save brand colors action; Use theme colors clears only the brand and accent overrides. In other sections, Save changes stores edits and Reset section to defaults asks for confirmation before immediately restoring the current section. A section reset leaves other sections unchanged.

Other colors contains optional background, text and app border overrides. Layout contains sidebar and dashboard colors, icon style and radius. Apply supabase/migrations/20261014130000_white_label_border_colors.sql before saving text or border overrides. Custom CSS and JavaScript are no longer accepted or injected into tenant sessions.

Email (SMTP) Configuration

{
  "host": "smtp.yourprovider.com",
  "port": 587,
  "username": "no-reply@yourdomain.com",
  "from_address": "no-reply@yourdomain.com",
  "from_name": "Abhiron",
  "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

Full release notes: changelog.html

Version 6.8.9 Current

October 26, 2026 · AI keys, social inbox, TikTok, YouTube and notifications.

Adds bring-your-own OpenAI/Gemini keys with a cost-tiered model catalog, Facebook/YouTube/LinkedIn/TikTok comments and TikTok direct messages in the Inbox, a TikTok DM chatbot, auto-renewing YouTube connections, unified module notifications and a responsive inbox. See downloadable v6.8.9 release notes.

Upgrade: Apply pending migrations through 20261026003000_byok_reuse_orphan_vault_secret.sql, set the TikTok Business and YouTube OAuth environment variables, and store the cron Vault secrets abhiron_cron_base_url and abhiron_cron_token.

Version 6.6.8

October 24, 2026 · Inbox, projects, dashboard, reminders and notifications.

Improves inbox layout and replies, project logos and descriptions, CRM/Project task tracking, dashboard data states, notification sounds and deep links. See downloadable v6.6.8 release notes for release highlights and review the upgrade note below for migration requirements.

Upgrade: Apply pending migrations to the linked Supabase project, including 20261024223000_activity_notifications.sql, for activity notifications and project deadline alerts.

Version 6.5.7

Released October 19, 2026 · Navigation, inbox, tenant reliability and deployment update.

Improves Global Search and deep links, Super Admin tenant creation, organization/workspace switching, inbox layout and timestamps, member identity resolution, compact navigation, Admin-configured payment-link currencies, Google Sheets integration discovery and single-domain Cloudflare deployment.

Upgrade: apply supabase/migrations/20261019150000_workspace_member_directory.sql. For Cloudflare, configure the three target values in local ENV, run npm run build, then npm run deploy:cloudflare.

Version 6.4.5

Released October 18, 2026 · Admin control-plane and platform governance update.

Unifies checkboxes on the shared accessible component, improves Email Templates and Feature Toggles, fixes workspace-invite permissions, and replaces AI Providers' native delete prompt with a shadcn dialog that removes deleted providers from the list and counters immediately. Also improves inbox media downloads, CRM and project tasks, customer notes, rich-text editing, attachment scheduling, Project Management and reminders.

Upgrade: apply supabase/migrations/20261018150000_auto_assign_role_on_workspace_invite.sql to fix existing invited-member permissions.

Unreleased: direct providers and Lovable Cloud removal

Current local work removes the active Lovable auth, connector and AI gateway paths, adds direct Google Workspace and Google/Microsoft Calendar OAuth, and replaces the Vite wrapper with direct project configuration. See the release notes for rollout and verification details. Live OAuth verification remains pending.

Version 6.3.2

Released October 14, 2026 · Customization and signed-in navigation update.

Workspace themes and white label controls are grouped under Customization. Owners and admins can edit brand colors, appearance, identity, login, email and domain settings. Reset section to defaults saves only that section after confirmation. The footer, workspace switcher and theme menu now follow dark mode colors.

Signed-in users go directly to the dashboard instead of the public landing, Features, Pricing, About or Contact pages. These marketing pages wait for browser auth before rendering to avoid the signed-in page flash. Their content is client-rendered, so review search indexing after deployment.

Upgrade: Apply supabase/migrations/20261014130000_white_label_border_colors.sql before saving text and border overrides. The Cloudflare deployment command now runs wrangler deploy against the generated Worker config. Verify the site and database after deployment.

Version 6.2.2

Released October 13, 2026 · Reliability and workspace integrity update.

Version 6.2.2 improves inbox and contact reliability, campaign and drip workflows, integration persistence, billing workspace isolation and production startup.

Inbox and contact reliability

• Resolve Messenger recipient names and search imported contacts correctly; refresh inbox messages after separate-page sends and on polling or focus.
• Clear incompatible conversation selections when changing channels or accounts, continue pagination through undated conversations, and preserve scalar contact names, phone numbers and email addresses during edits.

Campaigns and drip sequences

• Keep campaign dialog actions accessible, surface upload and queue-stat errors, refresh private media URLs at delivery, and show stalled-queue diagnostics.
• Add editable drip steps, checked activation, manual enrollment and future-contact welcome enrollment. Stage dispatch and enrollment updates transactionally with recipient eligibility checks and replay protection.

Integrations and OAuth

• Use the canonical application origin and reuse exact signed callback URLs for social OAuth authorization and token exchange.
• Add Google Workspace gateway administration, encrypted server-side credential persistence, workspace-scoped account restoration and checked connection actions. Scope installed integration metadata by user and workspace.

Billing integrity and workspace isolation

• Save invoice and quote headers and lines atomically, preserving original content when validation or insertion fails.
• Reject cross-workspace payment, document-line and product references at the database boundary. Recalculate both documents when moving payments or lines, restore payment states correctly and preserve shared deal totals.

Startup and compatibility

• Stop the retired service-worker registration and reload loop while preserving unrelated workers and caches. Render the root error page without requiring the failed root query provider.
• Correct the animation-module import, conversation account typing and integration dialog HTML semantics.

Upgrade and verification

• Apply both 20261012 migrations with the matching application build. Existing historical billing workspace mismatches require separate review; these guards do not automatically repair old records.
• Local verification passed 811 regression tests, 79 PostgreSQL checks, the full typecheck, the production build and four public browser smoke checks. Live OAuth, provider ingestion, campaign delivery and authenticated staging checks remain required.
• Automatic drip enrollment currently covers future-contact welcome journeys; birthday, anniversary, no-reply and stalled-lead event integrations remain separate work.

Version 6.0.0

• Google Workspace OAuth end-to-end via Lovable App User Connector (Gmail, Drive, Calendar, Contacts).
• Social Studio: TikTok & LinkedIn redirect-URI guidance surfaced in the channel settings panel.
• Messenger: unknown-contact name resolved via Graph API; fallback label "Messenger user <id>".
• Messenger: META_WEBHOOK_VERIFY_TOKEN diagnostic added to Meta App Status panel.
• WhatsApp template wizard: sticky footer — Submit to Meta button always visible.
• Shopify product sync upgraded to 250 products per page (API maximum).
• Billing documents: ZAR / non-USD workspace currency now displayed correctly on first load.
• Billing PDF print: iframe-clone approach replaces window.print() — no more blank pages.
• Booking module: Appointments tab opens by default; defaultValue prop correctly wired.
• Drip sequences: Pause / Resume / Activate per-sequence action buttons added.
• React Rules-of-Hooks correctness fixes across 7 components (useZonedDateFormatter, useTenantCurrency).
• Security — 9 backend correctness & security fixes: webhook workspace_id scoping, filter-injection via .or() fixed, cross-workspace WA status poisoning closed, scheduler double-dispatch race fixed, AI stream overrideConfig allowlisted, two hook handlers switched to supabaseAdmin, previewPlanChange auth gate added, coupon redemption race fixed, and realtime sales subscriptions workspace-filtered.
• Flow Builder & Chatbot Builder: sidebar auto-collapses when builders are open.
• Live Chat widget: session-reuse hardened; stale tokens start a fresh session instead of silently failing.
• Tenant accent-colour: accentForeground() always returns white — fixes illegible button labels on mid-tone brand colours.
• Demo mode: two realistic pre-seeded workspaces (Wellness Hub and Northbridge Goods) with 24 conversations and 72 messages total.

Version 5.0.0

Rebrand — Abhiron end to end

• App-wide sweep: 500+ retired-brand references replaced across 130+ files, including the SDK/CLI package name (@abhiron/sdk, @abhiron/cli), the outbound webhook signature header (x-abhiron-signature), the public API host, environment variable prefixes, the mobile app's bundle identifier and package name, the Docker image name, and the nginx site config.
• Fixed two pages left broken by an earlier, incomplete rebrand pass: the homepage meta title and the About page description had the brand name silently deleted rather than replaced — both now interpolate the brand name correctly.
• Canonical, share-link and Open Graph URLs that pointed at a placeholder preview address now point at the real production domain.
• Database rebrand: the platform-wide brand name setting, workspace white-label overrides, marketplace plugin publisher names, integration docs URLs and taglines, plugin category copy, a stray column default, and two pg_cron scheduled job names all now read Abhiron.
• The documentation portal — this page, the changelog, status and support pages, including the header logo mark — reads Abhiron throughout.
• Browser storage keys fold forward automatically from either retired brand namespace into the current one on first load (storage schema bumped), so active organization, workspace, favorites and preferences survive the upgrade with nothing for the user to redo.
• The legacy-brand template scanner (Super Admin → notification template preview) and the outbound-branding and database rebrand CI guards were updated to flag the retired names instead of the current one, so stale copy can't quietly creep back in.

Channel picker redesign

• The inbox “Reply via” channel switcher, the inbox's channel/account selector, the contact timeline's channel filter, and the “link a channel identity” dialog now render every channel as a colored icon chip instead of a flat, uncolored icon.
• The shared channel icon component gained a boxed chip variant plus coverage for Live Chat, Discord, Slack and Teams, so every picker in the app draws from one consistent, branded palette.

Release

• Version bumped to 5.0.0 across the app, this documentation portal, the release manifest, the downloadable PDF release notes, Docker Compose defaults, and the marketplace listing.

Version 4.8.8

• Security & RLS hardening: fixed a PostgREST filter-injection path, restricted billing_documents deletes, locked down public.settings, and tightened policies on payment_methods, billing_document_templates, and workspace_invitations so invite tokens are readable only by an admin or the invitee.
• SECURITY DEFINER functions audited and pinned to a fixed search_path, licensing logic isolated, and administrative functions refactored to verify the caller before doing privileged work.
• Rate-limiting restored for vcard_views, social channel tokens moved behind column-level grants, and an XSS sink in the public footer removed.
• New RLS regression suites: a DB-free static migration policy guard plus a live per-role harness that mints ephemeral users for every organization and workspace role, covering insert/update/delete on billing templates, invite-token privacy, and cross-tenant denial for every role.
• Automated security scans wired into CI so new findings block merges.
• Developer Center RBAC: navigation entries and sensitive actions are hidden for users without the required organization role — not just blocked by route guards — with requireOrgRole loader guards and integration tests asserting 403 behaviour.
• The 403 page now names the missing organization role and links to team & roles so users can request access.
• In-app organization switcher for the Developer Center and org-scoped API key management with selectable scopes.
• WhatsApp Forms (Meta Flows) end to end: publishing, a composer picker, and nfm_reply ingestion, plus centralized WhatsApp Catalog logic.
• Friendly error messages when publishing a form or sending from the composer fails, translating raw Meta and backend errors into actionable guidance.
• Organization settings load reactively, Super Admin brand leaks fixed, Billing portal empty states corrected, and Developer Center / Booking overview crashes resolved.
• Faster builds: incremental TypeScript compilation and query typing fixes cut warm typechecks to seconds.

Version 4.2.2

• The product is now Abhiron 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.
• Google Workspace OAuth unavailable — set the Google OAuth client ID and secret in Platform Settings → Integrations or the matching server environment variables. Register https://abhiron.com//api/public/integrations/google-workspace/callback in Google Cloud.
• TikTok / LinkedIn OAuth "redirect_uri mismatch" — register the exact URL https://<your-domain>/api/public/social/callback in the TikTok Developer Portal (Login Kit → Redirect URIs) and LinkedIn Developer App (Auth → Authorized redirect URLs) before starting the flow. The Social Studio settings panel displays the URL to copy.

Messenger / Meta Issues

• Messenger messages arrive but contacts show as UUID — the Graph API lookup for the sender's name is failing, usually because the Facebook Page token has insufficient permissions. Reconnect the Page under API Configurations → Messenger Accounts and ensure pages_messaging and public_profile are granted.
• Messenger real-time not working / webhook subscription fails — open API Configurations → Meta App Status and check the "META_WEBHOOK_VERIFY_TOKEN stored" row. If it shows fail, set META_WEBHOOK_VERIFY_TOKEN (any random string, e.g. openssl rand -hex 32) in your Supabase project secrets, then go to Meta Developers → your app → Webhooks → Page → Edit subscription and enter the same value in the Verify Token field.
• Meta App Status shows "Credentials accepted" but webhook check is warn — the webhook is not yet subscribed. In Meta Developers console, go to Webhooks → Page and subscribe to messages, messaging_postbacks, message_deliveries, and message_reads using the callback URL shown in the status panel.

E-Commerce Issues

• WooCommerce sync stops at 100 products — this is the WooCommerce REST API maximum per page; the sync will paginate automatically through all pages. If the count stays at exactly 100 after a sync, check the sync history — an error on page 2 would stop the loop early.
• Shopify sync shows fewer products than expected — if products are in a non-active status in Shopify (draft, archived) they are imported but marked is_active: false / status draft. Filter by "All" in the Products list to see them.
• Store test connection returns 401 — for Shopify, regenerate the access token in the Shopify admin (Apps → Private apps or Custom apps). For WooCommerce, ensure the consumer key has Read/Write permissions.

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.
• "Rendered more hooks than during the previous render" — a hook (useZonedDateFormatter, useTenantCurrency, etc.) is being called conditionally or inside a callback. Move the call to component top level, unconditionally, before any return or branching logic.

Billing & Print Issues

• Billing document shows wrong currency (always USD) — the workspace currency must be set in Settings → Workspace → Currency. After changing it, reload the billing-documents page; the hook syncs via useEffect on mount.
• PDF print produces blank page — ensure you are using the in-app Print button rather than the browser's Ctrl+P shortcut. The print helper clones the document into an iframe; if a Content-Security-Policy header blocks blob: URLs, relax the frame-src directive in your deployment's nginx/Caddy config.

Security & Multi-Tenant Issues

• Delivery receipts updating the wrong workspace's messages — upgrade to v6.2.2. The webhook processor now scopes all message_outbox and messages queries to workspace_id; previously a receipt arriving on one workspace's webhook could update rows belonging to a different tenant.
• Demo mode: data writes not blocked through workflow hooks — upgrade to v6.2.2. The workflow-queue and analyze.server hook handlers now use the centralised supabaseAdmin singleton that enforces the demo write guard.
• Non-admin users can call plan-preview endpoints — upgrade to v6.2.2. previewPlanChange now gates on assertOrgAdmin as its first operation.
• Limited coupon over-redeemed under high concurrency — upgrade to v6.2.2. The invoice engine now uses a single atomic conditional UPDATE to claim coupon uses, eliminating the read-modify-write race.
• Sales realtime tab refreshes for all workspaces — upgrade to v6.2.2. The use-sales-realtime hook now includes explicit workspace_id filters on all Supabase Realtime subscriptions.

Builder & Widget Issues

• Flow Builder or Chatbot Builder overlaps the sidebar on smaller screens — upgrade to v6.2.2. The application sidebar now auto-collapses when either builder is opened and restores when it is closed.
• Live Chat widget fails to reconnect after a page reload — upgrade to v6.2.2. The widget runtime now validates the visitor key and session token independently. A stale or mismatched token triggers a clean new session instead of a silent failure.
• Button labels / badge text appear near-black on brand-colour backgrounds — upgrade to v6.2.2. accentForeground() unconditionally returns #ffffff; the previous contrast calculation could produce dark text on mid-tone fills.

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 Abhiron 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.

Integrations

How do I connect Google Workspace? Apply the latest OAuth migrations and set APP_USER_CONNECTION_KEY_SECRET to a stable, base64-encoded random 32-byte key. Create a Google Cloud Web OAuth client and register https://abhiron.com//api/public/integrations/google-workspace/callback as an authorized redirect URI. Save its client ID and secret in Super Admin → Platform Settings → Integrations, or set GOOGLE_WORKSPACE_CLIENT_ID and GOOGLE_WORKSPACE_CLIENT_SECRET on the server. Then open Integrations → Google Workspace → Connect and approve consent. No gateway key is needed.

Which Google scopes does Abhiron request? gmail.readonly, gmail.send, drive.readonly, calendar, contacts.readonly, userinfo.email, and userinfo.profile. No write access to Drive or Contacts is requested.

Can I connect multiple Google accounts? One Google Workspace connection per workspace is supported. Disconnect the existing connection before connecting a different account.

How do I connect Booking calendars? Register https://abhiron.com//api/public/booking/google-calendar/callback in the Google Web OAuth client. For Microsoft 365, register https://abhiron.com//api/public/booking/microsoft-calendar/callback in Microsoft Entra, grant delegated User.Read and Calendars.ReadWrite, and set the server-only Microsoft client ID and secret. Set APP_ORIGIN and the stable encryption key before connecting. See the deployment guide for all variables and migration steps.

How do I connect TikTok or LinkedIn for Social Studio? In Social Studio → Channels, click Connect for TikTok or LinkedIn. First register the displayed redirect URI in the respective developer portal, then initiate the OAuth flow. See Troubleshooting → Auth Issues for the exact URI format.

E-Commerce

How many products can Abhiron sync from Shopify? There is no hard limit — the sync paginates through all pages at 250 products per request. A store with 5 000 products requires 20 API calls. The sync history shows pages fetched and total products imported.

Does Abhiron sync product variants? Currently the sync imports the first variant's price, SKU, and stock. Multi-variant support is planned.

Can I sync the same store to multiple workspaces? Yes — each store connection belongs to one workspace and uses a composite key (connection_id + external_id) so product IDs never collide across stores or workspaces.

Messenger

Why do Messenger contacts show as UUID or "Messenger user xxxx"? The Graph API lookup failed — most commonly because the Page token lacks public_profile permission. Reconnect the Page under API Configurations → Messenger Accounts. The fallback label "Messenger user <id>" was added in v6.2.2 so conversations are still identifiable even when the name lookup fails.

How do I set up the Messenger webhook? 1) Set META_WEBHOOK_VERIFY_TOKEN in your environment secrets. 2) In Meta Developers → your app → Webhooks → Page, enter https://<your-domain>/api/public/messenger/callback as the callback URL and the same token as Verify Token. 3) Subscribe to messages, messaging_postbacks, message_deliveries, message_reads. The Meta App Status panel shows a live health check for each step.

WhatsApp Templates

How do I submit a template to Meta? Open WhatsApp → Templates → New Template. Fill in all required fields (name, category, language, body), then click Submit to Meta in the sticky footer at the bottom of the dialog. The button is always visible — if you previously couldn't see it, upgrade to v6.2.2.

How long does Meta template approval take? Typically 10 minutes to 24 hours. You can track status in the Templates list — statuses are synced from Meta automatically.

Security & Multi-tenancy

Are webhook delivery receipts isolated per workspace? Yes, from v6.2.2. Every message_outbox and messages query in the webhook processor is scoped to the workspace derived from the incoming account. Prior versions lacked this scoping.

Can a non-admin user preview plan pricing? No, from v6.2.2. previewPlanChange now calls assertOrgAdmin as its first operation and returns 403 for non-admins.

Is the AI stream safe from model-injection via overrideConfig? Yes, from v6.2.2. The /api/ai/conversation-stream route allowlists only language and tone under overrideConfig; all other keys are silently dropped.

Builders & Live Chat

Why does the sidebar stay open when I open the Flow Builder? Upgrade to v6.2.2 — the sidebar now auto-collapses when the Flow Builder or Chatbot Builder is opened.

The Live Chat widget shows a blank chat panel on reload — what's wrong? This was a stale-token issue fixed in v6.2.2. The widget now validates the visitor key and token separately and starts a clean session when either is stale.

Button text on my accent-colour background is hard to read — why? This was a runtime CSS-variable conflict fixed in v6.2.2. accentForeground() now always returns white; the tenant theme engine darkens the fill colour via accentStrong() instead of darkening the text.

Demo Data

How do I explore the demo without generating test traffic? Fresh installations include pre-seeded demo workspaces. Log in with agent@demo.com to see "Wellness Hub" (12 conversations, WhatsApp/Messenger/Live Chat) or user@demo.com to see "Northbridge Goods" (12 conversations, e-commerce support scenarios). Both accounts are read-only in demo mode.

Can I reset the demo data? Re-apply the demo seed migration from supabase/seeds/demo.sql. This replaces all seeded rows without affecting production workspaces.

Marketing & Product Analytics

Abhiron 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.

Abhiron 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.

Abhiron 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-4 w-4) 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).

Abhiron Design System v1.0.0

The visual and interaction language for every Abhiron 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: 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 , 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, 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 Abhiron 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} />}
      />
      

Abhiron 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-control, 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.

Abhiron 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 (abhiron.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 (abhiron.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 (abhiron.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 (abhiron.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, GEMINI_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.

Abhiron 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.

Abhiron — 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.

Abhiron — 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.

Abhiron v1.0.0 — Typography System

Premium, enterprise-grade typography for the entire Abhiron 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: 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.

Abhiron · 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-.
• 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-control 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.