Vibe Coding Starter Kit

Stop wiring boilerplate and start building. This open-source starter kit gives vibe coders and AI coding agents a well-engineered foundation — a full-stack TypeScript + Python template with a pre-built dashboard UI, file upload system, and Backblaze B2 cloud storage already integrated. Save thousands of tokens on setup prompts, skip the "build me a dashboard from scratch" loop, and go straight to building your app's unique features.

What you get out of the box:

• Full-stack dashboard UI (Next.js 16 + React 19 + Tailwind v4 + shadcn/ui)
• File upload with drag-and-drop, progress tracking, and metadata extraction
• File browser with preview, download, and delete
• FastAPI backend with strict layered architecture and structural tests
• Agent-optimized docs — your AI coding agent can read the repo and start contributing immediately

What it looks like

Dashboard — stats, upload activity, and recent uploads at a glance:

File browser — tree view with preview, download, and delete:

Deploy your own in one click → Deploy to Vercel. One project, one origin, no CORS to wire up.

Quick Start

You need: Node.js >= 20, pnpm >= 9, Python >= 3.12, and a free Backblaze B2 account.

Start a new project

Option 1: GitHub Template (recommended)

Click the green "Use this template" button at the top of this repo, name your project, then:

git clone https://github.com/yourorg/my-cool-app.git
cd my-cool-app

Option 2: Clone and reinitialize

git clone https://github.com/backblaze-b2-samples/vibe-coding-starter-kit.git my-cool-app
cd my-cool-app
rm -rf .git
git init
git add .
git commit -m "Initial commit from vibe-coding-starter-kit"

Either way you get a clean project with no upstream history — ready to push to your own repo and point your agent at it.

Setup

1. Run setup

pnpm run setup

This copies .env.example to .env only when .env does not already exist, installs workspace dependencies from pnpm-lock.yaml, creates services/api/.venv if missing, validates that an existing venv uses Python 3.12+, and installs the API's committed Python 3.12 resolution from services/api/requirements.lock. It is safe to rerun and never overwrites an existing .env.

Use the pnpm run form: setup (like doctor) is a built-in pnpm command before pnpm 11, so bare pnpm setup would run pnpm's own command instead of this script.

2. Add your B2 credentials

Open .env in your editor and keep it visible. Then head to the Backblaze B2 dashboard and:

1. Create a bucket. B2 will show two values — paste each into .env:
   • Bucket Unique Name → B2_BUCKET_NAME
   • Endpoint → B2_ENDPOINT
2. Create an application key with Read and Write permission. B2 will show two values — paste each into .env:
   • keyID → B2_KEY_ID
   • applicationKey → B2_APPLICATION_KEY (only shown once — paste it now)

Want a walkthrough? See the docs for creating a bucket and creating app keys.

3. Run it

pnpm dev

That's it. Frontend at localhost:3000, API at localhost:8000. Upload a file and see it working. Interactive API docs (Swagger UI) are at localhost:8000/docs, with ReDoc at /redoc.

pnpm dev runs the preflight check first — it catches the common setup gotchas (wrong Node/Python version, missing venv, missing or placeholder .env, ports already taken) and tells you exactly how to fix each one. Run it standalone any time with pnpm run doctor.

Supported local environments

Local scripts run on macOS, Linux, and WSL2 — native Windows isn't supported yet (the dev scripts use POSIX shell syntax), so use WSL2 on Windows. Cloud or sandboxed agent environments also need permission to install dependencies and to bind localhost ports; see docs/verification.md for the sandbox, port-fallback, and IPv6 behavior.

When to use

Use this repository as a template or sample implementation when you want to clone or fork a working file-management dashboard, connect it to your own B2 bucket, and then rebrand and extend it for your application. It provides production-minded engineering controls—including strict architecture, contract checks, tests, linting, and deployment runbooks—so you can begin with a dependable scaffold instead of a blank prototype.

When not to use

