VELO - Tactical Enterprise AI CRM

Engineered by Getabalew Kemaw

VELO is a production-grade CRM that unifies Gmail and Telegram leads into one inbox, prioritizes them with AI, and gives business owners clear analytics, deal tracking, and reminders. It is built headless, so businesses can plug it into any website without migration.

This repository contains:

• apps/client - Next.js frontend
• apps/server - Express + Prisma backend
• packages - shared tooling (if any)

Problem We Solve

Small businesses lose revenue because messages are scattered across Telegram, Instagram, WhatsApp, Email, and Website. Owners are forced to tab-switch, guess what to reply to first, and manually track follow-ups. The "golden minute" after a lead arrives determines conversion, but most CRMs show data after the fact, not while decisions are being made.

How VELO Solves It (Step-by-Step Build)

1. Capture signals
   • Gmail and Telegram are connected and unified into one inbox.
2. Normalize messages
   • Threads, messages, and lead records are created consistently.
3. Clean noisy email content
   • Unsubscribe blocks, footers, and signatures are removed.
4. Auto-triage with AI
   • Gemini scores priority (low/medium/high).
5. Alert the owner
   • High-priority or stale high-priority leads trigger in-app notifications.
6. Track outcomes
   • Deals, pipeline value, win rate, and SLA metrics are computed.
7. Act with context
   • AI explains messages and answers lead-specific questions.

What It Does

1) Multi-Business Ownership (No Cross-User Leakage)

• One user can create multiple businesses from a single account.
• Leads are scoped to the authenticated owner, so users never see other users' leads.
• Each lead is tied to a business and to the owner who created that business.

2) Unified Lead Inbox (Zero Lead Leakage)

• Every message from Website, Email, Telegram, WhatsApp, and Instagram lands in one unified dashboard.
• Reply once and the response goes back to the customer on their original platform.
• Gmail supports threading and message history.
• Telegram supports bot webhook ingestion.
• WhatsApp and Instagram are planned (beta).

3) AI-Powered Lead Prioritization (Gemini 2.5 Flash)

• AI filters out "Hi" and "Hello" fluff and highlights leads ready to buy.
• Every inbound lead is auto-triaged (low/medium/high).
• High priority leads trigger notifications immediately.
• On-demand AI tools:
  • Explain the lead message
  • Chat with AI about the lead
  • Re-run triage

4) Smart Lead Tracking

• Tag leads as contacted, ignored, or keep them as new so nothing gets lost.
• Status is visible in the inbox and powers analytics and reminders.

5) Speed-to-Lead Advantage

• Automated reminders and unified replies reduce response time.
• In-app alerts for:
  • New lead created
  • High priority lead detected
  • High priority lead not contacted after 1 hour
• Worker polls periodically and creates reminders.

6) Deal Pipeline and Analytics

• Track deals from qualified to won/lost with clear stages.
• Analytics API includes:
  • Executive KPIs
  • Response time SLA
  • Productivity stats
  • Source ROI
  • Pipeline value / revenue / win rate

7) Clean Email Parsing

• Gmail email bodies are cleaned to remove signatures, unsubscribe links, and long footers.

8) Product-Linked Conversations (Planned)

• Connect website products directly.
• When a lead asks a question, you immediately know which product they are interested in.

Tech Stack

• Frontend: Next.js 16 (App Router), Tailwind, Framer Motion, Recharts
• Backend: Express 5 + TypeScript
• ORM: Prisma + PostgreSQL
• Auth: Better-Auth
• AI: Google Gemini SDK
• Integrations: Gmail OAuth + Pub/Sub, Telegram Bot webhooks

Environment Variables

Server (apps/server/.env)

DATABASE_URL=postgres://user:pass@localhost:5432/CRM
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=...
GMAIL_PUBSUB_TOPIC=...
WEBHOOK_BASE_URL=...
TELEGRAM_WEBHOOK_SECRET=...
GEMINI_API_KEY=...
GEMINI_MODEL=gemini-2.5-flash

Client (apps/client/.env.local)

NEXT_PUBLIC_API_URL=http://localhost:4000

Local Setup

git clone https://github.com/getabalewKemaw/FUTURE_FS_02
cd FUTURE_FS_02

cd apps/server
npm install
npx prisma migrate dev
npm run dev

cd ../client
npm install
npm run dev

Key API Endpoints

Leads

• GET /api/leads (supports status, businessId, page, limit)
• GET /api/leads/:id
• PATCH /api/leads/:id/status
• PATCH /api/leads/:id
• POST /api/leads/:id/ai-explain
• POST /api/leads/:id/ai-triage
• POST /api/leads/:id/ai-chat

Analytics

• GET /api/analytics/overview

Deals

• GET /api/deals
• POST /api/deals
• PATCH /api/deals/:id
• DELETE /api/deals/:id

Notifications

• GET /api/notifications
• PATCH /api/notifications/:id/read
• POST /api/notifications/read-all

Showcase

Strategic Dashboard	Neural Authentication
	Watch Auth Demo

• Business Creation Node: Watch Video
• Neural Walkthrough (Full): [Watch SamFull Demo](apps/client/public/docs/samfull demo.mp4)

Notes

• AI explanations are not stored. Priority is saved on the lead.
• Lead list and detail access is owner-scoped.
• High priority reminders run every ~5 minutes.

Roadmap / TODO

• Multi-user collaboration (teams and roles)
• Per-business lead filters in UI (select business on Leads page)
• SLA dashboards for response time by team member
• Source ROI configuration UI (cost inputs per channel)
• Notification rules editor (custom thresholds and schedules)
• Web push / email notifications (outside in-app)
• Lead tagging and segment filters
• Additional channels (WhatsApp, Instagram) - beta
• Product-linked conversations

Call For Contributors

• Developers / AI Enthusiasts - help refine the intelligence behind the system
• Early Adopters - test the beta and provide real feedback
• Designers - help craft the cleanest CRM dashboard experience

License

MIT