# piyushsarkar-dev/digital-clock-app architecture

> Architecture diagram of the GitHub repository piyushsarkar-dev/digital-clock-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/piyushsarkar-dev/digital-clock-app
- Repository: https://github.com/piyushsarkar-dev/digital-clock-app

## Overview

1. **Overall shape**
   - This is a small, single-page Next.js App Router app with no backend and no API layer.
   - The architecture is mainly a composition of client-side UI components around one central live clock display.

2. **Application shell**
   - `src/app/layout.tsx` defines the global app shell: document structure, shared providers, and global styles.
   - `src/app/page.tsx` is the single route that assembles the visible clock experience.

3. **Theme subsystem**
   - `src/components/Providers/ThemeProvider.tsx` wraps the app with `next-themes` support.
   - Theme state is global and drives dark/light mode styling across the page, including theme-specific visuals and the toggle control.

4. **Header and user controls**
   - `src/components/Header/Header.tsx` provides the top-level chrome for the page.
   - `src/components/ThemeToggleButton.tsx` is the main user interaction for switching themes and is a thin control over the shared theme state.

5. **Clock subsystem**
   - `src/components/Clock.tsx` is the core feature component.
   - It owns the live time/date presentation and is the main data-flow endpoint for the app: current time is read locally, transformed into display-friendly parts, and rendered continuously.

6. **Animated time rendering**
   - The clock display is not static text; it uses smooth digit transitions via `@number-flow/react` and an animated AM/PM indicator.
   - This makes the clock a client-driven, frequently updating component rather than a server-rendered snapshot.

7. **Glassmorphism visual layer**
   - `src/components/GlassSurface.tsx` is the visual container that creates the “liquid glass” panel.
   - It is a presentation boundary around the clock content, using SVG filter effects such as blur, displacement, and chromatic offsets to produce the frosted/refractive look.

8. **Design-system primitives**
   - `src/components/shadcnui/aurora-text.tsx` and `src/components/shadcnui/text-animate.tsx` are reusable animation/text primitives.
   - These are supporting UI building blocks rather than business logic, used to achieve the polished animated typography in the clock scene.

9. **Shared utilities and assets**
   - `src/lib/fonts.ts` centralizes font setup, and `src/lib/utils.ts` holds shared helper logic.
   - `public/` likely contains the visual assets used for the themed backgrounds and decorative effects referenced in the README.

10. **Styling and layout boundaries**
   - `src/app/globals.css` plus Tailwind/PostCSS form the global styling layer.
   - The page’s visual structure is driven by utility-first styling, with the glass panel, background, typography, and layout all composed in the UI layer rather than through separate domain services.

11. **Execution model**
   - The app’s runtime is mostly client-side once the page loads, because live time updates and theme switching require interactivity.
   - The server’s role is primarily to deliver the initial Next.js page and assets; there are no persistent data stores, queues, or external service dependencies in the repository.

12. **Architecture summary for a diagram**
   - A good diagram would show: Next.js app shell → theme provider → page composition → header/theme toggle + glass surface → clock/animated text primitives.
   - The main flow is local state and time input flowing into the clock UI, with theme state flowing across the whole visual layer.

