A production-ready Todo Application Template built with Next.js 15, 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.
- π Authentication System - Better Auth with email/password
- π Todo Management - Full CRUD operations with real-time updates
- π¨ Modern UI - Mantine components with responsive design
- ποΈ Enterprise Architecture - Entity-based repository pattern
- π Type Safety - Full TypeScript with tRPC API layer
- π Database - MongoDB with audit logging via Monguard
- β‘ Performance - Next.js 15 with App Router and React 19
- π― Production Ready - ESLint, Prettier, structured logging
- Next.js 15 - React framework with App Router
- React 19 - Latest React with concurrent features
- TypeScript - Strict type safety
- tRPC - End-to-end typesafe APIs
- MongoDB - Document database
- Monguard - MongoDB wrapper with audit logging
- Better Auth - Modern authentication library
- Zod - TypeScript-first schema validation
- Mantine - React components library
- Tailwind CSS - Utility-first CSS framework
- @tabler/icons-react - Icon library
- ESLint - Code linting
- Prettier - Code formatting
- Pino - Structured logging
- OpenTelemetry - Observability
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
- Entity-First Design: All types derive from database entities
- Domain-Driven Services: Business logic with string-based IDs
- Type-Safe Validation: Zod schemas with
matches<T>()
utility - Audit Logging: Automatic change tracking via Monguard
- Structured Logging: Request tracing and error context
- Node.js 18+
- pnpm (recommended) or npm
- MongoDB instance (local or MongoDB Atlas)
git clone <repository-url> my-todo-app
cd my-todo-app
pnpm 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"
pnpm dev
Visit http://localhost:3000 to see your app!
# Development
pnpm dev # Start development server with Turbo
pnpm build # Build for production
pnpm start # Start production server
pnpm preview # Build and start production server
# Code Quality
pnpm lint # Run ESLint
pnpm lint:fix # Fix ESLint errors
pnpm typecheck # Run TypeScript check
pnpm check # Run lint + typecheck together
# Formatting
pnpm format:check # Check Prettier formatting
pnpm format:write # Apply Prettier formatting
This template follows enterprise-grade design patterns documented in docs/entity-architecture.md
.
- Single Source of Truth - Types derive from database entities
- Dedicated Methods - Explicit operations over generic CRUD
- Repository Validation - Single validation point at data boundary
- Service Abstraction - Database-agnostic business logic
// 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:
- Email/Password authentication
- Session Management with secure cookies
- Protected Routes with middleware
- User Context propagation throughout the app
// 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
,deletedAt
createdBy
,updatedBy
,deletedBy
- Version tracking with
__v
pnpm 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"
pnpm dlx vercel
pnpm dlx @railway/cli deploy
docker build -t todo-app .
docker run -p 3000:3000 todo-app
- Define Domain Model in
~/server/domain/models/
- Create Database Entity in
~/server/infrastructure/entities/
- Build Repository Interface in
~/server/domain/repositories/
- Implement Repository in
~/server/infrastructure/repositories/
- Create Service Layer in
~/server/services/
- Add tRPC Router in
~/server/api/routers/
- Build UI Components in
~/app/_components/
βββ Authentication System β
βββ Todo CRUD Operations β
βββ Real-time Updates β
βββ Responsive UI β
βββ Production Logging β
βββ Type Safety β
βββ Audit Trail β
- Entity Architecture Guide - Repository pattern details
- CLAUDE.md - AI development guidelines
- API Documentation - tRPC endpoint reference (generated)
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes following the established patterns
- Run quality checks:
pnpm check
- Commit your changes:
git commit -m 'Add amazing feature'
- Push to the branch:
git push origin feature/amazing-feature
- Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with T3 Stack foundation
- UI components by Mantine
- Database management by Monguard
- Authentication by Better Auth
Made with β€οΈ for modern web development
This template represents production-ready patterns and can be used as a foundation for enterprise applications.