vibecarbon 0.1.0

package/carbon/Dockerfile

@@ -0,0 +1,98 @@
+# syntax=docker/dockerfile:1
+# check=skip=SecretsUsedInArgOrEnv
+
+# Base image can be overridden for Turbo Layer Caching
+# Default is the standard node image
+ARG BASE_IMAGE=node:22-alpine3.23
+FROM ${BASE_IMAGE} AS builder
+
+# Build args for Vite (baked into client bundle at build time).
+# The anon key is a public value — it ships in the JS bundle to every browser.
+ARG VITE_PROJECT_NAME
+ARG VITE_SUPABASE_URL
+ARG VITE_SUPABASE_ANON_KEY
+# Optional service feature flags (set to "true" when the service is enabled)
+ARG VITE_N8N_ENABLED
+ARG VITE_METABASE_ENABLED
+ARG VITE_REDIS_ENABLED
+ARG VITE_OBSERVABILITY_ENABLED
+# Routing mode: 'subdomain' (compose) or 'path' (k8s)
+ARG VITE_ROUTING_MODE
+# Analytics (optional — empty by default, no tracking unless configured)
+ARG VITE_PLAUSIBLE_DOMAIN
+ARG VITE_PLAUSIBLE_SCRIPT_URL
+
+# Ensure pnpm is available (runtime base image already has it, standard node image doesn't)
+RUN command -v pnpm >/dev/null 2>&1 || npm install -g pnpm@9
+
+WORKDIR /app
+
+# Install dependencies first so the layer caches independently of source.
+# .dockerignore excludes node_modules, so this always runs against a clean
+# /app — no need for a defensive `if [ ! -d node_modules ]` check.
+COPY package.json pnpm-lock.yaml ./
+RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
+    pnpm install --frozen-lockfile
+
+# Copy application code
+COPY tsconfig.json tsconfig.server.json biome.json vite.config.ts components.json ./
+COPY content/ ./content/
+COPY scripts/ ./scripts/
+COPY src/ ./src/
+
+# Build client (Vite) and server (TypeScript). Split into TWO RUNs so an
+# edit that only touches src/server/ doesn't bust the Vite client cache
+# (and vice versa). The COPY src/ above still cache-busts both on any
+# src change, but with split RUNs the slower of the two (Vite) can land
+# from cache when only the other side moved.
+# VITE_ env vars are available from ARGs during build
+ENV VITE_PROJECT_NAME=$VITE_PROJECT_NAME
+ENV VITE_SUPABASE_URL=$VITE_SUPABASE_URL
+ENV VITE_SUPABASE_ANON_KEY=$VITE_SUPABASE_ANON_KEY
+ENV VITE_N8N_ENABLED=$VITE_N8N_ENABLED
+ENV VITE_METABASE_ENABLED=$VITE_METABASE_ENABLED
+ENV VITE_REDIS_ENABLED=$VITE_REDIS_ENABLED
+ENV VITE_OBSERVABILITY_ENABLED=$VITE_OBSERVABILITY_ENABLED
+ENV VITE_ROUTING_MODE=$VITE_ROUTING_MODE
+ENV VITE_PLAUSIBLE_DOMAIN=$VITE_PLAUSIBLE_DOMAIN
+ENV VITE_PLAUSIBLE_SCRIPT_URL=$VITE_PLAUSIBLE_SCRIPT_URL
+RUN pnpm build:client
+RUN pnpm build:server
+
+# Dependency stage — install runtime deps in a throwaway container
+FROM node:22-alpine3.23 AS deps
+WORKDIR /deps
+RUN npm init -y > /dev/null 2>&1 && \
+    npm install --no-package-lock pino@10
+
+# Production stage — minimal Alpine with just the node binary
+FROM alpine:3.23 AS runner
+
+RUN apk add --no-cache libstdc++ && \
+    addgroup -g 1001 -S hono && \
+    adduser -S hono -u 1001 -G hono
+
+COPY --from=node:22-alpine3.23 /usr/local/bin/node /usr/local/bin/node
+
+WORKDIR /app
+
+# Copy pre-installed runtime dependencies from deps stage
+COPY --from=deps /deps/node_modules ./node_modules
+
+# Copy built application
+COPY --from=builder /app/dist ./dist
+
+# Copy entrypoint
+COPY docker-entrypoint.sh ./
+RUN chmod +x docker-entrypoint.sh
+
+# Security: switch to non-root user
+USER hono
+
+EXPOSE 3000
+
+ENV NODE_ENV=production
+ENV PORT=3000
+
+ENTRYPOINT ["./docker-entrypoint.sh"]
+CMD ["node", "dist/server/index.js"]

