⚖️ Lexvail Intelligence

The AI-Native Operating System for Modern CA Firms.

Lexvail is an enterprise-grade, multi-tenant SaaS platform for Chartered Accountant firms in India. It combines AI-powered compliance monitoring, proactive risk intelligence, and WhatsApp-based client communication into a single practice operating system — shifting CA firms from reactive record-keeping to proactive risk management.

---

Table of Contents

• Features
• Tech Stack
• Architecture
• Getting Started
• Environment Variables
• Available Scripts
• API Reference
• Security
• Deployment
• Contributing

---

✨ Features

🎛️ Overview — Control Hub

A centralized command center providing a bird's-eye view of firm-wide health, average trust scores across all clients, and critical system logs.

📈 Risk Pulse

A real-time volatility feed with trend sparklines that tracks clients whose Trust Scores dropped. Identifies filing misses and GSTIN anomalies before they trigger departmental notices.

🔵 Trust Gauge — AI Compliance Index

A visual, high-fidelity gauge for individual clients powered by Gemini AI. Explains why a score is low (e.g., "Missing December GSTR-1") and provides an immediate mitigation plan.

🔒 Verification Traps

Monitors clients on "Soft-Lock" protocol due to missing critical documents (UDYAM certificates, GST certificates, Board Resolutions) and tracks resolution progress dynamically.

🏭 45-Day MSME Tracker (Section 43B(h))

A specialized radar for vendor payment compliance. Flags invoices nearing the 45-day threshold, calculates potential tax disallowance penalties, and generates WhatsApp "Nudge" alerts for clients.

📋 Audit Intelligence Logs

A cryptographically verifiable, non-deletable event stream of every action taken by AI agents and staff members — ensuring complete transparency and audit readiness.

👥 Client Portfolio Node

Advanced management of all client GSTIN IDs, trust indices, and active filing operations with interactive status tracking.

🤖 VEX AI Chatbot — Dual-Mode WhatsApp Bot

An intelligent WhatsApp assistant that operates in two modes:

• Staff (Vex) Mode: Intent-aware command routing — query client status, trigger MSME scans, draft notices.
• Guard Mode: Client-facing compliance checks, VIP bypass, regional language auto-detection, and document upload verification.

📄 Notice Management & AI Response Drafting

Upload tax notices (GST, Income Tax), generate AI-powered draft responses with legal case citations via Gemini, and manage an approval workflow (Draft → Approved → Sent).

🔗 Tally ERP Integration

Real-time sync with Tally accounting software for bank statement reconciliation, invoice tracking, and transaction synchronisation.

📁 Document Management

Upload documents to Supabase Storage, extract data with Gemini Vision (GSTIN, ARN, filing status), verify authenticity, and manage document categorization.

🌐 Client Self-Service Portal

A dedicated portal for clients to upload documents, view compliance status, and communicate securely — with role-appropriate data isolation.

---

🛠️ Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router) + TypeScript
UI / Styling	Tailwind CSS + Framer Motion
Icons	Lucide React
Backend / DB	Supabase (Auth + PostgreSQL + Storage)
AI Engine	Google Gemini 1.5 Flash (intent analysis + vision)
Messaging	Twilio WhatsApp API
Rate Limiting	Upstash Redis
Validation	Zod
PDF Export	jsPDF + jsPDF-AutoTable
HTTP Client	Axios
Google APIs	Google Drive, Google Calendar
Testing	Vitest + React Testing Library
Linting	ESLint + Prettier
Deployment	Vercel (with cron jobs)

---

🏗️ Architecture

WhatsApp Message → Twilio → /api/webhook/whatsapp
       │
       ▼
  Phone Lookup (normalisation + case fallback)
       │
       ├─ Staff phone → Vex Command Mode (intent-aware routing)
       │
       └─ Client phone → Guard Mode
              │
              ├─ Kill-switch check (bot_active = false → forward to CA)
              ├─ VIP bypass (is_vip = true → warm response + CA alert)
              ├─ Language auto-detect → regional translation
              └─ Document uploads → AI verification → saved as DRAFT

Security layers:

• Row-Level Security (RLS) enforced at the database layer — zero cross-firm data leakage.
• supabaseAdmin used only in server-side webhook/cron routes; supabase (RLS-enforced) used for all client-facing queries.
• Twilio webhook always returns HTTP 200 with empty TwiML to prevent infinite retry storms.

Directory Structure

├── app/                  # Next.js App Router (pages + API routes)
│   ├── api/              # Backend routes (clients, notices, cron, webhook, vex …)
│   ├── dashboard/        # Main CA dashboard
│   ├── portal/           # Client self-service portal
│   └── page.tsx          # Auth / login
├── components/
│   ├── dashboard/        # Dashboard tabs & widgets
│   └── ui/               # Shared UI primitives (Button, Modal, Input …)
├── lib/
│   ├── services/         # Core business logic (database, gemini, twilio, trust …)
│   ├── security/         # Zod schemas, prompt-prison, GSTIN validator
│   ├── types/            # Global TypeScript types
│   └── constants/        # App-wide constants & intent definitions
├── supabase/             # SQL schema + RLS policies
└── tests/                # Vitest unit tests + webhook integration tests

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• A Supabase project
• A Google AI Studio API key (Gemini)
• A Twilio account with a WhatsApp-enabled number (optional for local dev)

