# π© Vibe Code Stack For CEOs
### You're the CEO. Your AI agents are the engineering org.
**Stop prompting. Start delegating.** The full-stack monorepo where Claude Code, Cursor, Gemini CLI, Kiro, Copilot, and Windsurf all read **one company handbook** β and ship **identical, production-grade code** on the first try.
[](https://github.com/NoahDuongMaster/vibe-code-stack-for-ceos/stargazers)
[](https://github.com/NoahDuongMaster/vibe-code-stack-for-ceos/network/members)
[](https://nextjs.org)
[](https://typescriptlang.org)
[](https://opensource.org/licenses/MIT)
[β‘ Quick Start](#-quick-start) Β· [π€ The Problem](#-the-problem) Β· [π’ How It Works](#-how-it-works--the-ceo-model) Β· [π₯ Battle-Tested](#-battle-tested-by-26-ai-agents) Β· [β Star History](#-star-history)
---
## π€ The Problem
You open Cursor, type _"create a user profile page"_, and get:
- A file in the wrong folder
- `useState` for form fields instead of react-hook-form
- Raw `fetch()` instead of your HTTP client
- `console.log` everywhere
- No Zod validation, no error boundaries, no types
**You hired a 10x engineer and got an intern with amnesia.** Every prompt starts from zero. Every tool has its own opinions. You spend more time reviewing AI slop than you'd spend writing the code yourself.
That's not vibe coding. That's babysitting.
---
## π’ How It Works β the CEO Model
**A real company doesn't re-explain its culture to every new hire. It hands them the handbook.**
This repo has one: [`AGENTS.md`](./AGENTS.md) β the emerging open standard for agent instructions (`CLAUDE.md` is a symlink, so every tool finds it). It defines the architecture, the naming laws, the testing rules, the fireable offenses. Every AI agent reads it before writing a single line.
```
βββββββββββββββββββββββββββββββββββ
β AGENTS.md (the handbook) β
β CLAUDE.md βββΊ symlink β
βββββββββββββββββ¬ββββββββββββββββββ
ββββββββββ¬βββββββββΌβββββββββ¬ββββββββββ
βΌ βΌ βΌ βΌ βΌ
Claude Cursor Copilot Gemini Windsurf
ββββββββββ΄βββββββββ΄βββββββββ΄ββββββββββ
βΌ
β
identical, rule-compliant code
```
And because trust is good but gates are better, **nothing ships without passing the Five Gates**:
> **`typecheck` β `lint` β `test` β `build` β `audit`** β enforced locally by husky, enforced again in CI, and deploys are CI-gated with staging/production separation. If an agent (or a human) breaks a rule, the pipeline says no. Period.
**You review outcomes, not syntax. That's the whole product.**
---
## π Why Developers Are Switching
|
create-next-app |
t3-app |
π© Vibe Code Stack For CEOs |
| AI understands your architecture |
- |
- |
One AGENTS.md, every agent |
| Feature-Sliced Design v2.1 |
- |
Partial |
Strict, Steiger + ESLint enforced |
| Full monorepo (3 apps + RPC backend) |
- |
- |
Turborepo, 9 workspaces |
| Type-safe end to end |
- |
tRPC |
Connect-RPC (Protobuf) + next-safe-action |
| CI-gated deploys (staging/prod) |
- |
- |
GitHub Environments + wrangler |
| Pre-commit AI code review |
- |
- |
Code Review Graph MCP |
| Headless, accessible UI |
- |
- |
Ark UI v5 (WAI-ARIA) |
| Security headers (CSP/HSTS/CORS) |
- |
- |
Nonce-based CSP, OWASP-ready |
| Audited by a fleet of AI agents |
- |
- |
26 agents, 86 findings, all fixed β
|
---
## π₯ Battle-Tested by 26 AI Agents
Most boilerplates say "production-ready." We made 26 AI agents prove it.
We ran a **multi-agent production-readiness audit**: 10 specialist auditors tore through security, architecture, testing, CI/CD, performance, config, and dependencies in parallel β then every critical finding was handed to an **adversarial verifier agent** whose only job was to refute it against the real code.
**The result: 86 findings. 0 refuted. All 9 high-severity blockers fixed** β including a CSP nonce bug that would have broken production, a Turborepo cache flaw that could have shipped mock-auth to prod, and full backend CORS. Then the fix wave: 4 parallel agent teams, 300+ files touched, every gate re-run green.
```
β
typecheck 9/9 workspaces
β
biome 190 files, 0 errors
β
eslint 6/6 workspaces
β
tests 94/94 passing
β
build 5/5 production builds
β
audit 0 known vulnerabilities
```
This is what "your AI org follows the handbook" looks like in practice β the repo you're cloning was hardened by the same workflow it sells.
---
## π What You Get
### ποΈ Architecture agents can't break
Frontend boundaries are executable, not just conventions. All three frontends
use an FSD-inspired layered architecture checked by Steiger plus ESLint. The
dapp keeps Next's framework entrypoints thin and gives application code explicit
layer names:
```
apps/dapp/
app/ Next pages/layout/Route Handlers β delegation only
proxy.ts Next proxy entrypoint
src/
bootstrap/ App composition: routes, providers, metadata, errors, styles
screens/ Complete route screens (api/model/ui)
features/ Reusable user interactions such as sign-in
entities/ Session domain API and model
shared/ API client, config, focused libraries, routes, UI kit
```
- Imports point downward only: `bootstrap β screens β widgets β features β entities β shared`
- Same-layer slices are isolated; every slice/segment has a Public API
- Segment names describe purpose (`api`, `model`, `ui`, `config`), not file type
- Optional layers stay absent until they add value β dapp has no `widgets` yet
- `bootstrap`/`screens` avoid overloading framework and FSD `app`/`pages` names
- Components never call `fetch()`; same-slice API modules use the Shared client
### π A real company, not a toy app
| | Workspace | Stack | Deploys to |
| --- | ---------------------- | ------------------------------------------------------------------------------- | ------------------ |
| ποΈ | `apps/dapp` | Next.js 16 App Router on vinext (Vite) | Cloudflare Workers |
| π οΈ | `apps/admin` | React 19 SPA β Rsbuild, route-split, code-split | Cloudflare Pages |
| πͺ§ | `apps/landing` | Astro β ships **literally zero JS** | Cloudflare Workers |
| π§ | `services/admin-rpc` | Admin auth + market facade β Connect, JWT, gRPC client to trading-rpc | Docker |
| βοΈ | `services/trading-rpc` | Nest/Fastify hybrid β Connect + gRPC, PostgreSQL 18, `/healthz` | Docker |
| π | `services/api-gateway` | Edge gateway Worker β CORS allowlist, upstream proxy | Cloudflare Workers |
| π | `packages/protocol` | Protobuf schemas, buf lint + breaking-change gate in CI | β |
| π§ | `packages/api-core` | One RPC implementation, two runtimes (Node + edge) | β |
| π | `packages/api-client` | End-to-end typed browser client | β |
### π Security that survived an adversarial audit
- Nonce-based CSP wired the way Next.js actually requires (on the _request_ headers β most tutorials get this wrong)
- iron-session encrypted cookies + cryptographic session validation in middleware
- Zod at every trust boundary; constant-time credential comparison; login rate limiting
- Static CSP via `_headers` for admin/landing; allowlist-driven CORS across the backend
- Boot-time kill switch: production **refuses to start** with placeholder secrets
### π¦ The Six Gates, everywhere
Husky pre-commit β CI (`typecheck`, `check:ci`, `lint`, `test`, `test:coverage`, `build`) β CI-gated deploys (`develop` β staging, `main` β production behind manual approval) β release-please automates versioning per workspace. Nobody deploys from a laptop. Nothing skips the gates.
| Framework | Next.js 16 (App Router) on vinext (Vite) |
| Language | TypeScript 6 (strict mode) |
| Styling | Panda CSS + Ark UI v5 (headless, WAI-ARIA) |
| Server State | TanStack Query v5 |
| Client State | Zustand v5 + nuqs (URL state) |
| Forms | react-hook-form + Zod v4 |
| Server Actions | next-safe-action v8 (end-to-end typed) |
| Tables | TanStack Table v8 |
| HTTP | ofetch via shared xhr client (dapp) Β· Connect-RPC client (admin) |
| Auth | iron-session v8 (encrypted cookies) |
| Animations | Motion (Framer Motion v12) |
| Testing | Vitest v4 + Testing Library + MSW v2 + Playwright |
| Linting | Biome v2 + ESLint (architectural rules) + buf lint |
| Monitoring | Sentry β client/server/edge on dapp, DSN-gated on every app + trading-rpc |
| Monorepo | Turborepo + pnpm workspaces (strict env allowlists, cached gates) |
| Backend API | Connect RPC (Protobuf/buf) β one core, two runtimes (Workers + Node) |
| Database | PostgreSQL 18 + Drizzle ORM/Kit over a bounded node-postgres pool |
| CI/CD | GitHub Actions β Five Gates + Playwright + Dependabot + release-please + CI-gated deploys |
| Containers | Docker definitions centralized in infra/docker (multi-stage, non-root) |
---
## β‘ Quick Start
Install and activate [mise](https://mise.jdx.dev/installing-mise.html) first.
Mise is the repository's supported toolchain and command interface. pnpm stays
under the hood for dependency resolution and workspace execution.
For the complete per-environment onboarding, provisioning, deployment, and
rollback runbook, see
[`docs/setup-and-deployment.en.md`](./docs/setup-and-deployment.en.md)
([TiαΊΏng Viα»t](./docs/setup-and-deployment.md)).
```bash
# Clone
git clone https://github.com/NoahDuongMaster/vibe-code-stack-for-ceos.git
cd vibe-code-stack-for-ceos
# Install the locked Node.js/pnpm toolchain and frozen dependencies
mise run setup
# Copy the complete local defaults once on a fresh clone.
cp .env.sample .env
cp apps/dapp/.env.sample apps/dapp/.env
cp apps/dapp/.dev.vars.sample apps/dapp/.dev.vars
cp apps/admin/.env.sample apps/admin/.env
cp apps/landing/.env.sample apps/landing/.env
cp services/trading-rpc/.env.sample services/trading-rpc/.env
cp services/admin-rpc/.env.sample services/admin-rpc/.env
cp services/api-gateway/.dev.vars.sample services/api-gateway/.dev.vars
# Start native hot reload plus its Docker VPC infrastructure
mise run dev
# β¦or one department
mise run dev:web # Next.js app β http://localhost:46000
mise run dev:admin # React admin SPA β http://localhost:46001
mise run dev:landing # Astro landing β http://localhost:46002
mise run dev:api # Native Connect-RPC; starts PostgreSQL first
mise run dev:admin-api # Admin RPC facade β trading-rpc native gRPC
mise run dev:gateway # Gateway β http://localhost:46003
mise run dev:backend # Gateway + native admin-rpc + native trading-rpc
```
Local listeners use the repository-specific `46000β46010` range rather than
common framework/database ports. Docker VPC origins use `46104β46107` so they
can run beside both native RPC services. Override Docker host ports in the root
`.env` if one of these ports is already occupied.
`mise run dev` starts PostgreSQL, the VPC-visible trading-rpc origin, and
cloudflared before Turbo starts the six native hot-reload processes. Ctrl-C
stops the native processes but keeps that infrastructure ready for a fast
restart. Stop it explicitly when finished:
```bash
mise run dev:infra:stop
```
### Development gateway β private RPC services through Workers VPC
The gateway task starts its Docker origin and Tunnel dependency before running
the Worker locally with its remote development binding:
```bash
mise run dev:gateway
# In a second terminal
curl -sS -X POST http://127.0.0.1:46003/trading.v1.TradingService/GetMarkets \
-H 'content-type: application/json' \
-H 'connect-protocol-version: 1' \
--data '{"coinIds":["bitcoin","ethereum"],"vsCurrency":"usd"}'
```
`mise run dev:gateway` selects `env.development` from `wrangler.jsonc`; Worker code
runs locally while `TRADING_RPC.fetch()` executes through Cloudflare's remote
VPC binding. The binding is mandatory in every environment; the gateway fails
closed when it is absent and never falls back to a direct URL.
The development VPC Service targets the network-scoped Docker alias
`trading-rpc.internal:3001`; override it before startup with
`TRADING_RPC_PRIVATE_HOSTNAME` when an environment needs a different internal
DNS suffix.
`trading-rpc` keeps Connect/gRPC on `3001`/`50051` inside its container. Host
diagnostics use `46104`/`46105`, leaving native `46004`/`46005` free. For a
reliable CoinGecko quota, add a free Demo key as `COINGECKO_API_KEY` in
`services/trading-rpc/.env`: the Node service owns the `TradingService` use
case and its CoinGecko adapter, while the gateway only proxies the Connect
request. Staging and production require isolated `TRADING_RPC` VPC Service IDs
before those environments can proxy this capability.
`admin-rpc` exposes `auth.v1.AuthService/Login` and
`admin.v1.AdminService/GetMarkets`. Login credentials and JWT signing stay on
the server; the browser receives a short-lived signed token, and the gateway
protects non-public RPC routes with the matching secret. The market facade
validates the admin request, calls `trading.v1.TradingService/GetMarkets` over
native gRPC, validates the downstream response, and returns the coin market
fields without owning CoinGecko or database logic. Browser/admin traffic calls
both services through the gateway's separate `ADMIN_RPC` VPC Service binding:
```bash
curl -sS -X POST http://127.0.0.1:46003/admin.v1.AdminService/GetMarkets \
-H 'content-type: application/json' \
-H 'connect-protocol-version: 1' \
--data '{"coinIds":["bitcoin","ethereum"],"vsCurrency":"usd"}'
```
Terraform registers `admin-rpc.internal:3001` and
`trading-rpc.internal:3001` as separate VPC Services. Deployment CI reads their
IDs from encrypted remote state and generates the environment-specific Wrangler
config; no fake or manually copied service ID is committed. The two RPC images
and the PostgreSQL/pgBackRest image deploy to one private EC2 host per
environment through immutable ECR tags and Systems Manager, without SSH or
public RPC/database ports. See
[`infra/terraform/README.md`](./infra/terraform/README.md) for the complete
AWS/Cloudflare bootstrap, plan, apply, rollout, and rollback runbook.
Then point your AI tool of choice at the repo. It reads [`AGENTS.md`](./AGENTS.md) and behaves. That's it β that's the onboarding.
### π© Run your code like a company. Ship like a CEO.
**If this saved you time, [star the repo](https://github.com/NoahDuongMaster/vibe-code-stack-for-ceos) β it helps other CEOs find their handbook.**
Built by [Noah Duong](https://github.com/NoahDuongMaster) Β· MIT License
