Archetype Engine

The missing backend layer for AI-generated frontends.

Define entities in TypeScript. Get production-ready backends instantly.

const Product = defineEntity('Product', {
  fields: {
    name: text().required().min(1).max(200),
    price: number().required().positive(),
    stock: number().integer().min(0).default(0),
  }
})

Run npx archetype generate → get:

• ✅ Drizzle ORM schemas (type-safe database)
• ✅ tRPC routers (CRUD + pagination + filters)
• ✅ Zod validation (runtime safety)
• ✅ React hooks (useProduct, useCreateProduct, etc.)
• ✅ Vitest tests (comprehensive test suites)
• ✅ OpenAPI docs (Swagger UI + API docs)
• ✅ Seed data (realistic sample data)

---

Why use this?

Tool	What it does	What you still write
Prisma	Database schema → Types	API, validation, hooks
tRPC	Type-safe API	Schema, validation, CRUD
Zod	Validation schemas	Database, API, hooks
Archetype	Schema → Everything	Business logic only

You're not replacing tools—you're generating the boilerplate.

---

Quick Start (2 minutes)

# 1. Create a new Next.js project
npx create-next-app@latest my-app && cd my-app

# 2. Install Archetype
npm install archetype-engine

# 3. Initialize with a template
npx archetype init

# Choose from:
# - SaaS Multi-Tenant (Workspace, Team, Member)
# - E-commerce (Product, Order, Customer)
# - Blog/CMS (Post, Author, Comment)
# - Task Management (Project, Task, Label)

# 4. Generate code
npx archetype generate

# 5. Push to database and run
npx drizzle-kit push
npm run dev

🎉 Done! You now have a fully functional backend with type-safe APIs.

---

What You Get

From a single entity definition, Archetype generates:

generated/
├── db/
│   └── schema.ts              # Drizzle ORM tables (type-safe SQL)
├── schemas/
│   └── product.ts             # Zod validation schemas
├── trpc/routers/
│   ├── product.ts             # Full CRUD API:
│   │                          #   - list (with pagination, filters, search)
│   │                          #   - get (by ID)
│   │                          #   - create, createMany
│   │                          #   - update, updateMany
│   │                          #   - remove, removeMany
│   └── index.ts               # Router aggregation
├── hooks/
│   └── useProduct.ts          # React Query hooks:
│                              #   - useProducts(), useProduct(id)
│                              #   - useCreateProduct(), useUpdateProduct()
│                              #   - useRemoveProduct(), etc.
├── tests/                     # 🆕 Auto-generated tests
│   ├── product.test.ts        #   - CRUD operation tests
│   └── setup.ts               #   - Validation & auth tests
├── docs/                      # 🆕 Auto-generated API docs
│   ├── openapi.json           #   - OpenAPI 3.0 specification
│   ├── swagger.html           #   - Interactive Swagger UI
│   └── API.md                 #   - Markdown documentation
└── seeds/                     # 🆕 Auto-generated seed data
    ├── product.ts             #   - Realistic sample data
    ├── index.ts               #   - Dependency management
    └── run.ts                 #   - CLI seed script

15 lines of entity code → 1,400+ lines of production-ready backend.

Live Example

Define once:

const Order = defineEntity('Order', {
  fields: {
    orderNumber: text().required().unique(),
    status: enumField('pending', 'paid', 'shipped'),
    total: number().required().positive(),
  },
  relations: {
    customer: hasOne('Customer'),
    items: hasMany('OrderItem'),
  },
  behaviors: {
    timestamps: true,
  },
  protected: 'all',  // Requires authentication
})

Use immediately:

// In your React component
const { data: orders } = useOrders({ 
  where: { status: 'pending' },
  orderBy: { field: 'createdAt', direction: 'desc' }
})

const { mutate: createOrder } = useCreateOrder()
createOrder({ 
  orderNumber: 'ORD-001',
  status: 'pending',
  total: 99.99 
})

No API boilerplate. No manual validation. No CRUD repetition. Just works.

---

Features