package/carbon/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vibecarbon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/carbon/PRODUCTION.md

@@ -0,0 +1,364 @@
+# Production Deployment Guide
+
+This guide explains the differences between local development and production deployments.
+
+## Architecture Differences
+
+### Local Development
+**Goal**: Fast startup, minimal resources, easy debugging
+
+Services included:
+- ✓ Core Supabase stack (Auth, Database, Storage, Realtime, REST API)
+- ✓ Development tools (Studio, Meta)
+- ✓ Basic networking
+
+**Start command:**
+```bash
+pnpm docker:up
+# or
+docker compose up -d
+```
+
+### Production
+**Goal**: Performance, reliability, scalability
+
+Additional services:
+- ✓ **Supavisor** - Connection pooling (handles 1000+ concurrent connections)
+- ✓ **Edge Functions** - Serverless function runtime
+- ✓ **Resource limits** - Prevents resource exhaustion
+- ✓ **Optimized settings** - Production-tuned configurations
+
+**Start command:**
+```bash
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+## Key Differences
+
+### 1. Connection Pooling (Supavisor)
+
+**Local**: Direct database connections
+- Simpler debugging
+- Lower latency
+- No connection limits needed
+
+**Production**: Connections via Supavisor
+- Handles 1000+ concurrent connections efficiently
+- Connection pooling (default: 15 per pool)
+- Session mode for complex queries
+- Exposed on port 5432
+
+```bash
+# Local connection
+DATABASE_URL=postgres://postgres:password@localhost:5432/postgres
+
+# Production connection (via pooler)
+DATABASE_URL=postgres://postgres:password@localhost:5432/postgres
+# Same URL, but routed through Supavisor internally
+```
+
+### 2. Edge Functions
+
+**Local**: Not included (use your Hono API for custom logic)
+- Faster startup
+- Simpler stack
+
+**Production**: Edge Functions runtime available
+- Run Deno/TypeScript functions
+- Webhook handlers
+- Scheduled tasks
+- Custom API endpoints
+
+```typescript
+// Example edge function: functions/hello-world/index.ts
+Deno.serve((req) => {
+  return new Response(JSON.stringify({ message: "Hello World!" }), {
+    headers: { "Content-Type": "application/json" },
+  });
+});
+```
+
+### 3. Resource Limits
+
+**Local**: No limits
+- Use whatever resources you have
+- Services compete for resources
+
+**Production**: Hard limits enforced
+- Database: 4GB RAM, 2 CPUs
+- API services: 512MB RAM, 1 CPU
+- Prevents one service from consuming all resources
+- Predictable performance
+
+## Configuration Files
+
+```
+.
+├── docker-compose.yml               # Base (local + production)
+├── docker-compose.prod.yml          # Production enhancements
+├── docker-compose.observability.yml # Optional: Grafana, Prometheus, Loki
+├── docker-compose.n8n.yml           # Optional: n8n workflow automation
+├── docker-compose.metabase.yml      # Optional: Metabase analytics
+├── k8s/                             # Kubernetes manifests with Kustomize overlays
+└── k8s/overlays/                    # Optional: HA multi-region overlays
+```
+
+### Composition Examples
+
+**Local development:**
+```bash
+docker compose up -d
+```
+
+**Local with n8n:**
+```bash
+docker compose -f docker-compose.yml -f docker-compose.n8n.yml up -d
+# Access: http://n8n.localhost (requires super_admin login)
+```
+
+**Local with Metabase:**
+```bash
+docker compose -f docker-compose.yml -f docker-compose.metabase.yml up -d
+# Access: http://metabase.localhost (requires super_admin login)
+```
+
+**Local with all optional services:**
+```bash
+docker compose -f docker-compose.yml \
+  -f docker-compose.observability.yml \
+  -f docker-compose.n8n.yml \
+  -f docker-compose.metabase.yml up -d
+```
+
+**Production:**
+```bash
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+**Production with n8n + Metabase:**
+```bash
+docker compose -f docker-compose.yml \
+  -f docker-compose.prod.yml \
+  -f docker-compose.n8n.yml \
+  -f docker-compose.metabase.yml up -d
+```
+
+## Environment Variables
+
+Most environment variables are the same between local and production. Key differences:
+
+### Local (.env.local)
+```bash
+# Development URLs
+SITE_URL=http://localhost:5173
+SUPABASE_URL=http://localhost:8000
+
+# No SMTP (emails logged to console)
+SMTP_HOST=
+SMTP_PORT=
+```
+
+### Production (.env.production)
+```bash
+# Production URLs
+SITE_URL=https://yourdomain.com
+SUPABASE_URL=https://api.yourdomain.com
+
+# Real SMTP
+SMTP_HOST=smtp.sendgrid.net
+SMTP_PORT=587
+SMTP_USER=apikey
+SMTP_PASS=your_api_key
+
+# S3 storage (required for production)
+STORAGE_BACKEND=s3
+S3_BUCKET=your-bucket
+S3_REGION=us-east-1
+AWS_ACCESS_KEY_ID=your_key
+AWS_SECRET_ACCESS_KEY=your_secret
+```
+
+## Package.json Scripts
+
+Add these scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "docker:up": "docker compose up -d",
+    "docker:prod:up": "docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d",
+    "docker:down": "docker compose down",
+    "docker:logs": "docker compose logs -f",
+    "docker:ps": "docker compose ps"
+  }
+}
+```
+
+## Migration Strategy
+
+### 1. Test Locally First
+```bash
+# Start local stack
+pnpm docker:up
+
+# Run your application
+pnpm dev
+
+# Test everything works
+```
+
+### 2. Test Production Stack Locally
+```bash
+# Stop local stack
+docker compose down
+
+# Start with production config
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+
+# Verify services start correctly
+docker compose ps
+
+# Test connection pooling
+psql postgres://postgres:password@localhost:5432/postgres
+```
+
+### 3. Deploy to Production Server
+
+```bash
+# SSH to your production server
+ssh user@your-server
+
+# Clone your repo
+git clone your-repo
+
+# Copy production environment variables
+cp .env.example .env.production
+# Edit .env.production with production values
+
+# Start production stack
+docker compose -f docker-compose.yml -f docker-compose.prod.yml --env-file .env.production up -d
+```
+
+## Monitoring Production
+
+### Check Service Health
+```bash
+docker compose ps
+```
+
+All services should show "healthy" or "Up".
+
+### Check Resource Usage
+```bash
+docker stats
+```
+
+Monitor CPU, memory, and network usage.
+
+### Connection Pooler Stats
+```bash
+# Supavisor metrics
+curl http://localhost:9999/metrics
+```
+
+### View Logs
+```bash
+# All services
+docker compose logs -f
+
+# Specific service
+docker compose logs -f supavisor
+```
+
+## Troubleshooting
+
+### Too Many Database Connections
+
+**Problem**: "remaining connection slots are reserved"
+
+**Solution**: Use Supavisor in production
+```bash
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+### Out of Memory
+
+**Problem**: Services crash with OOM errors
+
+**Solution**: Resource limits in `docker-compose.prod.yml` prevent this
+- Database limited to 4GB
+- Services limited to 512MB each
+
+### Slow Performance
+
+**Problem**: Queries are slow under load
+
+**Solution**: Connection pooling + resource limits
+- Supavisor handles connection overhead
+- Resource limits prevent resource starvation
+
+## Rate Limiting Considerations
+
+The API server includes built-in rate limiting (100 requests/minute per IP). This uses an in-memory store which works well for:
+- Single-server deployments
+- Development and testing
+
+### Horizontal Scaling Limitation
+
+When running multiple API instances (Kubernetes deployments), the in-memory rate limiter does not share state across pods. This means:
+- Each pod tracks its own request counts
+- Users could potentially make 100 * N requests/minute (where N = number of pods)
+
+### Solutions for Multi-Instance Deployments
+
+**Option 1: Use Traefik Rate Limiting (Recommended)**
+Configure rate limiting at the ingress level in `volumes/traefik/middlewares.yml`:
+```yaml
+http:
+  middlewares:
+    rate-limit:
+      rateLimit:
+        average: 100
+        burst: 200
+        period: 1m
+```
+
+**Option 2: Add Redis for Shared State**
+Add the Redis service and configure the rate limiter to use it:
+```bash
+npx vibecarbon add redis
+```
+Then update the rate limiter configuration to use Redis as the backing store.
+
+**Option 3: External Rate Limiting**
+Use Cloudflare Rate Limiting rules if using Cloudflare for DNS/CDN.
+
+## Best Practices
+
+### 1. Always Use Production Config in Production
+Never run production with just `docker-compose.yml`.
+
+### 2. Test Production Config Locally
+Before deploying, test the full production stack locally.
+
+### 3. Monitor Resource Usage
+Use `docker stats` to ensure limits are appropriate.
+
+### 4. Scale Horizontally
+For even more performance, run multiple instances behind a load balancer:
+```bash
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --scale rest=3
+```
+
+### 5. Use External Database for Large Deployments
+For very large deployments, consider external managed PostgreSQL:
+- Better backups
+- Automated failover
+- Dedicated resources
+
+## Learn More
+
+- [Supavisor Documentation](https://github.com/supabase/supavisor)
+- [Edge Functions Guide](https://supabase.com/docs/guides/functions)
+- [Docker Compose Production Guide](https://docs.docker.com/compose/production/)
+- [Self-Hosting Supabase](https://supabase.com/docs/guides/self-hosting)

package/carbon/README.md

@@ -0,0 +1,193 @@
+# {{PROJECT_NAME}}
+
+A production-ready full-stack application built with React 19, Hono, and self-hosted Supabase.
+
+## Quick Start
+
+```bash
+# Start development environment
+npx vibecarbon up
+
+# This runs: Docker services + database migrations + dev servers
+```
+
+**Access Points:**
+- App: http://app.localhost (or http://localhost:5173)
+- API: http://localhost:3000
+- API Docs: http://localhost:3000/api/docs
+- Supabase Studio: http://studio.localhost (or http://localhost:8000)
+
+## Tech Stack
+
+| Layer | Technology | Purpose |
+|-------|------------|---------|
+| Frontend | React 19, Vite, React Router, TanStack Query, Shadcn UI, Tailwind CSS v4, i18next | SPA with client-side routing, UI components, and i18n |
+| Backend | Hono, Pino logger, Zod validation | Lightweight API server |
+| Database | PostgreSQL | Self-hosted Supabase + RLS |
+| Auth | Supabase Auth | Email, OAuth, magic links, MFA, & SSO |
+| Security | Traefik, Cloudflare (optional) |  |
+| Automation | Node, Docker, K8s, Pulumi | Auto scaling, Backups, Failover, High Availability |
+| Tooling | Biome (lint/format), TypeScript, Vitest |  |
+
+## Architecture
+
+Architecture Diagram
+
+  ┌─────────────────────────────────────────────────────────────────┐
+  │                        CLOUDFLARE                               │
+  │                    (TLS termination, WAF)                       │
+  └──────────────────────────┬──────────────────────────────────────┘
+                             │                                       
+  ┌──────────────────────────▼──────────────────────────────────────┐
+  │                      TRAEFIK INGRESS                            │      
+  │              (Rate limiting, ForwardAuth)                       │      
+  └──────────────────────────┬──────────────────────────────────────┘
+                             │                                       
+          ┌──────────────────┼──────────────────┐                    
+          │                  │                  │                    
+          ▼                  ▼                  ▼                    
+  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐            
+  │   HONO API    │  │  KONG (API    │  │   SUPABASE    │            
+  │  (Port 3000)  │  │   Gateway)    │  │    STUDIO     │            
+  │               │  │  (Port 8000)  │  │  (Port 3000)  │            
+  │ • Auth checks │  │               │  │               │
+  │ • Rate limit  │  │ Routes to:    │  │               │
+  │ • Validation  │  │ • Auth        │  │               │
+  └───────┬───────┘  │ • REST API    │  └───────────────┘
+          │          │ • Realtime    │
+          │          │ • Storage     │
+          │          └───────┬───────┘                               
+          │                  │                                       
+          └────────┬─────────┘                                       
+                   │                                                 
+                   ▼                                                 
+  ┌─────────────────────────────────────────────────────────────────┐
+  │                      POSTGRESQL                                 │      
+  │                                                                 │      
+  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
+  │  │    RLS      │  │   Helper    │  │    Brute Force          │  │
+  │  │  Policies   │  │  Functions  │  │    Protection           │  │
+  │  │             │  │             │  │                         │  │
+  │  │ • Per-table │  │ • auth.uid  │  │ • failed_login_attempts │  │
+  │  │ • Per-role  │  │ • org_ids   │  │ • account lockout       │  │
+  │  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
+  └─────────────────────────────────────────────────────────────────┘
+
+## Commands
+
+```bash
+# Development
+pnpm dev:start          # Full cold start (Docker + migrations + dev)
+pnpm dev                # Start dev servers only
+pnpm dev:reset          # Remove containers, volumes, and built images
+
+# Build & Test
+pnpm build              # Build for production
+pnpm lint               # Run Biome linter
+pnpm typecheck          # TypeScript type checking
+pnpm test               # Run tests
+
+# Docker
+pnpm docker:up          # Start Supabase services
+pnpm docker:down        # Stop services
+pnpm db:migrate         # Run SQL migrations
+```
+
+## Features
+
+- **Auth**: Email/password, OAuth (Google, Microsoft, GitHub, Apple, Discord), magic links, MFA
+- **Billing**: Multi-provider (Stripe, Paddle, Polar) subscriptions, checkout, portal, plan gating, webhooks
+- **Teams**: Multi-tenant organizations with RBAC (Owner, Admin, Member)
+- **Onboarding**: Guided wizard (profile, organization, plan, invite)
+- **Contact Form**: Public form with honeypot spam protection, admin panel for submissions
+- **Newsletter**: Double opt-in subscription, admin compose/send, CSV export
+- **File Uploads**: Drag-and-drop uploads via S3-backed storage (Hetzner Object Storage) with avatar support
+- **Email**: Transactional email via SMTP — welcome, invite, billing, contact notifications
+- **Blog**: MDX-powered blog with frontmatter, auto-generated sitemap and RSS
+- **Changelog**: MDX-powered changelog with version tags
+- **Documentation**: MDX-powered docs with sidebar navigation, full-text search (Cmd+K), and prev/next links
+- **Legal Pages**: Privacy policy and terms of service with placeholder support
+- **i18n**: Internationalization with admin-toggled language switcher
+- **Background Jobs**: Scheduled tasks via pg_cron (zero extra infrastructure)
+- **Analytics**: Privacy-friendly product analytics via Plausible (cookie-free, GDPR-compliant)
+- **Admin Panel**: User management, org management, notifications, jobs, contact, newsletter, impersonation, infrastructure dashboard
+- **SEO**: Meta tags, Open Graph, sitemap.xml, robots.txt, RSS feed
+- **AI-Ready**: Pre-configured rules for Claude Code, Cursor, Windsurf, and GitHub Copilot
+
+## Project Structure
+
+```
+src/
+├── client/                  # React SPA
+│   ├── components/          # UI components (50+ Shadcn components)
+│   │   ├── ui/              # Shadcn UI primitives
+│   │   ├── auth/            # AuthProvider, ProtectedRoute
+│   │   ├── FileUpload.tsx   # Drag-and-drop file upload
+│   │   └── ImpersonationBanner.tsx
+│   ├── pages/               # Route pages
+│   │   ├── Blog.tsx         # MDX blog (index + posts)
+│   │   ├── Changelog.tsx    # MDX changelog
+│   │   ├── Docs.tsx         # MDX docs with sidebar nav
+│   │   ├── Onboarding.tsx   # Multi-step onboarding wizard
+│   │   ├── admin/           # Super admin pages
+│   │   ├── settings/        # User settings (profile, billing, security)
+│   │   └── organizations/   # Org details, members
+│   ├── hooks/               # Custom React hooks
+│   ├── lib/                 # Supabase client, i18n, blog/docs loaders
+│   └── locales/             # Translation files (en.json)
+│
+├── server/                  # Hono API
+│   ├── routes/              # API endpoints
+│   │   ├── v1/              # Versioned API (users, orgs, billing, admin)
+│   │   └── webhooks/        # Billing webhooks (Stripe, Paddle, Polar)
+│   ├── emails/              # React Email templates
+│   └── lib/                 # Server utilities (env, logger, stripe, email)
+│
+└── shared/                  # Shared TypeScript types & pricing config
+
+content/
+├── blog/                    # Blog posts (MDX with frontmatter)
+├── changelog/               # Changelog entries (MDX with version tags)
+└── docs/                    # Documentation pages (MDX with ordering)
+
+supabase/
+└── migrations/              # SQL migration files
+```
+
+## Documentation
+
+- [AGENTS.md](./AGENTS.md) - Development patterns, architecture, and mandatory security rules (also the source for CLAUDE.md / Copilot / Cursor instructions)
+- [PRODUCTION.md](./PRODUCTION.md) - Production deployment guide
+- [k8s/README.md](./k8s/README.md) - Kubernetes deployment
+
+## Running Multiple Projects
+
+To run multiple vibecarbon projects simultaneously on the same machine, configure port offsets in `.env.local`:
+
+```bash
+# Shift all ports by 100 (Vite: 5273, API: 3100, Kong: 8100)
+DEV_PORT_OFFSET=100
+```
+
+Or override individual ports:
+
+```bash
+DEV_VITE_PORT=5273
+DEV_API_PORT=3100
+DEV_KONG_PORT=8100
+```
+
+| Service | Default | With Offset 100 |
+|---------|---------|-----------------|
+| Vite | 5173 | 5273 |
+| API | 3000 | 3100 |
+| Kong | 8000 | 8100 |
+| Traefik | 80 | 180 |
+
+## Default Credentials
+
+The admin account created during setup:
+- **Email**: (provided during `npx vibecarbon create`)
+- **Password**: (provided during `npx vibecarbon create`)
+
+This account has `super_admin` role for accessing `/admin/*` routes.