Main entry points: [`src/app/page.tsx`](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/app/page.tsx) (Clock Page), [`src/components/Clock.tsx`](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/Clock.tsx) (Clock), [`src/components/Providers/ThemeProvider.tsx`](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/Providers/ThemeProvider.tsx) (Theme Provider), [`src/app/layout.tsx`](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/app/layout.tsx) (App Layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_layout["App Layout<br/>Next.js shell<br/>[layout.tsx]"]
  node_page["Clock Page<br/>route<br/>[page.tsx]"]
  node_globals["Global CSS<br/>style layer<br/>[globals.css]"]
end

subgraph group_components["UI Components"]
  node_themeprovider["Theme Provider<br/>theme context<br/>[ThemeProvider.tsx]"]
  node_header["Header<br/>page chrome<br/>[Header.tsx]"]
  node_themetoggle(("Theme Toggle<br/>theme control"))
  node_clock["Clock<br/>live display<br/>[Clock.tsx]"]
  node_glasssurface["Glass Surface<br/>visual shell<br/>[GlassSurface.tsx]"]
end

subgraph group_primitives["Animated Primitives"]
  node_aurora["Aurora Text<br/>text primitive<br/>[aurora-text.tsx]"]
  node_textanimate["Text Animate<br/>animation primitive<br/>[text-animate.tsx]"]
end

subgraph group_shared["Shared Layer"]
  node_fonts["Fonts<br/>font setup<br/>[fonts.ts]"]
  node_utils["Utils<br/>helper lib<br/>[utils.ts]"]
  node_assets["Public Assets<br/>static assets"]
end

node_layout -->|"wraps"| node_themeprovider
node_layout -->|"loads"| node_globals
node_layout -->|"renders"| node_page
node_page -->|"includes"| node_header
node_page -->|"frames"| node_glasssurface
node_page -->|"shows"| node_clock
node_header -->|"contains"| node_themetoggle
node_themeprovider -.->|"drives"| node_themetoggle
node_themeprovider -.->|"styles"| node_clock
node_themeprovider -.->|"styles"| node_glasssurface
node_clock -->|"uses"| node_aurora
node_clock -->|"uses"| node_textanimate
node_clock -->|"uses"| node_fonts
node_glasssurface -.->|"uses"| node_utils
node_page -.->|"references"| node_assets

click node_layout "https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/app/layout.tsx"
click node_page "https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/app/page.tsx"
click node_globals "https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/app/globals.css"
click node_themeprovider "https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/Providers/ThemeProvider.tsx"
click node_header "https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/Header/Header.tsx"
click node_themetoggle "https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/ThemeToggleButton.tsx"
click node_clock "https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/Clock.tsx"
click node_glasssurface "https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/GlassSurface.tsx"
click node_aurora "https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/shadcnui/aurora-text.tsx"
click node_textanimate "https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/shadcnui/text-animate.tsx"
click node_fonts "https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/lib/fonts.ts"
click node_utils "https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/lib/utils.ts"
click node_assets "https://github.com/piyushsarkar-dev/digital-clock-app/tree/main/public"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_layout,node_page,node_globals toneBlue
class node_themeprovider,node_header,node_themetoggle,node_clock,node_glasssurface toneAmber
class node_aurora,node_textanimate toneMint
class node_fonts,node_utils,node_assets toneRose
```

## Components

### App Shell

- [App Layout](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/app/layout.tsx): Next.js shell · Global document shell and shared providers. · `src/app/layout.tsx`
- [Clock Page](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/app/page.tsx): route · Single route that assembles the clock experience. · `src/app/page.tsx`
- [Global CSS](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/app/globals.css): style layer · App-wide styling and utility-first layout foundation. · `src/app/globals.css`

### UI Components

- [Theme Provider](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/Providers/ThemeProvider.tsx): theme context · Wraps the app with shared light/dark theme state. · `src/components/Providers/ThemeProvider.tsx`
- [Header](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/Header/Header.tsx): page chrome · Top-level page chrome and controls area. · `src/components/Header/Header.tsx`
- [Theme Toggle](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/ThemeToggleButton.tsx): theme control · User interaction for switching the shared theme. · `src/components/ThemeToggleButton.tsx`
- [Clock](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/Clock.tsx): live display · Core live time/date presentation and update loop. · `src/components/Clock.tsx`
- [Glass Surface](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/GlassSurface.tsx): visual shell · Frosted, refractive panel framing the clock content. · `src/components/GlassSurface.tsx`

### Animated Primitives

- [Aurora Text](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/shadcnui/aurora-text.tsx): text primitive · Reusable animated typography primitive. · `src/components/shadcnui/aurora-text.tsx`
- [Text Animate](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/components/shadcnui/text-animate.tsx): animation primitive · Reusable animated text transition primitive. · `src/components/shadcnui/text-animate.tsx`

### Shared Layer

- [Fonts](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/lib/fonts.ts): font setup · Centralized font configuration. · `src/lib/fonts.ts`
- [Utils](https://github.com/piyushsarkar-dev/digital-clock-app/blob/main/src/lib/utils.ts): helper lib · Shared helper logic used across the UI. · `src/lib/utils.ts`
- [Public Assets](https://github.com/piyushsarkar-dev/digital-clock-app/tree/main/public): static assets · Images and other static files used by the page visuals. · `public`

## Connections

- App Layout → Theme Provider: wraps · Provides global theme state to the app.
- App Layout → Global CSS: loads · Applies global styling foundation.
- App Layout → Clock Page: renders · Bootstraps the single route.
- Clock Page → Header: includes · Adds top-level page chrome.
- Clock Page → Glass Surface: frames · Places the clock inside the glass panel.
- Clock Page → Clock: shows · Main live feature of the page.
- Header → Theme Toggle: contains · Exposes the theme switch control.
- Theme Provider → Theme Toggle: drives · Provides the shared theme state used by the toggle.
- Theme Provider → Clock: styles · Theme state influences clock presentation.
- Theme Provider → Glass Surface: styles · Theme state influences the visual shell.
- Clock → Aurora Text: uses · Supports polished animated typography.
- Clock → Text Animate: uses · Supports animated time rendering.
- Clock → Fonts: uses · Applies shared font configuration.
- Glass Surface → Utils: uses · Leans on shared helper logic for presentation.
- Clock Page → Public Assets: references · Consumes static visuals and decorative assets.