# xeland314/advent-calendar architecture

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

- Interactive diagram: https://gitdiagram.com/xeland314/advent-calendar
- Repository: https://github.com/xeland314/advent-calendar

## Overview

##### Project type and purpose
- This is a static, front-end–only web application built with Next.js (React) and exported as a static site (GitHub Pages).
- Purpose: an interactive Advent calendar that reveals daily virtual gifts, uses date logic to enable content, includes animations and a countdown timer.

##### File structure
Top-level:
- .github/workflows/nextjs.yml – CI/CD workflow for build and deployment
- public/ – static assets (manifest.webmanifest, service worker sw.js, pixel-art images)
- src/app/ – Next.js App Router: pages, layout, components, hooks, utilities
- config files – next.config.ts, tailwind.config.ts, jest.config.ts, eslint.config.mjs, tsconfig.json
Under src/app:
- page.tsx, layout.tsx, not-found.tsx – routing and global layout
- components/ – UI building blocks (Header, Footer, Gift, AnimatedBall, Calendar, CountdownTimer, SnowFlake, etc.)
- hooks/ – custom React hooks (useCountdownTimer)
- utils/ – helper functions (getFormattedDate, getFormattedTimeLeft) and tests
- app/coal-gift/page.tsx – a dynamic “gift” page

##### README for additional insights
- Confirms static export, UI-focused features (animations, date gating), technologies (Next.js, React, Tailwind)
- No backend or API; all logic runs client-side

##### Main components
A. Build & Deployment Pipeline
- Source code repository (GitHub) → GitHub Actions (“nextjs.yml”) runs `npm run build` and `npm run export` → static artifacts
- Deployment to GitHub Pages or CDN
B. Static Hosting Layer
- CDN/Hosting (GitHub Pages) serves index.html, JS bundles, CSS, manifest, service worker, image assets
C. Client (Browser) Runtime
1. Browser requests static assets
2. Service Worker (public/sw.js) registers & caches files for offline support
3. Next.js–generated JavaScript bundles hydrate React on the client
D. React Application Structure
- Layout component – Header, Footer, global CSS
- Page components – Calendar grid (24 Gift components), CoalGift page
- Shared components – AnimatedBall, SnowFlake (decorative), CountdownTimer, Calendar, Gift
- Hooks & Utils – useCountdownTimer (countdown logic), getFormattedDate/TimeLeft (date formatting)
E. Data Flow & User Interaction
- On page load, hook reads system date → calculates available gift indexes
- CountdownTimer component updates every second via hook

