{"id":51630198,"url":"https://github.com/pingcap/full-stack-app-builder-ai-agent","last_synced_at":"2026-07-13T06:32:55.511Z","repository":{"id":266407809,"uuid":"632854984","full_name":"pingcap/full-stack-app-builder-ai-agent","owner":"pingcap","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-18T08:01:17.000Z","size":16521,"stargazers_count":24,"open_issues_count":1,"forks_count":11,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-07-13T06:32:55.122Z","etag":null,"topics":["codegen","database","database-branching","full-stack-ai-agent"],"latest_commit_sha":null,"homepage":"https://code.tidb.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pingcap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-04-26T09:13:12.000Z","updated_at":"2026-06-11T10:16:02.000Z","dependencies_parsed_at":"2024-12-04T05:36:45.249Z","dependency_job_id":"30bed882-72b4-41b2-9567-b7c8cddb4cf2","html_url":"https://github.com/pingcap/full-stack-app-builder-ai-agent","commit_stats":null,"previous_names":["pingcap/auto-gpt-tidb-serverless-plugin","pingcap/full-stack-app-builder-ai-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pingcap/full-stack-app-builder-ai-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingcap%2Ffull-stack-app-builder-ai-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingcap%2Ffull-stack-app-builder-ai-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingcap%2Ffull-stack-app-builder-ai-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingcap%2Ffull-stack-app-builder-ai-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pingcap","download_url":"https://codeload.github.com/pingcap/full-stack-app-builder-ai-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingcap%2Ffull-stack-app-builder-ai-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35413538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codegen","database","database-branching","full-stack-ai-agent"],"created_at":"2026-07-13T06:32:54.509Z","updated_at":"2026-07-13T06:32:55.506Z","avatar_url":"https://github.com/pingcap.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"TiDB Cloud\" src=\"./public/TiDB-Logo-w-Tagline-Full-Pos-RGB.svg\" width=\"360\" /\u003e\n\u003c/p\u003e\n\n# How to Build an AI Agent that Builds Full-Stack Apps\nAn open-source starter kit using TiDB Cloud, Vercel, Kysely, and GitHub. Think of this as a minimal, self-hostable cousin of [Lovable.dev](https://lovable.dev/) that you fully own and control.\n\n\u003e Describe an app and this agent provisions GitHub + TiDB Cloud + Vercel, codes with [Codex (gpt-5.1-codex)](https://openai.com/codex/) and [Claude Code (claude-sonnet-4.5)](https://www.claude.com/product/claude-code), tests, deploys, and streams the whole session.\n\n- Demo video: https://www.youtube.com/watch?v=kyWZzj57wwY\n- Blog post: https://www.pingcap.com/blog/ai-agent-that-builds-full-stack-apps/\n\n## What This Agent Can Do\n- Generate complete web apps from a prompt (Next.js 16 + shadcn/Tailwind).\n- Provision TiDB Cloud clusters/branches per project and per instruction.\n- Track versions so code, schema, and credentials stay aligned.\n- Run and preview apps instantly via Vercel sandboxes and previews.\n- Keep conversational context between generations for iterative refinement.\n- Scale down idle environments with TiDB Cloud serverless.\n\n## Architecture Overview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Architecture Overview: Full-Stack App-Builder AI Agent\" src=\"./public/architecture.png\" width=\"960\" /\u003e\n\u003c/p\u003e\n\n- **Server actions** (`src/actions/*`) orchestrate GitHub, TiDB Cloud, and Vercel resources.\n- **Sandboxes** (`src/sandboxes/*`) launch per-task runtimes, run `npm run dev`, and report via `src/app/hooks/v1/sandboxes/[sandboxId]/route.ts`.\n- **Session UI** (`src/app/(customer)/s/[slug]`) streams logs, checkpoints, and deploy links.\n- **Auth \u0026 protection** (`src/proxy.ts`, `src/lib/auth*`) gate `/projects`, `/settings`, and API v1 routes.\n\n## How It Works (End-to-End)\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"End-to-end user flow: prompt to plan, provision, generate, migrate, deploy, and iterate\" src=\"./public/userflow.png\" width=\"960\" /\u003e\n\u003c/p\u003e\n\n1. **Prompt** – “Build a todo app.”  \n2. **Plan** – Model drafts an execution plan.  \n3. **Provision** – Create TiDB cluster/branch, Vercel sandbox, GitHub repo/branch, and env vars.  \n4. **Generate** – Codex/Claude Code writes app code, Kysely schema, and migrations.  \n5. **Migrate** – Run typed migrations against the TiDB branch.  \n6. **Deploy** – Commit to GitHub and trigger a Vercel preview.  \n7. **Iterate** – Follow-up prompts (e.g., “Add a username field”) spawn new TiDB branches and code revisions, keeping everything reversible.\n\n## Magic Features\n- **Checkpointed versions** – Git branches map to TiDB branches for perfect code–data sync.\n  ```ts\n  // TiDB Cloud branch creation (simplified)\n  import fetch from \"node-fetch\";\n\n  async function createBranch(clusterId, displayName, publicKey, privateKey) {\n    const res = await fetch(\n      `https://serverless.tidbapi.com/v1beta1/clusters/${clusterId}/branches`,\n      {\n        method: \"POST\",\n        headers: {\n          \"Content-Type\": \"application/json\",\n          Authorization:\n            \"Basic \" + Buffer.from(`${publicKey}:${privateKey}`).toString(\"base64\"),\n        },\n        body: JSON.stringify({ displayName }),\n      },\n    );\n    if (!res.ok) throw new Error(await res.text());\n    return (await res.json()).branchId;\n  }\n  ```\n- **Type-safe migrations** – Kysely migrations keep schema evolution safe and reversible.\n  ```ts\n  import type { Kysely } from \"kysely\";\n\n  export async function up(db: Kysely\u003cany\u003e) {\n    await db.schema\n      .alterTable(\"todo_list\")\n      .addColumn(\"username\", \"varchar(255)\", (col) =\u003e col.notNull().defaultTo(\"\"))\n      .execute();\n  }\n\n  export async function down(db: Kysely\u003cany\u003e) {\n    await db.schema.alterTable(\"todo_list\").dropColumn(\"username\").execute();\n  }\n  ```\n- **Scale-to-zero** – TiDB Cloud automatically scales down to $0 when idle, enabling ephemeral AI-generated apps, on-demand dev envs, branch-per-instruction workflows, and bursty agent workloads without persistent costs.\n\n## Directory Layout\n| Path | Purpose |\n| --- | --- |\n| `src/app/(auth)` | Credential login flow rendered via `LoginForm`. |\n| `src/app/(main)` | Internal dashboard (project list, per-project GitHub/Vercel cards, task tables, dialogs). |\n| `src/app/(customer)/s/[slug]` | Session replay UI backed by `getSessionData`. |\n| `src/app/api` | Versioned REST hooks for projects, tasks, revisions, sandboxes, TiDB Cloud branches, Vercel resources, and debug message streams. |\n| `src/actions` | Server actions encapsulating provisioning logic for projects, tasks, revisions, Vercel sandboxes, and TiDB Cloud branches. |\n| `src/lib` | Auth, DB, TiDB Cloud client, user setting validators, AI model helpers, utility types, and `generateSessionId`. |\n| `src/sandboxes` | Helpers that orchestrate `@vercel/sandbox` lifecycle (install tools, resume sessions from Blob storage, enforce trusted runtimes). |\n| `migrations` | Kysely migrations plus schema evolution for `user`, `project`, `task`, `task_revision`, `tidbcloud_branch`, `vercel_sandbox`, and `ui_session`. |\n| `scripts` | Local DX helpers (`migrate.ts`, `setup-local-user.js`, `gen-password.js`). |\n\n## Prerequisites \u0026 Environment\n- Node.js 18.18+ (Next.js 16 requirement) and npm.\n- TiDB Serverless account with API keys, organization/project IDs, region, and database endpoint.\n- GitHub account with access to install the required template and push commits via Personal Access Token.\n- Vercel team token with Blob Storage enabled.\n- OpenAI (or CRS) API key to drive Codex sessions.\n- Required environment variables:\n  - `DATABASE_URL`\n  - `OPENAI_API_KEY`\n  - `TIDB_CLOUD_REGION`, `TIDB_CLOUD_DATABASE_ENDPOINT`\n\n## Setup\n```bash\nnpm install\n\n# Bootstrap TiDB schema (creates the schema + tables and regenerates typed bindings)\nnpm run migrate:init       # one-time schema creation\nnpm run migrate:up         # run pending migrations\n\n# Create your first local operator seeded with GitHub + password credentials\nnode scripts/setup-local-user.js\n# (Use scripts/gen-password.js if you only need to hash a password with BCRYPT_SALT)\n\n# Launch the workspace\nnpm run dev\n```\nVisit `http://localhost:3000/login`, authenticate with the user you just created, and start creating projects or sessions.\n\n## Core npm Scripts\n| Command | Description |\n| --- | --- |\n| `npm run dev` | Starts the App Router dev server with live reload. |\n| `npm run build` / `npm run start` | Compile and serve the production bundle. |\n| `npm run lint` | Run Biome lint rules (Next/React presets). |\n| `npm run format` | Apply Biome formatting in-place. |\n| `npm run migrate:init|up|down` | Execute the TiDB schema bootstrap/migration workflow in `scripts/migrate.ts` and regenerate `src/lib/db/schema.d.ts`. |\n| `npm run install-shadcn-components` | Re-sync shadcn/ui components based on `components.json`. |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpingcap%2Ffull-stack-app-builder-ai-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpingcap%2Ffull-stack-app-builder-ai-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpingcap%2Ffull-stack-app-builder-ai-agent/lists"}