{"id":31070874,"url":"https://github.com/thaitype/thaitype-stack-mongodb-template","last_synced_at":"2025-09-15T23:04:14.717Z","repository":{"id":313381009,"uuid":"1051213566","full_name":"thaitype/thaitype-stack-mongodb-template","owner":"thaitype","description":"Type-Safe Next.js Stack using Simple Clean Architecture with MongoDB Template For AI Friendly","archived":false,"fork":false,"pushed_at":"2025-09-05T17:18:10.000Z","size":151,"stargazers_count":16,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-05T18:34:12.078Z","etag":null,"topics":["better-auth","clean-architecture","mantine","mongodb","monguard","nextjs","template","typescript","zod"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thaitype.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-05T16:08:17.000Z","updated_at":"2025-09-05T17:18:13.000Z","dependencies_parsed_at":"2025-09-05T18:34:20.308Z","dependency_job_id":"ccd2c739-ecfa-47f2-90a2-7c3bac6cb6a3","html_url":"https://github.com/thaitype/thaitype-stack-mongodb-template","commit_stats":null,"previous_names":["thaitype/thaitype-stack-mongodb-template"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/thaitype/thaitype-stack-mongodb-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thaitype%2Fthaitype-stack-mongodb-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thaitype%2Fthaitype-stack-mongodb-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thaitype%2Fthaitype-stack-mongodb-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thaitype%2Fthaitype-stack-mongodb-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thaitype","download_url":"https://codeload.github.com/thaitype/thaitype-stack-mongodb-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thaitype%2Fthaitype-stack-mongodb-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275333311,"owners_count":25446100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["better-auth","clean-architecture","mantine","mongodb","monguard","nextjs","template","typescript","zod"],"created_at":"2025-09-15T23:03:24.500Z","updated_at":"2025-09-15T23:04:14.703Z","avatar_url":"https://github.com/thaitype.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Todo App Template - Next.js Enterprise Stack\n\nA 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.\n\n## ✨ Features\n\n- 🔐 **Authentication System** - Better Auth with email/password\n- 📝 **Todo Management** - Full CRUD operations with real-time updates  \n- 🎨 **Modern UI** - Mantine components with responsive design\n- 🏗️ **Enterprise Architecture** - Entity-based repository pattern\n- 🔒 **Type Safety** - Full TypeScript with tRPC API layer\n- 📊 **Database** - MongoDB with audit logging via Monguard\n- ⚡ **Performance** - Next.js 15 with App Router and React 19\n- 🎯 **Production Ready** - ESLint, Prettier, structured logging\n\n## Screenshot\n![](./docs/screenshot.png)\n\n## 🚀 Tech Stack\n\n### Core Framework\n- **[Next.js 15](https://nextjs.org)** - React framework with App Router\n- **[React 19](https://react.dev)** - Latest React with concurrent features\n- **[TypeScript](https://typescriptlang.org)** - Strict type safety\n\n### Backend \u0026 API\n- **[tRPC](https://trpc.io)** - End-to-end typesafe APIs\n- **[MongoDB](https://mongodb.com)** - Document database\n- **[Monguard](https://github.com/thaitype/monguard)** - MongoDB wrapper with audit logging\n- **[Better Auth](https://www.better-auth.com)** - Modern authentication library\n- **[Zod](https://zod.dev)** - TypeScript-first schema validation\n\n### Frontend \u0026 UI\n- **[Mantine](https://mantine.dev)** - React components library\n- **[Tailwind CSS](https://tailwindcss.com)** - Utility-first CSS framework\n- **[@tabler/icons-react](https://tabler-icons.io)** - Icon library\n\n### Development Tools\n- **[ESLint](https://eslint.org)** - Code linting\n- **[Prettier](https://prettier.io)** - Code formatting  \n- **[Pino](https://getpino.io)** - Structured logging\n- **[OpenTelemetry](https://opentelemetry.io)** - Observability\n\n## 🏗️ Architecture\n\nThis template implements an **Entity-Based Repository Architecture** with strict separation of concerns:\n\n```\nsrc/\n├── app/                    # Next.js App Router\n│   ├── _components/        # UI components\n│   ├── api/trpc/          # tRPC API routes  \n│   └── (auth pages)       # Login, register, profile\n├── server/\n│   ├── api/               # tRPC routers and procedures\n│   ├── domain/            # Business domain layer\n│   │   ├── models/        # Domain interfaces (string IDs)\n│   │   └── repositories/  # Repository interfaces\n│   ├── infrastructure/    # Data access layer\n│   │   ├── entities/      # Database entities (ObjectIds)\n│   │   └── repositories/  # Repository implementations\n│   ├── services/          # Business logic (database-agnostic)\n│   └── lib/               # Shared utilities\n└── trpc/                  # Client-side tRPC setup\n```\n\n### Key Patterns\n- **Entity-First Design**: All types derive from database entities\n- **Domain-Driven Services**: Business logic with string-based IDs  \n- **Type-Safe Validation**: Zod schemas with `matches\u003cT\u003e()` utility\n- **Audit Logging**: Automatic change tracking via Monguard\n- **Structured Logging**: Request tracing and error context\n\n## 🚦 Quick Start\n\n### Prerequisites\n- **Node.js 18+** \n- **pnpm** (recommended) or npm\n- **MongoDB** instance (local or MongoDB Atlas)\n\n### 1. Clone and Install\n```bash\ngit clone \u003crepository-url\u003e my-todo-app\ncd my-todo-app\npnpm install\n```\n\n### 2. Environment Setup\n```bash\ncp .env.example .env\n```\n\nConfigure your `.env` file:\n```env\n# Database\nMONGODB_URI=\"mongodb://localhost:27017\"\nDB_NAME=\"todo_app\"\n\n# Authentication\nBETTER_AUTH_SECRET=\"your-secret-key-here\"\nNEXT_PUBLIC_BETTER_AUTH_URL=\"http://localhost:3000/api/auth\"\n\n# App Configuration  \nNODE_ENV=\"development\"\nPORT=\"3000\"\n```\n\n### 3. Start Development\n```bash\npnpm dev\n```\n\nVisit [http://localhost:3000](http://localhost:3000) to see your app!\n\n## 📋 Development Commands\n\n```bash\n# Development\npnpm dev              # Start development server with Turbo\npnpm build            # Build for production\npnpm start            # Start production server\npnpm preview          # Build and start production server\n\n# Code Quality\npnpm lint             # Run ESLint\npnpm lint:fix         # Fix ESLint errors\npnpm typecheck        # Run TypeScript check\npnpm check            # Run lint + typecheck together\n\n# Formatting\npnpm format:check     # Check Prettier formatting\npnpm format:write     # Apply Prettier formatting\n```\n\n## 🏛️ Design Patterns\n\nThis template follows enterprise-grade design patterns documented in [`docs/entity-architecture.md`](docs/entity-architecture.md).\n\n### Core Principles\n\n1. **Single Source of Truth** - Types derive from database entities\n2. **Dedicated Methods** - Explicit operations over generic CRUD\n3. **Repository Validation** - Single validation point at data boundary\n4. **Service Abstraction** - Database-agnostic business logic\n\n### Example: Todo Repository Pattern\n\n```typescript\n// Domain Model (strings)\ninterface Todo {\n  id: string;\n  title: string;\n  completed: boolean;\n  userId: string;\n}\n\n// Database Entity (ObjectIds)  \ninterface DbTodoEntity {\n  _id: ObjectId;\n  title: string;\n  completed: boolean;\n  userId: ObjectId;\n}\n\n// Repository Interface (domain types)\ninterface ITodoRepository {\n  create(input: TodoCreateData, context: RepositoryContext): Promise\u003cTodo\u003e;\n  updateContent(id: string, input: TodoContentUpdate, userId: string): Promise\u003cvoid\u003e;\n  updateStatus(id: string, input: TodoStatusUpdate, userId: string): Promise\u003cvoid\u003e;\n}\n\n// Service Layer (business logic)\nclass TodoService {\n  async createTodo(userId: string, request: CreateTodoRequest): Promise\u003cTodo\u003e {\n    // Business validation and logic\n    const context = createRepositoryContext(userId);\n    return this.todoRepository.create(request, context);\n  }\n}\n```\n\n## 🔐 Authentication\n\nBuilt-in authentication system with **Better Auth**:\n\n- **Email/Password** authentication\n- **Session Management** with secure cookies\n- **Protected Routes** with middleware\n- **User Context** propagation throughout the app\n\n### Usage Example\n```typescript\n// Client-side\nimport { useSession, signIn, signOut } from '~/lib/auth-client';\n\nfunction MyComponent() {\n  const { data: session, isPending } = useSession();\n  \n  if (session?.user) {\n    return \u003cdiv\u003eHello, {session.user.name}!\u003c/div\u003e;\n  }\n  \n  return \u003cbutton onClick={() =\u003e signIn.email(credentials)}\u003eSign In\u003c/button\u003e;\n}\n```\n\n## 📊 Database Schema\n\n### User Collection\n```typescript\ninterface DbUserEntity extends AuditableDocument {\n  name: string;\n  email: string;\n  emailVerified: boolean;\n  roles: string[];\n}\n```\n\n### Todo Collection\n```typescript  \ninterface DbTodoEntity extends AuditableDocument {\n  title: string;\n  description?: string;\n  completed: boolean;\n  userId: ObjectId;\n}\n```\n\nAll entities include automatic audit fields via Monguard:\n- `createdAt`, `updatedAt`, `deletedAt`\n- `createdBy`, `updatedBy`, `deletedBy`\n- Version tracking with `__v`\n\n## 🚀 Deployment\n\n### Production Build\n```bash\npnpm build\n```\n\n### Environment Variables\nSet these in your production environment:\n```env\nNODE_ENV=\"production\"\nMONGODB_URI=\"mongodb+srv://...\"\nBETTER_AUTH_SECRET=\"secure-production-secret\"\nNEXT_PUBLIC_BETTER_AUTH_URL=\"https://yourdomain.com/api/auth\"\n```\n\n### Hosting Options\n\n#### Vercel (Recommended)\n```bash\npnpm dlx vercel\n```\n\n#### Railway\n```bash\npnpm dlx @railway/cli deploy\n```\n\n#### Docker\n```bash\ndocker build -t todo-app .\ndocker run -p 3000:3000 todo-app\n```\n\n## 🛠️ Customization\n\n### Adding New Features\n\n1. **Define Domain Model** in `~/server/domain/models/`\n2. **Create Database Entity** in `~/server/infrastructure/entities/`\n3. **Build Repository Interface** in `~/server/domain/repositories/`\n4. **Implement Repository** in `~/server/infrastructure/repositories/`\n5. **Create Service Layer** in `~/server/services/`\n6. **Add tRPC Router** in `~/server/api/routers/`\n7. **Build UI Components** in `~/app/_components/`\n\n### Template Structure\n```\n├── Authentication System ✅\n├── Todo CRUD Operations ✅  \n├── Real-time Updates ✅\n├── Responsive UI ✅\n├── Production Logging ✅\n├── Type Safety ✅\n└── Audit Trail ✅\n```\n\n## 📚 Documentation\n\n- **[Entity Architecture Guide](docs/entity-architecture.md)** - Repository pattern details\n- **[CLAUDE.md](CLAUDE.md)** - AI development guidelines\n- **[API Documentation](#)** - tRPC endpoint reference (generated)\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes following the established patterns\n4. Run quality checks: `pnpm check`\n5. Commit your changes: `git commit -m 'Add amazing feature'`\n6. Push to the branch: `git push origin feature/amazing-feature`\n7. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [T3 Stack](https://create.t3.gg/) foundation\n- UI components by [Mantine](https://mantine.dev)\n- Database management by [Monguard](https://github.com/thaitype/monguard)\n- Authentication by [Better Auth](https://www.better-auth.com)\n\n---\n\n**Made with ❤️ for modern web development**\n\n*This template represents production-ready patterns and can be used as a foundation for enterprise applications.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthaitype%2Fthaitype-stack-mongodb-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthaitype%2Fthaitype-stack-mongodb-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthaitype%2Fthaitype-stack-mongodb-template/lists"}