Do not choose this repository expecting a complete hosted SaaS product or a drop-in production service. It does not provide managed hosting, user accounts, authentication, tenant isolation, billing, or on-call operations. Before using an adapted application in production, you own its product-specific security, operations, capacity, compliance, and support decisions.

Why Backblaze B2?

Backblaze B2 is the object storage this kit is built around — a deliberate default, not just a demo backend:

• S3-compatible API. B2 speaks the S3 API, so the boto3 calls, SDKs, and tooling you already use for AWS S3 work unchanged — you just point them at B2's endpoint. This kit uses the S3-compatible API throughout (isolated in services/api/app/repo/), so nothing is locked to a proprietary client.
• Built for data-heavy apps. B2 storage runs at a fraction of hyperscaler pricing with generous free egress to many CDN and compute partners — what you want when an AI app accumulates uploads, datasets, model artifacts, and generated media.
• Free to start. A free B2 account is enough to run everything in this repo.

Building Your App

When you adapt this kit for a new app, keep the shared scaffolding and only swap out what's app-specific:

• Keep the UI kit (apps/web/src/components/ui/ + design tokens in globals.css + /design).
• Keep the File Explorer (/files) and Upload (/upload) pages and their sidebar nav entries — they're the reusable B2-backed surface.
• Adapt the Dashboard (/) to your use case — replace the default stats, chart, and recent uploads with metrics that reflect what your app actually does.
• Rebrand by editing a single file: apps/web/src/lib/app-config.ts holds the app name and description (APP_NAME, APP_DESCRIPTION). Changing them there updates the page title, sidebar, and breadcrumb everywhere — no other files to touch.

Full contract and rationale: AGENTS.md §2 — Building on This Starter Kit.

Agent-First Architecture

This repo is optimized for coding agents. Use the template, point your agent at it, and start building.

The structure follows the principle that repository knowledge is the system of record. Anything an agent can't access in-context doesn't exist — so everything it needs to reason about the codebase is versioned, co-located, and discoverable from the repo itself.

How it works

AGENTS.md is the single source of truth for all coding agents. Its bounded, agent-sized entry point gives agents the repository layout, architectural invariants, commands, conventions, and pointers to deeper docs. Agent-specific files (CLAUDE.md, GEMINI.md, Copilot instructions, etc.) are thin pointers back to AGENTS.md.

Architecture is enforced mechanically, not by convention. Layering rules, import boundaries, backend application Python file-size limits, and SDK containment are verified by structural tests and lints that run on every change. When rules are enforceable by code, agents follow them reliably.

The knowledge base is structured for progressive disclosure:

AGENTS.md              Single source of truth — layout, invariants, commands, conventions
ARCHITECTURE.md        System layout, layering rules, data flows
docs/
  features/            Feature docs (inputs, outputs, flows, edge cases)
  app-workflows.md     User journeys
  dev-workflows.md     Engineering workflows, command index, releases
  verification.md      What each gate checks, and failure recovery
  frontend-conventions.md  Frontend conventions and data fetching
  SECURITY.md          Security principles
  RELIABILITY.md       Reliability expectations
  exec-plans/          Execution plans and tech debt tracker

Key design decisions

Principle	Implementation
Give agents a single source of truth	AGENTS.md — bounded layout, invariants, commands, conventions
Enforce invariants mechanically	Structural tests + ruff + ESLint verify boundaries
DRY documentation	Each fact lives in one place; no redundant files to drift
Strict layered architecture	types -> config -> repo -> service -> runtime, enforced by tests
Prefer boring, composable libraries	stdlib logging over frameworks, Pydantic over ad-hoc validation
Contain external SDKs	boto3 only in repo/ layer — verified by structural test
Keep files agent-sized	300-line limit per file, enforced by test
Docs updated with code	Same-PR requirement prevents documentation rot
Structured observability	JSON logging, /metrics endpoint, request tracing

