Skip to content

docs: spruce up README with mermaid diagram, emojis, and hyperlinks #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nitrocode merged 1 commit into from
Apr 24, 2026
Merged

docs: spruce up README with mermaid diagram, emojis, and hyperlinks #60

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 107 additions & 42 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,57 +1,66 @@
# AI Death Clock 💀
# 💀 AI Token Deathclock

[![Unit Tests](https://github.com/nitrocode/token-deathclock/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/nitrocode/token-deathclock/actions/workflows/unit-tests.yml)
[![E2E Tests](https://github.com/nitrocode/token-deathclock/actions/workflows/e2e-tests.yml/badge.svg)](https://github.com/nitrocode/token-deathclock/actions/workflows/e2e-tests.yml)
[![Deploy](https://github.com/nitrocode/token-deathclock/actions/workflows/deploy.yml/badge.svg)](https://github.com/nitrocode/token-deathclock/actions/workflows/deploy.yml)
[![codecov](https://codecov.io/gh/nitrocode/token-deathclock/branch/main/graph/badge.svg)](https://codecov.io/gh/nitrocode/token-deathclock)

> **Live site:** `https://nitrocode.github.io/token-deathclock/`
> 🌐 **Live site:** [nitrocode.github.io/token-deathclock](https://nitrocode.github.io/token-deathclock/)

A GitHub Pages visualisation that shows the environmental cost of global AI token consumption — featuring live counters, milestone tracker, and a token-growth chart with projections.
Every AI prompt has a cost. This site makes it visceral. 🔥

Watch the global AI token counter tick in real time, track environmental milestones as they fall, and discover what humanity could have done instead with those same resources.

Created by **RB**.

---

## Features
## ✨ Features

| Feature | Details |
|---------|---------|
| **Live counter** | Estimated global AI tokens consumed since Jan 2020, ticking in real-time |
| **Session counter** | Tokens consumed globally since *you* opened the page |
| **Environmental milestones** | 7 thresholds (trees → bees → water → coral → glaciers → ocean → extinction) with triggered status, progress bars, and consequence descriptions |
| **Growth chart** | Historical data + 18-month projection on a log scale (Chart.js) |
| **Predictions table** | Predicted calendar dates for each milestone |
| **Dark / Light mode** | Toggle button; dark mode is the default |
| ⏱️ **Live counter** | Estimated global AI tokens consumed since Jan 2020, ticking in real-time |
| 📊 **Session counter** | Tokens consumed globally since *you* opened the page |
| 🌿 **Environmental milestones** | 7 thresholds (trees → bees → water → coral → glaciers → ocean → extinction) with progress bars and consequence descriptions |
| 📈 **Growth chart** | Historical data + 18-month projection on a log scale (Chart.js) |
| 🗓️ **Predictions table** | Predicted calendar dates for each upcoming milestone |
| 🏆 **Doom achievements** | Unlock badges as global consumption hits new levels |
| 🎮 **Accelerate the Doom** | A satirical mini-game — click to burn tokens faster |
| 🧮 **Personal footprint calculator** | Estimate your own AI token footprint |
| 🌙 **Dark / Light mode** | Toggle button; dark mode is the default |

---

## Running Locally
## 🚀 Running Locally

```bash
# Clone and open
# Clone the repo
git clone https://github.com/nitrocode/token-deathclock.git
cd token-deathclock

# Serve with any static server, e.g.:
npx serve .
# Then open http://localhost:3000
```

No build step required — it's a fully static site. 🎉

---

## Running Tests
## 🧪 Running Tests

```bash
npm install
npm test # runs Jest with coverage
npm run test:ci # CI mode (fails on coverage drop)
npm test # runs Jest with coverage (interactive)
npm run test:ci # CI mode — fails if coverage drops
npm run test:e2e # Playwright end-to-end tests
```

Tests are in `tests/death-clock.test.js` and cover all pure functions in `death-clock-core.js`.
Unit tests live in [`tests/death-clock.test.js`](tests/death-clock.test.js) and cover all pure functions in [`death-clock-core.js`](death-clock-core.js).

---

## Coverage
## 📊 Coverage

Unit-test coverage is tracked by [Codecov](https://codecov.io/gh/nitrocode/token-deathclock). Every pull request receives an automated comment showing per-file coverage deltas; the PR check fails if coverage decreases.

Expand All @@ -63,42 +72,98 @@ E2E tests run in CI via Playwright (Chromium). Their pass/fail status is shown b

---

## Deployment (GitHub Pages)
## 🚢 Deployment

The site is automatically deployed on every push to `main` via the `deploy.yml` workflow.
It is live at `https://nitrocode.github.io/token-deathclock/`.
The site deploys automatically on every push to `main` via the [`deploy.yml`](.github/workflows/deploy.yml) workflow, pushing to the `gh-pages` branch.

---
🔗 Live URL: [https://nitrocode.github.io/token-deathclock/](https://nitrocode.github.io/token-deathclock/)

## Architecture
Pull requests each get an isolated preview URL:
`https://nitrocode.github.io/token-deathclock/previews/pr-{number}/`

---

## 🏗️ Architecture

### How it fits together

```mermaid
flowchart TD
subgraph Source["📁 Source Files (edit these)"]
core["death-clock-core.js\n☁️ Pure functions\n(no DOM, fully testable)"]
srcjs["src/js/\n00-state … 21-boot\n(feature modules)"]
styleSrc["styles/\nvariables, base,\nfeatures, etc."]
html["index.html\n🏠 Static HTML shell"]
yaml["milestones.yaml\nproject-stats.yaml\nCHANGELOG.md"]
end

subgraph Generated["⚙️ Auto-Generated (do not edit)"]
scriptjs["script.js\n(built from src/js/)"]
stylescss["styles.css\n(built from styles/)"]
datajs["*-data.js\n(built from YAML / MD)"]
end

subgraph Tests["🧪 Tests"]
unit["tests/death-clock.test.js\nJest unit tests"]
e2e["tests/e2e/\nPlaywright E2E tests"]
end

subgraph CI["🤖 GitHub Actions"]
deploy["deploy.yml\nGH Pages deploy"]
unitCI["unit-tests.yml\nJest + Codecov"]
e2eCI["e2e-tests.yml\nPlaywright"]
preview["preview.yml\nPR preview deploy"]
release["release-please.yml\nSemVer + changelog"]
end

subgraph Live["🌐 GitHub Pages"]
site["nitrocode.github.io\n/token-deathclock/"]
end

core -->|imported by| srcjs
srcjs -->|npm run build:js| scriptjs
styleSrc -->|npm run build:css| stylescss
yaml -->|npm run build:*| datajs

html --> Live
scriptjs --> Live
stylescss --> Live
datajs --> Live

core --> unit
html --> e2e
scriptjs --> e2e

unit --> unitCI
e2e --> e2eCI
Live -->|push to main| deploy
deploy --> site
```
.
├── index.html ← Main GitHub Pages entry point
├── styles.css ← Dark/light theme, animations, layout
├── death-clock-core.js ← Pure functions (no DOM deps; testable)
├── script.js ← DOM manipulation, Chart.js, RAF loop
├── package.json ← Jest config & dev deps
├── tests/
│ └── death-clock.test.js
└── .github/
└── workflows/
├── deploy.yml ← GitHub Pages deployment
├── unit-tests.yml ← Jest unit tests + Codecov upload
└── e2e-tests.yml ← Playwright E2E tests
```

### Key source files

| File | Role |
|------|------|
| [`death-clock-core.js`](death-clock-core.js) | 🧠 Pure calculation functions — no DOM, fully unit-testable |
| [`src/js/`](src/js/) | 🖥️ Feature modules compiled into `script.js` |
| [`styles/`](styles/) | 🎨 CSS source files compiled into `styles.css` |
| [`index.html`](index.html) | 🏠 Static HTML shell loaded by GitHub Pages |
| [`milestones.yaml`](milestones.yaml) | 🏁 Source of truth for environmental milestone data |
| [`project-stats.yaml`](project-stats.yaml) | 📦 Tracks PR count + tokens consumed building this project |

> ⚠️ Never edit `script.js`, `styles.css`, or `*-data.js` directly — they are auto-generated. Edit the source files and run the relevant `npm run build:*` command.

---

## Environmental Data Sources
## 🌍 Environmental Data Sources

| Metric | Source |
|--------|--------|
| Energy per token (~0.0003 kWh / 1K tokens) | Google/DeepMind inference benchmarks, MLPerf |
| CO₂ per kWh (0.4 kg) | IEA global average grid intensity 2024 |
| Water per token (~0.5 L / 1K tokens) | Microsoft sustainability report 2023 |
| CO₂ per tree (~21 kg/year) | US Forest Service estimates |
| Historical token growth | OpenAI usage blog, Epoch AI, AI Index 2024 |
| CO₂ per kWh (0.4 kg) | [IEA global average grid intensity 2024](https://www.iea.org/data-and-statistics/charts/global-average-co2-intensity-of-electricity-generation-2000-2023) |
| Water per token (~0.5 L / 1K tokens) | [Microsoft sustainability report 2023](https://www.microsoft.com/en-us/corporate-responsibility/sustainability/report) |
| CO₂ per tree (~21 kg/year) | [US Forest Service estimates](https://www.fs.usda.gov/ccrc/topics/urban-forests/canopy-cover-and-carbon-sequestration) |
| Historical token growth | OpenAI usage blog, [Epoch AI](https://epochai.org/), [AI Index 2024](https://aiindex.stanford.edu/report/) |

> All figures are illustrative estimates intended to communicate scale, not precise measurements.
> 📌 All figures are illustrative estimates intended to communicate scale, not precise measurements.

Loading