A gamified advent calendar web application for tea lovers, built with Next.js 16, featuring daily challenges, user authentication, and a ranking system. This app is designed for the community participating in this special event.
Each accepted participant is responsible for curating their assigned day, updating tea information, and setting the daily atmosphere. A logistical coordinator (affectionately known as the Execu-TEA-ve) assigns days and manages the distribution of physical tea packs to all participants beforehand.
On the designated days (typically early December), the cycle unfolds as follows:
- Morning: Essential brewing instructions and initial mood setting.
- Noon & Afternoon: Enhanced atmosphere (music, photos, stories) is revealed.
- Evening: The tea's identity and purchase details are finally unveiled.
Participants can also play AdivinaTé (Guess the Tea). Registered users earn points by guessing any or all of the following: tea name, ingredients, type, and/or the contributor. You can guess just one field or all of them. Points for each correct guess are calculated immediately and stored, and revealed at the same time as tea name but if you only guess the contributor the points remain hidden until the final revelation day.
- 🔐 Secure Authentication: User registration, login, and password recovery with BetterAuth
- 📅 Interactive Calendar: Grid-based advent calendar with daily tea reveals
- 🎮 Gamification: Guess tea info daily and earn points based on accuracy and timing
- 🏆 Ranking System: Daily and overall leaderboards with highlighted top 3 users
- 📖 Story Content: Progressive narrative reveals with optional YouTube media
- 🖼️ Image Management: Cloudinary integration for avatars and tea day images
- 👥 User Roles: Admin (full system access), Execu-TEA-ve (curate all teas and stories), and User (assigned to one specific day)
- ✅ Test-Driven Development: Vitest + React Testing Library
- User: Authentication, profile, assigned day
- Day: Tea information (name, infusion time, properties)
- TeaIngredient: Ingredients associated with a Tea
- StoryTea: Narrative content with progressive reveals
- TeaGuess: User guesses with calculated points
- StoryImage: Multiple images per tea day story
- Badge (Future): Achievement definitions
- UserBadge (Future): User-badge assignments
- Tea name, ingredients, and type are revealed
- If a user only guesses the contributor, points remain hidden until final day
- Daily ranking is updated
- Contributor identity remains hidden until final day
- Overall ranking is shown after final day
-
What you can guess (any combination):
- Tea name
- Ingredients
- Tea type
- Contributor (who proposed this tea)
-
Scoring:
- Submit guesses anytime before reveal time
- Points calculated immediately using string similarity algorithm
- Only your last guess for each field counts
This project uses cutting-edge technologies to explore modern web development patterns and evaluate their production-readiness:
Next.js 16 (App Router)
- Native server actions for type-safe mutations without API routes
- Async dynamic params (
await params) for cleaner route handling - Turbopack stability for faster dev/build cycles
Tailwind CSS v4 + daisyUI 5
- New
@importand@pluginsyntax for simplified configuration - Inline theme definitions for better maintainability
- Component-first approach with daisyUI reducing custom CSS by ~60%
BetterAuth over NextAuth
- Type-safe auth with zero config boilerplate
- Built-in Prisma adapter with proper TypeScript inference
- Simpler session management for this use case (no OAuth complexity needed)
Vitest over Jest
- Resolved Jest compatibility issues with Prisma in integration tests (ESM/CommonJS mismatch)
- Native ESM support eliminates transform configuration overhead
- Faster test execution in watch mode
- Better TypeScript integration out-of-the-box
- Benefits: Modern DX, performance improvements, cleaner codebase
- Risks: Limited community resources, potential breaking changes
- Mitigation: Comprehensive test coverage (TDD), detailed documentation, MCP integration for AI-assisted documentation
- Mastered Next.js 16 async patterns and Server Component best practices
- Evaluated Tailwind v4 migration path (worth it for new projects)
- Proved BetterAuth viability for production auth flows
- Developed workflows for managing bleeding-edge dependencies safely
The code adheres to high-quality software engineering standards to ensure maintainability, scalability, and code health:
- SOLID Principles: Ensuring modular and testable component architecture.
- KISS & DRY: Keeping logic simple and avoiding duplication, especially in server actions and services.
- Clean Code: Meaningful naming conventions, small functions, and self-documenting code.
- TDD (Test-Driven Development): Writing tests before implementation to guide design and ensure reliability.
- Mobile-First: Designing UI/UX priorities for mobile devices using Tailwind's responsive utilities.
This project leverages modern AI tools to enhance productivity and code quality:
- AI Agents: Specialized roles defined in
AGENTS.md(e.g., UI Agent, Database Agent, Testing Agent) to handle specific domains. - MCP (Model Context Protocol): Integration with external tools (GitHub, Sentry, Documentation) to provide rich context to the AI assistant.
- GitHub Copilot: Used for code generation, refactoring, and following the strict guidelines defined in
.github/copilot-instructions.md.
- Node.js 18.17 or later
- pnpm (recommended) or npm/yarn/bun
- Clone the repository
git clone https://github.com/CarlosCanet/advientea.git
cd advientea- Install dependencies
# Using pnpm (recommended)
pnpm install
# Or using npm
npm install- Set up environment variables
cp .env.example .envEdit .env and add your credentials.
- Set up the database
# Using pnpm
pnpm dlx prisma generate
pnpm dlx prisma migrate dev --name init
# Or using npx
npx prisma generate
npx prisma migrate dev --name init- Run the development server
# Using pnpm
pnpm dev
# Or using npm
npm run devOpen http://localhost:3000 with your browser to see the result.
npm run dev # Start development server with Turbopack
npm run build # Build for production
npm run start # Start production server
npm run lint # Run ESLint
npm run test # Run tests with Vitest
npx prisma studio # Open Prisma Studio (DB GUI)- AGENTS.md - Agent roles and responsibilities for AI development
- copilot-instructions.md - Coding standards and patterns
- daisyUI Instructions - UI component guidelines