This approach draws from OpenAI's experience building with Codex: agents work best in environments with strict boundaries, predictable structure, and progressive context disclosure.

Core Features

• File Upload — drag-and-drop upload with real-time progress
• File Browser — list, preview, download, delete files
• Dashboard — stats cards, upload chart, recent uploads
• Metadata Extraction — image dimensions, EXIF, PDF info, checksums
• Design System — tokens, primitives, AI elements, the blaze generating loader, and inline ErrorState / EmptyState patterns. Live preview at /design.
• Inline error handling — fetch failures surface what's wrong (API offline, 401, 5xx) and offer a Retry, instead of silently rendering empty state.
• Single-source config — one .env at the repo root powers both API and web app, validated at startup so misconfig fails fast with a readable message.
• Centralized data layer — every fetch goes through TanStack Query hooks in apps/web/src/lib/queries.ts; cache invalidation is one call after a mutation.
• Checked local API contract — docs/api/openapi.json plus pnpm contract:check catch FastAPI/client route drift; it describes the template API you run, not a hosted public endpoint.
• Structural tests — verify layering rules, import boundaries, SDK containment, and backend application Python file-size limits
• Structured JSON logging — every request traced with request_id and timing
• /health endpoint — B2 connectivity check
• /metrics endpoint — Prometheus-format counters (request count, latency, uploads)
• /docs + /redoc — auto-generated interactive API docs (toggle off in prod with ENABLE_DOCS=false)
• Per-IP rate limiting and magic-byte upload validation — see SECURITY.md

Tech Stack

• TypeScript, Next.js 16, React 19, Tailwind v4, shadcn/ui, Recharts
• TanStack Query — caching, dedup, retry, stale-while-revalidate for every fetch
• Python 3.12+, FastAPI, boto3, Pydantic v2, Pillow, PyPDF2
• Backblaze B2 (S3-compatible object storage)
• pnpm workspaces (monorepo)

Commands

The commands you reach for day to day:

Command	What it does
pnpm run setup	One-time cold start: copy .env.example → .env (only if missing), install workspace deps, create the backend venv, install locked API deps
pnpm dev	Start frontend + backend (runs the pnpm run doctor preflight first)
pnpm verify	Credential-free pre-PR suite — runs check:agent-docs, verify:api, then verify:web
pnpm verify:full	pnpm verify plus Playwright E2E; needs a live local stack, real .env, free port 3000, and Chromium
pnpm contract:export / pnpm contract:check	Export / verify the FastAPI OpenAPI contract in docs/api/openapi.json

pnpm verify is the gate to run before opening a PR. It needs services/api/.venv from pnpm run setup, but no B2 credentials or browser, and it breaks down into pnpm verify:api (backend lint, tests, structure), pnpm verify:web (frontend lint, unit tests, typecheck + build), and pnpm check:agent-docs (agent-doc drift).

For the full command reference (dev:web, dev:api, lint, test:*, check:structure, test:e2e, live B2 tests), see docs/dev-workflows.md. For worktree/parallel-run notes, port-fallback behavior, and slow-run recovery, see docs/verification.md.

Deploying to Vercel

Deploys as one Vercel project — the Next.js web app and FastAPI API build from the same repo and share one origin (web at /, API under /api), so there's no CORS and no second URL to wire up.

Set your B2 credentials and bucket, and you're live. Uploads go directly from the browser to B2 (presigned PUT), so Vercel's 4.5 MB payload limit doesn't apply — you keep the 100 MB default. Two things to know before a real deploy:

• Your bucket's CORS must allow the deploy origin.
• The deployed API is unauthenticated and bucket-wide — use a dedicated B2 bucket/prefix and key for any preview.

Full setup — variable reference, the two-Projects alternative, security, preview/production, /health checks, and rollback — is in the Vercel delivery contract.

Documentation Map

