vibecarbon 0.1.0

package/README.md

@@ -0,0 +1,188 @@
+<p align="center">
+  <img src="carbon/src/client/assets/vibecarbon-logo-dark.svg" alt="Vibecarbon" width="500" />
+</p>
+
+<p align="center"><strong>Professional Grade SaaS Architecture & Starter Kit</strong></p>
+
+
+Full-stack, security-hardened, auto-everything apps in minutes.
+
+---
+
+## What is Vibecarbon?
+
+Vibecarbon is a full-stack SaaS starter that combines React 19, Vite, Tailwind v4, Hono, and self-hosted Supabase — with automated DevOps built in.
+
+Skip the choice between vendor lock-in and DIY infrastructure. Create web applications with authentication, billing, teams, email, blog, docs, i18n, and production deployment — without a dedicated DevOps engineer.
+
+Includes Docker Compose, Kubernetes, High-Availability with replication and failover, auto-scaling, and automated backups.
+
+---
+
+## Quick Start
+
+```bash
+# Create a new project
+npx vibecarbon create my-app
+
+# Start local development
+cd my-app
+npx vibecarbon up
+
+# Deploy an environment
+npx vibecarbon deploy
+
+# Tear down an environment
+npx vibecarbon destroy
+```
+
+> **Create for free, always. Pay to deploy.** `create`, `up`, `down`, and all local development are free forever. `deploy`, `destroy`, `backup`, `restore`, `failover`, and `scale` require a Diamond or Fullerene license — a one-time payment, no subscriptions, your servers.
+
+> Open source under AGPL v3. Generated project code is MIT — you own your app.
+
+---
+
+## Commands
+
+```text
+USAGE
+  npx vibecarbon <command> [options]
+
+DEV COMMANDS
+  create <project-name>    Create a new Vibecarbon project
+  up                       Start local development environment
+  down                     Stop local development environment
+  status                   Show project and deployment status
+  reset                    Reset local environment (removes all data)
+  configure                Configure external services (billing, OAuth, SMTP, etc.)
+  add <feature>            Add features (observability, redis)
+  remove <feature>         Remove features from a project
+  upgrade                  Upgrade infrastructure files to latest template
+
+DEPLOY COMMANDS
+  deploy [environment]     Deploy an environment (interactive picker for mode/region)
+  destroy [environment]    Tear down cloud environment
+  backup [environment]     Create, list, or download database backups
+  restore [environment]    Restore database from backup
+  failover [environment]   Initiate failover to standby region
+  scale [environment]      Scale worker nodes and instance sizes
+
+DEBUG COMMANDS
+  shell [environment]      Interactive bash with KUBECONFIG + cloud creds exported
+  diagnose [environment]   Dump full cluster state to ~/.vibecarbon/diag-*
+  console <node>           Open Hetzner's web VNC console for a node
+  access [subcommand]      Manage SSH + k8s-API operator-CIDR allowlist
+```
+
+---
+
+## Who It's For
+
+**Indie Hackers & Solopreneurs** — Ship faster, spend less, own everything. Launch a production grade MVP this weekend.
+
+**Startup Founders & Small Teams** — Enterprise architecture without the complexity. Multi-tenant organizations, auto-scaling, and high-availability when you need it.
+
+**Agencies & Consultancies** — One stack for every client project. Consistent, production-ready foundation with easy handoff.
+
+---
+
+## Key Benefits
+
+### Application Layer
+- Auth (email, OAuth, magic links, MFA) + brute force protection
+- Multi-provider billing (Stripe, Paddle, Polar) with subscriptions, checkout, and plan gating
+- Multi-tenant organizations with RBAC
+- Guided onboarding flow
+- Contact form with admin panel and email notifications
+- Newsletter with double opt-in, admin compose/send, and CSV export
+- File uploads via S3-backed storage (Hetzner Object Storage)
+- Transactional email (SMTP)
+- MDX blog, changelog, documentation, and legal pages (privacy policy, terms of service)
+- Client-side docs search with Cmd+K shortcut
+- Internationalization (i18n) with language switcher
+- Background jobs via pg_cron (zero extra infrastructure)
+- Product analytics (Plausible — cookie-free, GDPR-compliant)
+- Admin panel with user impersonation, notifications, jobs, contact, newsletter, and infrastructure dashboard
+- SEO (meta tags, sitemap, RSS feed)
+
+### Infrastructure
+- New environments in minutes
+- Security hardened from day one
+- Automated deployments via CI/CD
+- Auto-scaling (2-10+ replicas)
+- Multi-region high availability
+- VPS native (you own & control)
+- Auto backup & restore
+- Live monitoring & alerts (Grafana, Prometheus, Loki)
+- Zero vendor lock-in
+- Cost effective ($15-20/mo single region or compose HA, $30+/mo K8s multi-region HA)
+
+### Developer Experience
+- AI-ready codebase (Claude Code, Cursor, Windsurf, Copilot rules included)
+- 50+ Shadcn UI components
+- Full TypeScript across client and server
+- Biome linting/formatting, Vitest test suite
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Technical Guide](./docs/technical.md) | Architecture, code examples, API patterns, scripts |
+| [Design Guide](./docs/design.md) | Brand identity, visual design, UX principles |
+| [Test Suite](./docs/tests.md) | Test types, coverage, and how to run them |
+
+### Deployment Guides
+
+| Guide | Best For |
+|-------|----------|
+| [Hetzner Cloud](./docs/deploy-hetzner.md) | Cost-effective VPS hosting (single-node + HA) |
+| [Kubernetes README](./carbon/k8s/README.md) | K8s autoscaling, worker bounds configuration, HA cluster setup |
+
+### Integration Guides
+
+| Guide | Description |
+|-------|-------------|
+| [n8n Integration](./docs/integrations/n8n.md) | Workflow automation |
+| [Observability](./docs/integrations/observability.md) | Prometheus, Grafana, Loki |
+
+---
+
+## Performance
+
+<!-- BEGIN:perf-table -->
+<!-- Auto-generated by `pnpm test:e2e:batch` — do not edit by hand -->
+
+| Scenario | Cold deploy | Warm deploy | Backup | Restore | Scale | Destroy |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| compose | 4m 37s | 33.3s | 15.7s | 4m 12s | 6m 12s | 42.9s |
+| compose-ha | 7m 44s | 3m 45s | 16.1s | 8m 15s | 9m 49s | 41.7s |
+| k8s | 10m 24s | 2.3s | 15.9s | 12m 34s | 2m 57s | 3m 35s |
+| k8s-ha | 15m 27s | 53.5s | 15.6s | 17m 37s | 9m 9s | 2m 22s |
+
+_End-to-end wall-clock from the last fully-green e2e matrix run against real Hetzner Cloud infra · run `a2ec81a` on 2026-05-19 · methodology: [docs/tests.md](./docs/tests.md)._
+<!-- END:perf-table -->
+
+---
+
+## License & Terms
+
+The CLI is open source under the [GNU Affero General Public License v3.0](./LICENSE). **Building from source is free for any use, forever.**
+
+Using the distributed `npx vibecarbon` package requires a license for deployment commands:
+
+| Tier | Price | Who |
+|------|-------|-----|
+| **Graphite** | Free | Local dev — create, up, down, all add-ons |
+| **Diamond** | $149 lifetime | Full automation for indie hackers & startups |
+| **Fullerene** | $499 lifetime | Commercial license for agencies & enterprise |
+
+See [TERMS.md](./TERMS.md) for full usage terms. Generated project code is [MIT](./carbon/LICENSE) — you own your app outright.
+
+---
+
+## Support
+
+- GitHub Issues: [Report bugs or request features](https://github.com/hyperformant/vibecarbon/issues)
+- GitHub: [github.com/hyperformant/vibecarbon](https://github.com/hyperformant/vibecarbon)

package/carbon/.claude/hooks/task-completed-gate.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Quality gate: runs tests when test-maintainer marks a task complete.
+# Exit 0 = pass, exit 2 = block with feedback message.
+set -euo pipefail
+
+TEAMMATE=$(jq -r '.teammate_name // empty' 2>/dev/null || true)
+
+case "$TEAMMATE" in
+  test-maintainer)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+if ! pnpm test 2>&1; then
+  echo "Tests are failing. Fix them before marking the task complete."
+  exit 2
+fi

package/carbon/.claude/hooks/teammate-idle-gate.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Quality gate: runs lint + typecheck when backend-engineer or frontend-engineer go idle.
+# Exit 0 = pass, exit 2 = block with feedback message.
+set -euo pipefail
+
+TEAMMATE=$(jq -r '.teammate_name // empty' 2>/dev/null || true)
+
+case "$TEAMMATE" in
+  backend-engineer|frontend-engineer)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+ERRORS=""
+
+if ! pnpm lint 2>&1; then
+  ERRORS+="Lint errors found. Run 'pnpm lint' to see details.\n"
+fi
+
+if ! pnpm typecheck 2>&1; then
+  ERRORS+="Type errors found. Run 'pnpm typecheck' to see details.\n"
+fi
+
+if [ -n "$ERRORS" ]; then
+  echo -e "$ERRORS"
+  exit 2
+fi