Installation

# 1. Clone the repository
git clone https://github.com/ch1n-may/ca-app.git
cd ca-app

# 2. Install dependencies
npm install

# 3. Configure environment variables
cp .env.example .env.local
# Edit .env.local — see Environment Variables section below

# 4. Start the development server (Turbopack)
npm run dev

Visit http://localhost:3000.

---

🔐 Environment Variables

Variable	Required	Description
NEXT_PUBLIC_SUPABASE_URL	✅	Your Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	✅	Supabase anonymous (public) key
SUPABASE_SERVICE_ROLE_KEY	✅	Supabase service role key (server only)
GEMINI_API_KEY	✅	Google Gemini AI API key
TWILIO_ACCOUNT_SID	✅	Twilio account SID
TWILIO_AUTH_TOKEN	✅	Twilio auth token
TWILIO_WHATSAPP_FROM	✅	Twilio WhatsApp sender number (e.g. whatsapp:+14155238886)
NEXT_PUBLIC_BASE_URL	✅	Public base URL (e.g. https://yourapp.vercel.app)
CRON_SECRET	✅	Secret token for authenticating cron job requests
UPSTASH_REDIS_REST_URL	⬜	Upstash Redis URL (rate limiting)
UPSTASH_REDIS_REST_TOKEN	⬜	Upstash Redis token (rate limiting)
GOOGLE_CLIENT_ID	⬜	Google OAuth client ID (Drive / Calendar)
GOOGLE_CLIENT_SECRET	⬜	Google OAuth client secret

---

📜 Available Scripts

Script	Description
npm run dev	Start development server with Turbopack
npm run build	Build for production
npm start	Start production server
npm run lint	Run ESLint
npm run type-check	TypeScript type validation (tsc --noEmit)
npm test	Run Vitest unit tests
npm run test:ui	Run Vitest with interactive UI
npm run test:coverage	Run tests with coverage report
npm run test:integration	Run webhook integration simulation
npm run format	Format all files with Prettier
npm run format:check	Check formatting without writing

---

🔌 API Reference

Clients

Method	Endpoint	Description
GET/POST	/api/clients	List all clients / create a client
GET/PUT/DELETE	/api/clients/[id]	Get, update, or delete a client
POST	/api/clients/bulk	Batch import clients
POST	/api/clients/broadcast	Send broadcast WhatsApp message
POST	/api/clients/sync-deadlines	Sync filing deadlines

Notices

Method	Endpoint	Description
GET	/api/notices	List tax notices
GET/POST	/api/notices/drafts	Manage AI-generated draft responses
POST	/api/notices/alerts/msme	Send MSME payment alerts

Documents

Method	Endpoint	Description
POST	/api/documents/verify	Verify uploaded document via Gemini Vision
POST	/api/documents/sign	Digitally sign a document

Client Portal

Method	Endpoint	Description
POST	/api/portal/upload	Client document upload
POST	/api/portal/verify	Verify portal submission
POST	/api/portal/dispatch	Dispatch verified documents

Integrations

Method	Endpoint	Description
POST	/api/webhook/whatsapp	Twilio WhatsApp webhook (Vex/Guard bot)
GET/POST	/api/tally	Tally ERP sync
POST	/api/vex	VEX AI agent direct query

Cron Jobs (Vercel Scheduled)

Endpoint	Schedule	Description
/api/cron/msme-radar	Daily 3:30 AM UTC	Scan for MSME payment violations
/api/cron/risk-report	Weekly	Generate firm risk summary
/api/cron/newsletter	Monthly	Client compliance newsletter
/api/cron/cleanup-portal	Weekly	Remove stale portal sessions

---

🛡️ Security

• Row-Level Security (RLS): Deep isolation at the database layer — clients can only query their own records via auth.uid() checks.
• PII Masking: Automatic redaction of PAN, GSTIN, and CIN in immutable forensic logs.
• Forensic Audit Ledger: Cryptographically tracked, non-deletable action stream.
• Content Security Policy (CSP): Strict headers preventing XSS, clickjacking, and data injection attacks.
• HSTS: 1-year preload with includeSubDomains.
• Rate Limiting: Upstash-based rate limiting on all public API routes.
• GSTIN Checksum Validation: Every tax ID is validated via the 15-character checksum algorithm before processing.
• No Production Source Maps: Source code is not exposed in production builds.
• Notice DRAFT Gate: AI-generated notice responses are always saved as DRAFT — a CA must manually approve before any reply is sent to the tax department.

---

🚢 Deployment

Lexvail is optimised for Vercel.

# Deploy to production
vercel --prod

Cron jobs are configured in vercel.json and run automatically on the defined schedules. Ensure all environment variables listed above are configured in your Vercel project settings.

For a full step-by-step deployment walkthrough, see LEXVAIL_SETUP.md.

---

🤝 Contributing

1. Fork the repository and create a feature branch (git checkout -b feature/my-feature).
2. Make your changes and ensure all tests pass (npm test).
3. Run the type checker (npm run type-check) and linter (npm run lint).
4. Open a pull request with a clear description of your changes.

---

Version 2.1.0 · Built for Indian CA Excellence · Lexvail Intelligence