Velobase Harness

An open-source framework that takes your AI app from code to cash.

Help us reach more developers — Star this repo!

中文 · Quick Start · Docs · Architecture

Ship fast. Get paid faster.

In the vibe-coding era, everyone can build. But almost none of them make a dollar from it.

We went from the same problem to 8-figure ARR. The secret was not a better product — it was the growth and monetization infrastructure behind it. We just open-sourced all of it. That is Velobase Harness.

Why Velobase Harness

An open-source AI SaaS framework, extracted from a product doing 8-figure ARR. Unlike every other boilerplate, it does not stop at shipping — it covers the full path from build to revenue.

📡 Ad Attribution — Server-side tracking that tells you which ads actually convert. Google Ads offline conversion upload, X pixel, PropellerAds.

🤝 Affiliate Engine — Financial-grade double-entry ledger, refund clawback, USDT cashout. Your users become your salesforce.

💳 Usage-Based Billing — Full credits lifecycle, subscriptions, multi-currency, metering dashboard, and @velobaseai/billing integration. Charges from day one.

📧 Email Outreach — A/B testing, scheduled campaigns, dual-provider failover. Brings people back automatically.

Plus: Auth & anti-abuse · Multi-LLM AI chat · 11 BullMQ background workers · Stripe & crypto payments · PostHog analytics · Affiliate/Referral · Promo codes · Admin dashboard · Pluggable modules (toggle via env vars) · Docker, Kubernetes & GitOps docs

We checked every boilerplate on the market. They help you build. We help you build AND make money.

Quick Start

Option A: Self-hosted local development

pnpm install
cp .env.example .env
pnpm docker:db:up
pnpm db:push
pnpm db:seed
pnpm dev:all

pnpm dev:all starts the combined local runtime: Web on :3000, API on :3002, and Worker on :3001.

You can also split processes across terminals:

pnpm dev
pnpm api:dev
pnpm worker:dev

Option B: Deploy with Velobase Cloud

Velobase Cloud uses this repository as the default application template for Launchpad-created projects.

1. Create a project in Velobase Cloud or start from Launchpad.
2. Cloud creates a GitHub repository from the velobase-harness template and provisions PostgreSQL, Redis, R2, Kubernetes resources, domain, and deploy API credentials.
3. Add VELOBASE_API_KEY to GitHub Actions secrets.
4. Push to main.
5. GitHub Actions calls GET https://api.velobase.cloud/api/v1/deploy/config, builds and pushes the Docker image, then calls POST https://api.velobase.cloud/api/v1/deploy.
6. Visit https://{subdomain}.velobase.app after deployment succeeds.

Application requirements for Cloud deployment:

• A root Dockerfile
• HTTP listening on port 3000
• Environment variables read from runtime env
• Prisma migration through prisma migrate deploy
• A GET /healthz readiness endpoint

Architecture

flowchart TB
  browser[Browser] --> nextApp[Next.js Web]
  nextApp --> trpc[tRPC Routers]
  external[External Integrations] --> hono[Hono API]
  trpc --> services[Domain Services]
  hono --> services
  services --> db[(PostgreSQL)]
  services --> redis[(Redis)]
  services --> events[Event Bus]
  events --> modules[Pluggable Modules]
  worker[BullMQ Worker] --> redis
  worker --> services
  modules --> growth[Growth Operations]

The same codebase can run as one process or as separate services:

SERVICE_MODE supports all, web, api, worker, and combinations such as web,api.

From Template to Cloud

flowchart LR
  idea[Product Idea] --> launchpad[Velobase Launchpad]
  launchpad --> repo[GitHub Repo from Harness]
  launchpad --> cloud[Velobase Cloud Resources]
  repo --> ide[IDE Agent Development]
  ide --> push[Git Push]
  push --> actions[GitHub Actions]
  actions --> deployApi[Velobase Deploy API]
  deployApi --> liveApp[Live SaaS App]

Launchpad generates an IDE prompt that tells the AI agent how to use the Harness docs, where to implement product features, how to keep framework boundaries intact, and how to push changes back for Cloud deployment.

Documentation

Legacy Chinese-first docs remain available during migration, including FRAMEWORK_GUIDE.md, docs/integration-guide.md, and docs/ai-completion-checklist.md.

Star History

Replace velobase/velobase-harness if your public repository lives under a different owner/name.

Project Structure

src/
├── app/              # Next.js pages and API routes
├── api/              # Standalone Hono API entry
├── config/           # Module configuration
├── modules/          # Product modules and templates
├── server/           # Auth, billing, order, events, modules, features
├── workers/          # BullMQ queues and processors
├── components/       # Shared UI components
└── analytics/        # PostHog and ads event tracking

Quality Commands

pnpm lint
pnpm typecheck
pnpm check
pnpm format:check
pnpm build

package.json does not define a general unit-test script in this template. Service-mode smoke coverage lives in docker-compose.test.yml and scripts/test-service-mode.mjs.

License

Private - All rights reserved.