• 🎯 Type-Safe Everything - Database ↔ API ↔ Frontend sync guaranteed
• 🚀 Production-Ready Templates - SaaS, E-commerce, Blog, Task Management
• 🔐 Built-in Auth - NextAuth v5 integration with multiple providers
• 🔍 Smart Filtering - Pagination, search, sorting out of the box
• 🪝 Lifecycle Hooks - Add business logic before/after CRUD operations
• 📊 Auto ERD - Visual database diagrams with npx archetype view
• 🌍 i18n Ready - Multi-language support for generated code
• ⚡ Fast - Generate 1000+ lines of code in seconds
• 🧪 Auto-Generated Tests - Comprehensive Vitest test suites with validation, auth, and CRUD tests
• 📖 Auto-Generated Docs - OpenAPI 3.0 specs + interactive Swagger UI
• 🌱 Auto-Generated Seeds - Realistic sample data with smart field mapping

Use Cases

Template	Perfect For	Entities Included
SaaS Multi-Tenant	Team collaboration apps	Workspace, Team, Member + roles
E-commerce	Online stores, marketplaces	Product, Customer, Order, OrderItem
Blog/CMS	Content platforms, news sites	Post, Author, Comment
Task Management	Todo apps, kanban boards	Project, Task, Label

Documentation

📚 Full docs: archetype-engine.vercel.app

Popular guides:

• Getting Started - 5-minute tutorial
• Fields & Validation - text(), number(), date(), etc.
• Relations - hasOne, hasMany, belongsToMany
• Authentication - Protect routes & entities
• Filtering & Search - Build admin panels
• Lifecycle Hooks - Custom business logic
• AI Integration - Build AI app builders

---

Why Archetype?

The Problem: AI Tools Generate Incomplete Backends

Tools like v0.dev, Bolt.new, and Cursor generate beautiful UIs but:

• ❌ Hardcoded mock data
• ❌ No database integration
• ❌ No type safety
• ❌ No production-ready APIs

You get a gorgeous frontend that doesn't connect to anything real.

The Solution: Archetype Completes the Stack

Archetype generates the missing backend layer:

• ✅ Real database schemas (Drizzle ORM)
• ✅ Type-safe APIs (tRPC)
• ✅ Runtime validation (Zod)
• ✅ React hooks for data fetching

Use case: Generate UI with v0 → Add backend with Archetype → Deploy to production.

---

CLI Commands

Archetype provides a suite of commands organized by namespace to avoid conflicts with your Next.js project:

Archetype Commands (Code Generation & Documentation)

npx archetype init                 # Interactive setup with entity templates
npx archetype generate             # Generate all code from entities
npx archetype view                 # View ERD diagram in browser (port 3333)
npx archetype docs                 # View OpenAPI/Swagger UI (port 3334)
npx archetype validate             # Validate manifest without generating

Project Scripts (Added by npx archetype init)

New projects automatically get these npm scripts:

{
  "scripts": {
    // Archetype - Generation & Docs
    "archetype:generate": "archetype generate",
    "archetype:view": "archetype view",
    "archetype:docs": "archetype docs",
    "archetype:check": "archetype validate",
    
    // Database - Schema & Data
    "db:push": "drizzle-kit push",
    "db:studio": "drizzle-kit studio",
    "db:seed": "tsx generated/seeds/run.ts",
    "db:seed:reset": "tsx generated/seeds/run.ts --reset",
    
    // Testing
    "test:api": "vitest run generated/tests"
  }
}

Common Workflows

Initial setup:

npm run archetype:generate   # Generate code
npm run db:push              # Create database schema
npm run db:seed              # Add sample data
npm run dev                  # Start dev server

Development loop:

# Edit archetype/entities/product.ts
npm run archetype:generate   # Regenerate code
npm run db:push              # Update schema
npm run dev                  # Test changes

Documentation & validation:

npm run archetype:view       # View entity relationships
npm run archetype:docs       # Browse API endpoints
npm run archetype:check      # Validate entity definitions

---

Roadmap

• Core entity system with relations
• Pagination, filtering, search
• Authentication integration (NextAuth v5)
• CRUD lifecycle hooks
• Batch operations (createMany, updateMany, removeMany)
• Computed fields
• Enum support
• Test generator (Vitest)
• API documentation generator (OpenAPI + Swagger)
• Seed data generator
• E2E test generator (Playwright) (Q1 2026)
• Admin UI generator (Q1 2026)
• Multi-tenancy utilities (Q1 2026)
• RBAC/permissions framework (Q2 2026)
• GraphQL template (Q2 2026)

---

Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Architecture overview
• Development setup
• How to add features
• Testing guidelines

---

License

MIT - Use freely in commercial and open-source projects.

---

Support

• 📖 Docs: archetype-engine.vercel.app
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 🐦 Updates: Follow @archetype_dev

---

Built with ❤️ for developers tired of writing boilerplate.