A full-stack, production-grade Facebook clone built end-to-end by Claude using ralph loops — persistent, self-verifying AI workflows that turn a single sentence into a working application.
This repo is a public demo of what modern AI agents can ship when given a clear goal and the freedom to plan, delegate, and iterate. The entire app — 60+ routes, 16 database models, realtime messaging, and pixel-faithful Facebook UI — was generated from one prompt:
full facebook clone with all functionalities and similar look and feel.
not prototype but production ready
No hand-coding. No file-by-file dictation. The orchestrator (Claude Opus) expanded that brief, designed the architecture, spawned eight specialist sub-agents in parallel, ran type checks and a production build, and self-corrected until everything compiled.
A ralph loop is a persistence pattern for AI agents: keep working on a goal — planning, executing, verifying, fixing — until every acceptance criterion is satisfied. The loop only stops when reality (a passing build, green tests, a satisfied reviewer) confirms completion. No hedging, no "should work", no half-done.
In this build, the loop produced:
| Phase | What happened |
|---|---|
| 0 | Lead agent broke the prompt into 10 tasks, defined a 16-model Prisma schema, chose the stack, and set up shared libs |
| 1 | Auth + layout sub-agents ran in parallel — NextAuth v5 + the entire UI primitive library |
| 2 | Six feature sub-agents ran in parallel — feed, friends, profiles, messaging, notifications, stories/groups/search |
| 3 | Lead agent integrated the modules, wired the navbar, fixed cross-agent type mismatches, ran npm run build, and self-corrected until it passed |
| 4 | Seeded the database with realistic demo data and pushed this repo |
The whole thing was driven by structured task tracking, parallel agent delegation, and TypeScript + production-build verification as the ground truth.
- Auth — register, log in, JWT sessions, route-protecting middleware
- News feed — posts (text + multi-image), cursor-paginated infinite scroll, privacy levels
- 7 Reactions — Like / Love / Care / Haha / Wow / Sad / Angry with the hover picker
- Comments — threaded comments + replies, comment reactions
- Friends — send/accept/decline/cancel requests, unfriend, suggestions, mutual friends
- Profiles — cover + avatar, intro card, Posts/About/Friends/Photos tabs, edit profile, photo albums
- Messaging — realtime 1:1 + group chat over Socket.io, typing indicators, online presence, read receipts
- Notifications — realtime delivery, unread badge, dropdown panel, full notifications page
- Stories — 24h ephemeral image/text stories, story bar, fullscreen viewer
- Groups — create/join/leave, group pages, group posts, member roles
- Search — live dropdown (users, posts, groups) + filterable results page
- Dark mode — full light/dark theme
| Layer | Tech |
|---|---|
| Framework | Next.js 16 (App Router, src/, Turbopack), React 19 |
| Language | TypeScript (strict) |
| Database | PostgreSQL + Prisma 6 |
| Auth | NextAuth v5 (credentials, JWT, bcrypt) |
| Realtime | Socket.io (custom Node server) |
| Styling | Tailwind CSS v4 (light/dark theme tokens) |
| State / UX | Zustand, sonner (toasts), lucide-react (icons), zod |
- 60 routes (32 API + 28 pages) — all compile cleanly
- 16 Prisma models — Users, Posts, Comments, Reactions, Friendships, FriendRequests, Conversations, ConversationParticipants, Messages, Notifications, Stories, Groups, GroupMembers, Albums, Photos, Sessions
- ~50 React components + shared UI primitive library
- Custom server wiring Next.js + Socket.io for realtime
- Zero
tsc --noEmiterrors,npm run buildpasses
- Node.js 20+
- PostgreSQL 14+ (Homebrew, Docker, or any reachable instance)
# 1. Install dependencies
npm install
# 2. Start PostgreSQL — either Docker:
docker compose up -d
# or Homebrew:
brew install postgresql@17 && brew services start postgresql@17
# 3. Configure environment
cp .env.example .env
# edit DATABASE_URL to match your Postgres
# set AUTH_SECRET / NEXTAUTH_SECRET (generate with: openssl rand -base64 32)
# 4. Create schema + seed demo data
npm run db:push
npm run db:seed
# 5. Run the custom Next + Socket.io server
npm run devOpen http://localhost:3000.
Email: demo@facebook.com
Password: password123
The login page also has a one-click "Log in as demo user" button.
The seed creates 14 users, 44 posts with reactions and threaded comments, 39 friendships, pending friend requests, 6 conversations with messages, 8 active stories, 5 groups with members and group posts, and photo albums — so the app feels alive the moment you log in.
| Script | Description |
|---|---|
npm run dev |
Dev server (Next.js + Socket.io) |
npm run build |
prisma generate + production build |
npm start |
Production server |
npm run db:push |
Sync Prisma schema to the database |
npm run db:seed |
Wipe + reseed demo data |
npm run db:studio |
Open Prisma Studio |
npm run db:reset |
Reset the database |
See AGENTS.md for the full directory layout, data model, and
code conventions enforced across all sub-agents.
server.js— custom server wiring Socket.io into Next.jsprisma/schema.prisma— full data layersrc/app/(auth)— login / register (no app shell)src/app/(main)— authenticated app with shared navbar + sidebarssrc/app/api— REST-style route handlers, all zod-validatedsrc/components/ui— reusable Facebook-styled primitivessrc/lib— Prisma client, auth, realtime helpers, shared types, validation
Uploaded images land in public/uploads via POST /api/upload. For a real
deployment, swap src/lib/upload.ts for S3 / Cloudinary — call sites only
depend on it returning a URL string.
- Set strong
AUTH_SECRET/NEXTAUTH_SECRETand a realDATABASE_URL - Move uploads to object storage
- Run behind HTTPS;
server.jshonoursPORTandNODE_ENV
This isn't a toy. It's evidence that a sufficiently capable AI agent, given a clear goal and a persistence loop, can ship a coherent, production-quality application end-to-end — including parts most demos hand-wave: realtime sockets, auth, dark mode, infinite scroll, image uploads, threaded comments, friend graphs, search.
The prompt was one sentence. The build was the loop.
MIT — do whatever you want with it.