# thatsourjake/advent-cal-2023 architecture

> Architecture diagram of the GitHub repository thatsourjake/advent-cal-2023, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thatsourjake/advent-cal-2023
- Repository: https://github.com/thatsourjake/advent-cal-2023

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    U["User"]:::user

    %% Frontend (Next.js)
    subgraph "Frontend (Next.js)"
        HP["Home Page"]:::frontend
        DP["Day Page"]:::frontend
        LP["Login Page"]:::frontend
        RP["Register Page"]:::frontend
        LBP["Leaderboard Page"]:::frontend
        UI["UI Components"]:::frontend
        GC["Global CSS"]:::frontend
        TC["Tailwind Config"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        GA["Game Submission API"]:::api
        SM["Scoring Modules"]:::api
        DM["Day-Game Mapping API"]:::api
    end

    %% Persistence Layer
    subgraph "Persistence"
        MS["MongoDB Service"]:::db
    end

    %% Utilities and Helpers
    UTL["Utility Functions"]:::utils

    %% Infrastructure & Configuration
    subgraph "Infrastructure & Config"
        MW["Middleware"]:::infra
        LG["Logger"]:::infra
        CF["Configurations"]:::infra
    end

    %% Public Assets
    PA["Public Assets"]:::assets

    %% Connections
    U --> HP
    HP --> UI
    UI -->|"submitGame"| GA
    GA --> SM
    GA --> DM
    SM --> MS

    UTL --> UI
    UTL --> GA

    MW --> UI
    MW --> GA
    CF --> MW

    UI --> LG
    GA --> LG

    PA --> UI

    %% Click Events
    click HP "https://github.com/thatsourjake/advent-cal-2023/blob/main/app/page.tsx"
    click DP "https://github.com/thatsourjake/advent-cal-2023/blob/main/app/day/1/page.tsx"
    click LP "https://github.com/thatsourjake/advent-cal-2023/blob/main/app/login/page.tsx"
    click RP "https://github.com/thatsourjake/advent-cal-2023/blob/main/app/register/page.tsx"
    click LBP "https://github.com/thatsourjake/advent-cal-2023/blob/main/app/leaderboard/page.tsx"
    click UI "https://github.com/thatsourjake/advent-cal-2023/tree/main/app/components"
    click GC "https://github.com/thatsourjake/advent-cal-2023/blob/main/app/globals.css"
    click TC "https://github.com/thatsourjake/advent-cal-2023/blob/main/tailwind.config.ts"
    click GA "https://github.com/thatsourjake/advent-cal-2023/blob/main/app/api/submit-game/route.ts"
    click SM "https://github.com/thatsourjake/advent-cal-2023/tree/main/app/api/submit-game/calculate-score"
    click DM "https://github.com/thatsourjake/advent-cal-2023/blob/main/app/api/day-game-map.ts"
    click MS "https://github.com/thatsourjake/advent-cal-2023/blob/main/app/services/mongo.ts"
    click UTL "https://github.com/thatsourjake/advent-cal-2023/tree/main/app/utils"
    click MW "https://github.com/thatsourjake/advent-cal-2023/blob/main/middleware.ts"
    click LG "https://github.com/thatsourjake/advent-cal-2023/blob/main/logger.ts"
    click CF "https://github.com/thatsourjake/advent-cal-2023/tree/main/Dockerfile"
    click PA "https://github.com/thatsourjake/advent-cal-2023/tree/main/public"

    %% Styles
    classDef frontend fill:#e1f5fe,stroke:#0277bd,stroke-width:2px;
    classDef api fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef db fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;
    classDef infra fill:#fffde7,stroke:#f9a825,stroke-width:2px;
    classDef utils fill:#fff3e0,stroke:#ef6c00,stroke-width:2px;
    classDef assets fill:#fbe9e7,stroke:#d84315,stroke-width:2px;
    classDef user fill:#e0f2f1,stroke:#00695c,stroke-width:2px;
```
