gem-hunter
Language: TypeScript
Type-Safe Next.js Stack using Simple Clean Architecture with MongoDB Template For AI Friendly
A production-ready Todo Application Template built with Next.js 16, implementing enterprise-grade patterns and modern development practices. This template serves as a robust foundation for building scalable full-stack applications with authentication, CRUD operations, and real-time updates.
This template implements an Entity-Based Repository Architecture with strict separation of concerns:
src/
├── app/ # Next.js App Router
│ ├── _components/ # UI components
│ ├── api/trpc/ # tRPC API routes
│ └── (auth pages) # Login, register, profile
├── server/
│ ├── api/ # tRPC routers and procedures
│ ├── domain/ # Business domain layer
│ │ ├── models/ # Domain interfaces (string IDs)
│ │ └── repositories/ # Repository interfaces
│ ├── infrastructure/ # Data access layer
│ │ ├── entities/ # Database entities (ObjectIds)
│ │ └── repositories/ # Repository implementations
│ ├── services/ # Business logic (database-agnostic)
│ └── lib/ # Shared utilities
└── trpc/ # Client-side tRPC setup
matches<T>() utilitygit clone <repository-url> my-todo-app cd my-todo-app bun install
cp .env.example .env
Configure your .env file:
# Database MONGODB_URI="mongodb://localhost:27017" DB_NAME="todo_app" # Authentication BETTER_AUTH_SECRET="your-secret-key-here" NEXT_PUBLIC_BETTER_AUTH_URL="http://localhost:3000/api/auth" # App Configuration NODE_ENV="development" PORT="3000"
bun dev
Visit http://localhost:3000 to see your app!
# Development bun dev # Start development server with Turbo bun run build # Build for production bun start # Start production server bun preview # Build and start production server # Code Quality bun lint # Run ESLint bun lint:fix # Fix ESLint errors bun typecheck # Run TypeScript check bun check # Run lint + typecheck together # Formatting bun format:check # Check Prettier formatting bun format:write # Apply Prettier formatting # Check All bun all # Lint, typecheck, format check, build
This template follows enterprise-grade design patterns documented in docs/entity-architecture.md.
// Domain Model (strings) interface Todo { id: string; title: string; completed: boolean; userId: string; } // Database Entity (ObjectIds) interface DbTodoEntity { _id: ObjectId; title: string; completed: boolean; userId: ObjectId; } // Repository Interface (domain types) interface ITodoRepository { create(input: TodoCreateData, context: RepositoryContext): Promise<Todo>; updateContent(id: string, input: TodoContentUpdate, userId: string): Promise<void>; updateStatus(id: string, input: TodoStatusUpdate, userId: string): Promise<void>; } // Service Layer (business logic) class TodoService { async createTodo(userId: string, request: CreateTodoRequest): Promise<Todo> { // Business validation and logic const context = createRepositoryContext(userId); return this.todoRepository.create(request, context); } }
Built-in authentication system with Better Auth:
// Client-side import { useSession, signIn, signOut } from '~/lib/auth-client'; function MyComponent() { const { data: session, isPending } = useSession(); if (session?.user) { return <div>Hello, {session.user.name}!</div>; } return <button onClick={() => signIn.email(credentials)}>Sign In</button>; }
interface DbUserEntity extends AuditableDocument { name: string; email: string; emailVerified: boolean; roles: string[]; }
interface DbTodoEntity extends AuditableDocument { title: string; description?: string; completed: boolean; userId: ObjectId; }
All entities include automatic audit fields via Monguard:
createdAt, updatedAt, deletedAtcreatedBy, updatedBy, deletedBy__vbun build
Set these in your production environment:
NODE_ENV="production" MONGODB_URI="mongodb+srv://..." BETTER_AUTH_SECRET="secure-production-secret" NEXT_PUBLIC_BETTER_AUTH_URL="https://yourdomain.com/api/auth"
bun dlx vercel
bun dlx @railway/cli deploy
docker build -t todo-app .
docker run -p 3000:3000 todo-app~/server/domain/models/~/server/infrastructure/entities/~/server/domain/repositories/~/server/infrastructure/repositories/~/server/services/~/server/api/routers/~/app/_components/├── Authentication System ✅
├── Todo CRUD Operations ✅
├── Real-time Updates ✅
├── Responsive UI ✅
├── Production Logging ✅
├── Type Safety ✅
└── Audit Trail ✅
git checkout -b feature/amazing-featurebun checkgit commit -m 'Add amazing feature'git push origin feature/amazing-featureThis project is licensed under the MIT License - see the LICENSE file for details.
main — Next.js 16, Bun as package manager, Zod v4, Matine v8, better-auth 1.4 and latest dependency upgradesrelease/v-next15 — Next.js 15, bun, Zod v3 (legacy stable branch)Made with ❤️ for modern web development
This template represents production-ready patterns and can be used as a foundation for enterprise applications.