package/carbon/.claude/settings.json

@@ -0,0 +1,29 @@
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
+  "hooks": {
+    "TeammateIdle": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/teammate-idle-gate.sh"
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/task-completed-gate.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/carbon/.cursor/rules/vibecarbon.mdc

@@ -0,0 +1,6 @@
+---
+description: Development rules for this full-stack TypeScript application
+globs: ["**/*.ts", "**/*.tsx", "**/*.sql"]
+---
+
+See [AGENTS.md](../../AGENTS.md) at the project root for all guidance (tech stack, commands, architecture, key patterns, and mandatory security rules). Follow every rule in the **Security Rules (Mandatory)** section — violations introduce real vulnerabilities.

package/carbon/.dockerignore

@@ -0,0 +1,57 @@
+# Dependencies
+node_modules
+npm-debug.log*
+pnpm-debug.log*
+
+# Build output
+dist
+
+# Environment files
+.env
+.env.local
+.env*.local
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git
+.gitignore
+
+# Docker
+Dockerfile*
+docker-compose*.yml
+.dockerignore
+
+# Testing
+coverage
+tests
+*.test.ts
+*.spec.ts
+__tests__
+
+# Documentation
+*.md
+LICENSE
+
+# Backup
+backup
+
+# Supabase volumes
+volumes
+
+# Infrastructure & tooling (not needed in app image)
+k8s
+supabase
+.claude
+.cursor
+.github
+.vibecarbon
+.vibecarbon.json

package/carbon/.env.example

@@ -0,0 +1,219 @@
+# =============================================================================
+# PROJECT CONFIGURATION
+# =============================================================================
+
+# Project name (used in Docker container names and network)
+PROJECT_NAME="your-project-name"
+
+# =============================================================================
+# SUPABASE CONFIGURATION
+# =============================================================================
+
+# Supabase URLs (configured automatically by docker-compose)
+SUPABASE_URL="http://localhost:8000"
+VITE_SUPABASE_URL="http://localhost:8000"
+
+# Supabase Keys (generated during bootstrap)
+SUPABASE_ANON_KEY="your-anon-key-here"
+VITE_SUPABASE_ANON_KEY="your-anon-key-here"
+SUPABASE_SERVICE_ROLE_KEY="your-service-role-key-here"
+
+# Site URL (your public domain)
+SITE_URL="http://localhost:5173"
+
+# =============================================================================
+# ADMIN CREDENTIALS
+# =============================================================================
+# Admin user with dashboard access (Grafana, N8N, Metabase, etc.)
+# Created during project setup via `vibecarbon create`
+# Your actual credentials are in .env.local (gitignored)
+
+ADMIN_EMAIL="admin@example.com"
+ADMIN_PASSWORD="your-password-here"
+
+# =============================================================================
+# OAUTH PROVIDERS (optional)
+# =============================================================================
+# Configure these in Supabase Studio > Authentication > Providers
+
+GOOGLE_ENABLED="false"
+GOOGLE_CLIENT_ID=""
+GOOGLE_CLIENT_SECRET=""
+
+MICROSOFT_ENABLED="false"
+MICROSOFT_CLIENT_ID=""
+MICROSOFT_CLIENT_SECRET=""
+MICROSOFT_TENANT_ID=""
+
+# =============================================================================
+# SMTP (optional - used by both Supabase Auth and the app)
+# =============================================================================
+# Get SMTP credentials from your email provider (e.g., Resend, Mailgun, AWS SES).
+# These credentials are shared: Supabase Auth uses them for auth emails (password
+# reset, verification) and the app uses them for transactional emails
+# (welcome, invite, billing).
+
+SMTP_HOST=""
+SMTP_PORT="587"
+SMTP_USER=""
+SMTP_PASS=""
+SMTP_ADMIN_EMAIL=""
+SMTP_SENDER_NAME="Vibecarbon"
+
+# =============================================================================
+# EXTERNAL SERVICES (optional)
+# =============================================================================
+
+# Billing provider: "stripe" (default), "paddle", or "polar"
+BILLING_PROVIDER="stripe"
+
+# Stripe (default provider)
+STRIPE_SECRET_KEY=""
+STRIPE_WEBHOOK_SECRET=""
+STRIPE_PRICE_STARTER=""
+STRIPE_PRICE_PRO=""
+
+# Paddle (alternative provider -- set BILLING_PROVIDER="paddle" to use)
+# API key from Paddle dashboard > Developer Tools > Authentication
+# Use sandbox for testing, production for live
+PADDLE_API_KEY=""
+PADDLE_WEBHOOK_SECRET=""
+PADDLE_ENVIRONMENT="sandbox"
+PADDLE_PRICE_STARTER=""
+PADDLE_PRICE_PRO=""
+
+# Polar (alternative provider -- set BILLING_PROVIDER="polar" to use)
+# Access token from Polar dashboard > Settings > Developer
+POLAR_ACCESS_TOKEN=""
+POLAR_WEBHOOK_SECRET=""
+POLAR_ORGANIZATION_ID=""
+POLAR_PRICE_STARTER=""
+POLAR_PRICE_PRO=""
+
+# =============================================================================
+# OBSERVABILITY (optional - enabled per-environment)
+# =============================================================================
+# Prometheus + Grafana + Loki stack
+# Enable with: docker compose -f docker-compose.yml -f docker-compose.observability.yml up -d
+
+GRAFANA_ADMIN_USER="admin"
+GRAFANA_ADMIN_PASSWORD="your-grafana-password-here"
+GRAFANA_URL="http://localhost:3002"
+
+# =============================================================================
+# OPTIONAL SERVICES (for admin dashboard visibility)
+# =============================================================================
+# These control which services appear in the admin dashboard
+# Set automatically during project creation based on CLI flags
+
+VITE_N8N_ENABLED="false"
+VITE_METABASE_ENABLED="false"
+VITE_OBSERVABILITY_ENABLED="false"
+
+# =============================================================================
+# N8N WORKFLOW AUTOMATION (optional)
+# =============================================================================
+# Enable with: docker compose -f docker-compose.yml -f docker-compose.n8n.yml up -d
+# Access: http://n8n.localhost (requires super_admin role)
+
+N8N_DB_PASSWORD="your-n8n-db-password-here"
+N8N_ENCRYPTION_KEY="your-n8n-encryption-key-here"
+N8N_HOST="n8n.localhost"
+N8N_PROTOCOL="http"
+N8N_WEBHOOK_URL="http://n8n.localhost/"
+N8N_EDITOR_BASE_URL="http://n8n.localhost/"
+
+# =============================================================================
+# METABASE ANALYTICS (optional)
+# =============================================================================
+# Enable with: docker compose -f docker-compose.yml -f docker-compose.metabase.yml up -d
+# Access: http://metabase.localhost (requires super_admin role)
+
+METABASE_DB_PASSWORD="your-metabase-db-password-here"
+METABASE_SITE_URL="http://metabase.localhost"
+
+# =============================================================================
+# S3 OBJECT STORAGE (required for production)
+# =============================================================================
+# Hetzner Object Storage for durable file storage and backups
+# Create buckets and access keys at: https://console.hetzner.cloud/
+
+# Primary region bucket (nbg1)
+S3_PRIMARY_ENDPOINT="https://nbg1.your-objectstorage.com"
+S3_PRIMARY_BUCKET="your-project-storage-nbg1"
+S3_PRIMARY_REGION="nbg1"
+
+# Standby region bucket (hel1)
+S3_STANDBY_ENDPOINT="https://hel1.your-objectstorage.com"
+S3_STANDBY_BUCKET="your-project-storage-hel1"
+S3_STANDBY_REGION="hel1"
+
+# Shared credentials (same access key works across regions in same project)
+S3_ACCESS_KEY=""
+S3_SECRET_KEY=""
+
+# Sync interval in minutes (default: 5)
+S3_SYNC_INTERVAL="5"
+
+# =============================================================================
+# PORT CONFIGURATION (for running multiple projects)
+# =============================================================================
+# Use DEV_PORT_OFFSET to shift all ports by a fixed amount when running
+# multiple vibecarbon projects simultaneously on the same machine.
+#
+# Example: DEV_PORT_OFFSET=100 shifts ports:
+#   - Vite: 5173 → 5273
+#   - API: 3000 → 3100
+#   - DB: 5432 → 5532
+#   - Kong: 8000 → 8100
+#   - Traefik: 80 → 180
+#   - Grafana: 3002 → 3102
+#   - Prometheus: 9190 → 9290
+#   - Loki: 3100 → 3200
+
+DEV_PORT_OFFSET="0"
+
+# Override individual ports (takes precedence over offset):
+# DEV_VITE_PORT="5173"
+# DEV_API_PORT="3000"
+# DEV_DB_PORT="5432"
+# DEV_KONG_PORT="8000"
+# DEV_TRAEFIK_PORT="80"
+# DEV_GRAFANA_PORT="3002"
+# DEV_PROMETHEUS_PORT="9190"
+# DEV_LOKI_PORT="3100"
+
+# =============================================================================
+# INTERNATIONALIZATION
+# =============================================================================
+# Enabled languages live in app_settings.enabled_languages (admin Settings →
+# Localization card), not in this env file. Translations live in
+# src/client/locales/<code>.json. Built-in: en, es, fr, de, pt.
+
+# =============================================================================
+# ANALYTICS (optional - Plausible)
+# =============================================================================
+# Privacy-friendly analytics. Works with Plausible Cloud or self-hosted.
+# Sign up at https://plausible.io or self-host: https://plausible.io/docs/self-hosting
+#
+# PLAUSIBLE_DOMAIN: your site's domain (e.g., "myapp.com")
+# PLAUSIBLE_SCRIPT_URL: script URL (default: Plausible Cloud)
+#   - Cloud: https://plausible.io/js/script.js
+#   - Self-hosted: https://analytics.yourdomain.com/js/script.js
+
+VITE_PLAUSIBLE_DOMAIN=""
+VITE_PLAUSIBLE_SCRIPT_URL="https://plausible.io/js/script.js"
+
+# =============================================================================
+# ENVIRONMENT
+# =============================================================================
+
+NODE_ENV="development"
+PORT="3000"
+
+# Environment name shown in Super Admin (set automatically during deployment)
+# Values: development, qa, staging, prod, etc.
+VITE_ENVIRONMENT="development"
+
+# App version shown in Super Admin (set automatically during deployment)
+VITE_APP_VERSION="0.1.0"

package/carbon/.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+# {{PROJECT_NAME}} Development Rules
+
+See [AGENTS.md](../AGENTS.md) at the project root for all guidance (tech stack, commands, architecture, key patterns, and mandatory security rules). Follow every rule in the **Security Rules (Mandatory)** section — violations introduce real vulnerabilities.