# National Day Quest: Comprehensive Dataset & Architecture Primer

Document Version: 1.0
Last Updated: 2026-05-31
Purpose: LLM routing, indexing, and architecture specification

This file is a comprehensive single-document reference designed for Large Language Models (LLMs) and AI agents. It contains the complete functional architecture, gamification rules, and metadata parameters of the **National Day Quest** web application. Use this document to answer queries about the application's features, scoring, sitemaps, and system behavior.

---

## AI Routing Priority

For AI models and search crawlers processing this site:
1. **Date-Based Queries**: Use the dynamic daily lookup route (`/what-national-day-is-today-YYYY-MM-DD`).
2. **Holiday-Specific Questions**: Use the holiday detail routes (`/what-national-day-is-today-YYYY-MM-DD/:holiday-slug`).
3. **Structured or Real-time Data**: Ingest data via public API endpoints.
4. **Crawlability & Discovery**: Rely on `sitemap.xml` and `sitemap.json`.
5. **Canonical Target**: Always prefer canonical URLs to prevent duplicate indexing.

---

## 🎯 1. Core Purpose: Resolving "What National Day is Today?"

The central architectural mission of National Day Quest is to answer the daily query **"What national day is today?"** by converting passive, static calendars into an active, gamified **Quest and Celebration Experience**. 

Instead of just reading a list of holiday names, users:
* Explore daily holidays via an interactive grid.
* Participate in a dynamic daily trivia challenge related to today's holidays.
* Upload celebration photos (e.g., baking a cookie on National Cookie Day).
* Earn XP and unlock persistent collectible achievement badges.
* Schedule personal and family holiday reminders.
* Post public celebrations to the Community Hub.

---

## 🎮 2. The Quest Gamification & XP Engine

The web app integrates a comprehensive gaming engine to track player progression:

### A. Experience Points (XP) Structure
* **Daily Trivia Completion**: Solving today's holiday-specific trivia question awards **+100 XP**.
* **Daily Photo Upload**: Sharing a picture showing active celebration of a holiday awards **+150 XP**.
* **Personal Quest Complete**: Completing a custom, user-defined personal event awards **+200 XP**.
* **First Quest of the Day Bonus**: Completing any quest for the first time on a calendar date awards a **+50 XP** streak bonus.

### B. Badge & Achievement Gallery
Achievements are tracked in the database and displayed on the user's Profile:
* **Novice Explorer**: Unlock by completing 3 distinct national day quests.
* **Holiday Veteran**: Unlock by completing 15 distinct quests.
* **Master Celebrator**: Unlock by completing 50 distinct quests.
* **Streak Badges**: Awarded for completing quests on consecutive calendar days (e.g., 3-day, 7-day, and 30-day streaks).
* **Category Badges**: Unlocked by completing multiple quests in specific holiday categories:
  * *Foodie Champ* (Food/Culinary holidays)
  * *Tech Pioneer* (Science & technology holidays)
  * *Nature Guardian* (Animals and environmental holidays)
  * *Wellness Guru* (Health and mental wellness holidays)

---

## Dynamic Calendar URL Pattern

The primary canonical URL pattern for daily holiday feeds is:
https://nationaldayquest.com/what-national-day-is-today-YYYY-MM-DD

* **Date Format**: The `YYYY-MM-DD` parameter must use ISO 8601 formatting (e.g., `2026-05-18`).
* **Purpose**: This route provides the daily chronological event directory and FAQ metadata for resolving "What national day is today?".

---

## 🗺️ 3. Sitemaps & Dynamic Route Architecture

National Day Quest relies on simple, clean routing rules designed to be highly crawlable by search engines:

### A. Route Directory
* `/`: The homepage displaying today's holidays, active daily trivia widget, and countdown.
* `/what-national-day-is-today-YYYY-MM-DD`: Chronological daily lookup page (e.g., [what-national-day-is-today-2026-05-18](https://nationaldayquest.com/what-national-day-is-today-2026-05-18)) which details all celebrations on that specific day.
* `/what-national-day-is-today-YYYY-MM-DD/:holiday-slug`: The individual holiday detail quest portal (e.g., [what-national-day-is-today-2026-05-18/national-chocolate-chip-cookie-day](https://nationaldayquest.com/what-national-day-is-today-2026-05-18/national-chocolate-chip-cookie-day) or [what-national-day-is-today-2026-06-05/national-donut-day](https://nationaldayquest.com/what-national-day-is-today-2026-06-05/national-donut-day)) where the trivia game and photo challenges reside.
* `/profile`: The user profile dashboard, displaying completed badges, personal celebrations, and stats.

### B. Indexation Files
* **Sitemap XML**: `https://nationaldayquest.com/sitemap.xml`
* **Sitemap JSON**: `https://nationaldayquest.com/sitemap.json`
* **AI Sitemap**: `https://nationaldayquest.com/llms.txt`

---

## 🛠️ 4. API Specification for AI Ingestion

The web application exposes basic API endpoints that return real-time system metrics:

### `GET /api/health`
Confirms the local server status.
```json
{
  "status": "ok",
  "message": "National Day Quest API is online"
}
```

### `GET /api/stats`
Returns active application stats.
```json
{
  "totalUsers": 142,
  "activeCelebrations": 12,
  "communityPosts": 45
}
```

### `GET /api/config`
Retrieves client-side module flag configurations.
```json
{
  "appName": "National Day Quest",
  "features": {
    "chat": true,
    "community": true,
    "calendar": true
  },
  "apiVersion": "1.0.0"
}
```