Doc	Purpose
AGENTS.md	Agent table of contents — start here
ARCHITECTURE.md	System layout, layering, data flows
docs/features/	Feature docs (upload, browser, dashboard, metadata)
docs/design-system.md	Design tokens, primitives, AI elements, loader, error/empty states
docs/app-workflows.md	User journeys
docs/dev-workflows.md	Engineering workflows, command index, releases
docs/verification.md	What each gate checks, and failure recovery
docs/frontend-conventions.md	Frontend conventions, screens, data fetching
docs/SECURITY.md	Security principles
docs/RELIABILITY.md	Reliability expectations
docs/api/openapi.json	Checked contract for the template's local FastAPI API
infra/vercel/README.md	Vercel deployment contract
docs/exec-plans/	Execution plans and tech debt tracker

FAQ

What is the Vibe Coding Starter Kit? An open-source, full-stack template (Next.js 16 + FastAPI) with a pre-built dashboard UI, drag-and-drop file upload, and file browser, with Backblaze B2 cloud storage already integrated. You clone it, connect it to your own B2 bucket, then rebrand and extend it for your app.

Is it free? Yes. The code is MIT-licensed (see License), and Backblaze B2 offers a free account to get started.

Can I use it in production? It's a template/sample Backblaze maintains to help developers get started with B2. Production use is possible with caution and requires your own validation — you own the product-specific security, operations, capacity, compliance, and support decisions for anything you adapt, and the repository software carries no SLA. See When not to use and Maintenance and support.

Does it include authentication, user accounts, or multi-tenant isolation? No. It does not provide managed hosting, user accounts, authentication, tenant isolation, billing, or on-call operations. Add whatever your application requires on top of the scaffold.

Do I have to use Backblaze B2? It integrates Backblaze B2 through the S3-compatible API, and B2 is the storage the kit is built around. You supply your own B2 bucket and application key during setup.

Is it really built for AI coding agents? Yes. AGENTS.md is the single source of truth for coding agents, architectural boundaries are enforced mechanically by structural tests and lints (not by convention), and the docs use progressive disclosure — so an agent can read the repo and start contributing immediately.

What's the tech stack? Frontend: TypeScript, Next.js 16, React 19, Tailwind v4, shadcn/ui, TanStack Query. Backend: Python 3.12+, FastAPI, boto3, Pydantic v2. Storage: Backblaze B2 (S3-compatible). See Tech Stack.

How do I rebrand it for my own app? Edit a single file — apps/web/src/lib/app-config.ts (APP_NAME, APP_DESCRIPTION) — and the page title, sidebar, and breadcrumb update everywhere. See Building Your App.

How do I deploy it? It deploys to Vercel as a single project — the web app and FastAPI API build from the same repo and share one origin (web at /, API under /api), so there's no CORS or second URL to wire up. A Railway path is also documented. Deploying is always a human-approved action — see Deploying to Vercel.

Does it work on Windows? Local scripts are supported on macOS, Linux, and WSL2. Native Windows is not supported yet — use WSL2 on Windows.

Where do I get help or report bugs? Report repository defects and feature requests through GitHub Issues. For B2 account, billing, service, or API help, use Backblaze Support.

Maintenance and support

Backblaze maintains this open-source template/sample to help developers get started with B2. Production use is possible with caution and requires your own validation. Report repository defects and feature requests through GitHub Issues; for B2 account, billing, service, or API help, use Backblaze Support. This template/sample is not covered by the Backblaze service level agreement, and no SLA is provided for the repository software; any B2 service or support commitments are governed separately by the applicable Backblaze terms and support plan.

Contributing

Start with AGENTS.md. It's the map — everything else is discoverable from there. For local commit hooks, follow the pre-commit workflow.

License

MIT License - see LICENSE for details.

Related projects

Claude Agent B2 Skill — manage Backblaze B2 from your terminal using natural language (list/search, audits, stale or large file detection, security checks, safe cleanup). Repo: claude-skill-b2-cloud-storage.