##### Architectural patterns and design principles
- Static Site Generation (SSG) – Next.js export for performance and simplicity
- Component-driven design – small, reusable React components
- Custom hooks for encapsulating stateful logic
- Utility modules for pure functions and date logic
- Client-only logic (no server)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Build & Deployment Pipeline"
        Repo["GitHub Repo"]:::green
        CI["GitHub Actions"]:::green
        Build["npm run build"]:::green
        Export["npm run export"]:::green
        Artifact["Static Artifacts"]:::green
        Repo --> CI --> Build --> Export --> Artifact
    end

    subgraph "Static Hosting Layer"
        CDN["CDN / GitHub Pages"]:::blue
        Artifact --> CDN
    end

    subgraph "Client (Browser)"
        Browser["Browser"]:::orange
        ServiceWorker["Register Service Worker"]:::orange
        SW["Service Worker (sw.js)"]:::orange
        Manifest["Web Manifest"]:::orange
        Browser -->|"requests assets"| CDN
        Browser --> ServiceWorker
        ServiceWorker --> SW
        ServiceWorker --> Manifest
    end

    subgraph "React Application"
        Hydrate["React Hydration"]:::orange
        Browser --> Hydrate

        Layout["Global Layout"]:::purple
        PageRoot["App Router Entry (page.tsx)"]:::purple

        subgraph "Pages"
            CalendarPage["Calendar Page"]:::purple
            CoalGiftPage["Coal Gift Page"]:::purple
            NotFound["404 Page"]:::purple
        end

        subgraph "Shared Components"
            Header["Header"]:::purple
            Footer["Footer"]:::purple
            CalendarComp["Calendar"]:::purple
            GiftComp["Gift"]:::purple
            DayGift["DayGift"]:::purple
            CountdownGift["CountdownGift"]:::purple
            CoalGiftComp["CoalGift UI"]:::purple
            AnimatedBall["AnimatedBall"]:::purple
            SnowFlake["SnowFlake"]:::purple
            CountdownTimer["CountdownTimer"]:::purple
        end

        subgraph "Logic"
            Hooks["Custom Hooks"]:::purple
            useCountdownTimer["useCountdownTimer"]:::purple
            Utils["Utilities"]:::purple
            DateFmt["getFormattedDate"]:::purple
            TimeFmt["getFormattedTimeLeft"]:::purple
        end

        Hydrate --> Layout
        Hydrate --> PageRoot
        Layout --> Header
        Layout --> Footer
        PageRoot --> CalendarPage
        PageRoot --> CoalGiftPage
        PageRoot --> NotFound
        CalendarPage --> CalendarComp
        CalendarComp --> GiftComp
        GiftComp --> DayGift
        GiftComp --> CountdownGift
        GiftComp --> CoalGiftComp
        GiftComp --> AnimatedBall
        GiftComp --> SnowFlake
        GiftComp --> CountdownTimer
        CountdownTimer --> useCountdownTimer
        useCountdownTimer --> Hooks
        Utils --> DateFmt
        Utils --> TimeFmt
    end

    %% Click Events
    click CI "https://github.com/xeland314/advent-calendar/blob/main/.github/workflows/nextjs.yml"
    click CDN "https://github.com/xeland314/advent-calendar/tree/main/public/"
    click SW "https://github.com/xeland314/advent-calendar/blob/main/public/sw.js"
    click Manifest "https://github.com/xeland314/advent-calendar/blob/main/public/manifest.webmanifest"
    click PageRoot "https://github.com/xeland314/advent-calendar/blob/main/src/app/page.tsx"
    click Layout "https://github.com/xeland314/advent-calendar/blob/main/src/app/layout.tsx"
    click NotFound "https://github.com/xeland314/advent-calendar/blob/main/src/app/not-found.tsx"
    click CoalGiftPage "https://github.com/xeland314/advent-calendar/blob/main/src/app/coal-gift/page.tsx"
    click Header "https://github.com/xeland314/advent-calendar/blob/main/src/app/components/Header.tsx"
    click Footer "https://github.com/xeland314/advent-calendar/blob/main/src/app/components/Footer.tsx"
    click CalendarComp "https://github.com/xeland314/advent-calendar/blob/main/src/app/components/Calendar.tsx"
    click GiftComp "https://github.com/xeland314/advent-calendar/blob/main/src/app/components/Gift.tsx"
    click DayGift "https://github.com/xeland314/advent-calendar/blob/main/src/app/components/DayGift.tsx"
    click CountdownGift "https://github.com/xeland314/advent-calendar/blob/main/src/app/components/CountdownGift.tsx"
    click CoalGiftComp "https://github.com/xeland314/advent-calendar/blob/main/src/app/components/CoalGift.tsx"
    click AnimatedBall "https://github.com/xeland314/advent-calendar/blob/main/src/app/components/AnimatedBall.tsx"
    click SnowFlake "https://github.com/xeland314/advent-calendar/blob/main/src/app/components/SnowFlake.tsx"
    click CountdownTimer "https://github.com/xeland314/advent-calendar/blob/main/src/app/components/CountdownTimer.tsx"
    click Hooks "https://github.com/xeland314/advent-calendar/blob/main/src/app/hooks/index.ts"
    click useCountdownTimer "https://github.com/xeland314/advent-calendar/blob/main/src/app/hooks/useCountdownTimer.ts"
    click Utils "https://github.com/xeland314/advent-calendar/blob/main/src/app/utils/index.ts"
    click DateFmt "https://github.com/xeland314/advent-calendar/blob/main/src/app/utils/getFormattedDate.ts"
    click TimeFmt "https://github.com/xeland314/advent-calendar/blob/main/src/app/utils/getFormattedTimeLeft.ts"

    %% Styles
    classDef green fill:#b2f2bb,stroke:#333,stroke-width:1px
    classDef blue fill:#aed6f1,stroke:#333,stroke-width:1px
    classDef orange fill:#f5b041,stroke:#333,stroke-width:1px
    classDef purple fill:#d7bde2,stroke:#333,stroke-width:1px
```
