How thatsourjake/advent-cal-2023 works
Project Type and Purpose
• The project is a full-stack web application built using Next.js. Its primary goal is to run an advent calendar event where users can log in, register, and play various games (such as Find Santa, Spot the Difference, Matching Pairs, Quiz, Riddle, Lucky Wheel, Word Fill-ins, and Wordle) with unique scoring schemes.
• The application not only renders day-specific pages based on the advent calendar but also processes game submissions via dedicated API endpoints with scoring calculations.
Main Components
• Frontend (Presentation Layer):
• Next.js Pages: Located in the “app” folder (e.g., app/page.tsx, app/day/[n]/page.tsx, app/login/page.tsx, app/register/page.tsx, app/leaderboard/page.tsx).
• UI Components: Found in the “app/components” directory. These include game UIs (such as crosswords, spot the difference, etc.), generic UI elements (alert, loading, home banners) and special components handling game-specific logic.
• Styling: Global CSS (app/globals.css) and Tailwind CSS configured through tailwind.config.ts.
• API Layer (Business Logic/Backend Processing):
• API Endpoints: Under “app/api” to handle game submissions and scoring. The “app/api/submit-game” folder holds API routes and a nested “calculate-score” directory in which individual scoring modules (e.g., diff.ts, match.ts, quiz.ts, etc.) compute game scores based on the published rules in the README.
• Other API endpoints like “app/api/day-game-map.ts” which likely maps advent calendar days to game content.
• Service/Database Integration:
• MongoDB Integration: The file “app/services/mongo.ts” indicates that MongoDB is used, possibly to store user data, scores, and game progress.
• Utilities and Helpers:
• Utility Functions: Located in “app/utils”, they manage aspects like API calls, random number generation, score calculations, and general validations.
• Core Infrastructure/Configuration:
• Middleware: “middleware.ts” probably handles authentication, form validation, or other request-based processing.
• Docker and Build Configurations: With Dockerfile, .dockerignore, and configuration files like next.config.js, tailwind.config.ts, and tsconfig.json indicating containerization and environment setup.
• Logger: “logger.ts” for application logging.
• Public Assets:
Relationships and Interactions
• Users interact with the frontend, which renders interactive pages using React components.
• When a game is played, the frontend sends submission requests to the API endpoints (under “app/api/submit-game”).
• The API endpoints route calls to specific scoring modules in the “calculate-score” directory. Each module (e.g., quiz.ts, word.ts, etc.) uses the scoring rules defined in the README.
• Calculated scores and relevant game data may be persisted or retrieved via the MongoDB service, as defined in “app/services/mongo.ts”.
• Utility functions and middleware support data validation, user authentications (login/register), and logging.
• The built Docker setup ensures the entire environment (both server and application) is containerized for deployment.
Architectural Patterns and Principles
• Separation of Concerns: Distinct separation between UI (components and pages), business logic (API endpoints and score calculations), and persistence (MongoDB service).
• Modular Design: Each game scoring logic is encapsulated into its own module inside the “app/api/submit-game/calculate-score” directory.
• Routing and Page Management: Use of Next.js file-based routing (under “app/day”, “app/login”, “app/register”) is evident, supporting a clear delineation of application sections.
• Reusability: Shared utility modules facilitate common tasks (e.g., random number generation, validation).