Onboarding: hackerkid/Mind-Expanding-Books

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/hackerkid/Mind-Expanding-Books shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

AVOID — Stale and unlicensed — last commit 1y ago

• 73+ active contributors
• Distributed ownership (top contributor 9% of recent commits)
• ⚠ Stale — last commit 1y ago
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live hackerkid/Mind-Expanding-Books repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hackerkid/Mind-Expanding-Books.

What it runs against: a local clone of hackerkid/Mind-Expanding-Books — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in hackerkid/Mind-Expanding-Books | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 573 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>hackerkid/Mind-Expanding-Books</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of hackerkid/Mind-Expanding-Books. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/hackerkid/Mind-Expanding-Books.git
#   cd Mind-Expanding-Books
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of hackerkid/Mind-Expanding-Books and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "hackerkid/Mind-Expanding-Books(\\.git)?\\b" \\
  && ok "origin remote is hackerkid/Mind-Expanding-Books" \\
  || miss "origin remote is not hackerkid/Mind-Expanding-Books (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "app/gatsby-config.js" \\
  && ok "app/gatsby-config.js" \\
  || miss "missing critical file: app/gatsby-config.js"
test -f "app/src/data/books.json" \\
  && ok "app/src/data/books.json" \\
  || miss "missing critical file: app/src/data/books.json"
test -f "app/src/data/categories.json" \\
  && ok "app/src/data/categories.json" \\
  || miss "missing critical file: app/src/data/categories.json"
test -f "app/src/context/globalState.js" \\
  && ok "app/src/context/globalState.js" \\
  || miss "missing critical file: app/src/context/globalState.js"
test -f "app/src/pages/index.js" \\
  && ok "app/src/pages/index.js" \\
  || miss "missing critical file: app/src/pages/index.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 573 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~543d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/hackerkid/Mind-Expanding-Books"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

A Gatsby-powered static site and curated reading recommendation engine that surfaces hand-picked books across 30+ categories (Startups, Philosophy, Fiction, Science, etc.). Users browse categorized books with Goodreads ratings, Amazon links, and a personal reading list feature, built on a JSON data source (books.json, categories.json) served through server-side rendering. Monolithic Gatsby site structure: app/ contains the entire frontend (src/components, src/pages, src/templates, src/context). Book data lives in app/src/data/ as static JSON files (books.json, categories.json). State management uses React Context (globalState.js, bookReducer.js). Category pages are generated via gatsby-node.js from templates/categoryTemplate.js. Utils/ directory exists but is sparse in the file list provided.

Who it's for

Book enthusiasts and casual readers seeking curated book recommendations without algorithm overwhelm; contributors who maintain the book curation lists and improve the discovery UI. Also suits developers building Gatsby + React applications with static data sources and category filtering patterns.

Maturity & risk

Actively maintained with solid fundamentals (Gatsby 2.24, React 16, Bootstrap 4.5, proper ESLint/Prettier setup, pre-commit hooks). No explicit test framework visible (test script is a placeholder TODO). Appears production-ready for a content site but lacks automated test coverage; maturity is high for a curated reference tool but low for a complex application.

Main risks: no test suite (test script just echoes TODO), relatively lightweight dependency footprint (~15 core deps) reduces supply-chain risk, but Gatsby major version (v2) is aging relative to v5 ecosystem. Single data source (books.json) means no API independence; contributor base appears small, so curation continuity depends on community engagement. No visible CI/CD pipeline mentioned in file list.

Active areas of work

Unable to determine from provided file list—no recent commit hashes, PR data, or issue backlog visible. The repo likely accepts community book submissions (CONTRIBUTING.md exists) and UI refinements, but active development status is unclear from the snapshot.

Get running

npm install && npm start Changes:

• Clone the repo: git clone https://github.com/hackerkid/Mind-Expanding-Books.git
• Navigate to app folder: cd app
• Install dependencies: npm install (or yarn)
• Start dev server: npm run develop
• Open http://localhost:8000

Daily commands: cd app && npm run develop Runs Gatsby dev server on http://localhost:8000 with hot reload. Build for production: npm run build. Serve production build: npm run serve.

Map of the codebase

• app/gatsby-config.js — Gatsby configuration defining site metadata, plugins, and data source setup; required for understanding how the site builds and transforms data.
• app/src/data/books.json — Core data file containing all curated books; every contributor must understand the schema and structure to add or modify book entries.
• app/src/data/categories.json — Defines all book categories and their descriptions; essential for understanding how books are organized and displayed.
• app/src/context/globalState.js — React Context API setup managing application-wide state (filtering, sorting); critical for understanding data flow across components.
• app/src/pages/index.js — Main homepage entry point rendering the feed of books; primary user-facing interface that ties together all major components.
• utils/update_json_files.py — Python utility that updates books.json and category metadata from external sources; required for understanding the data pipeline.

Components & responsibilities

• gatsby-config.js (Gatsby plugin API) — Declares plugins (sharp, json transformer, analytics), site metadata, and source filesystem paths
  • Failure mode: Missing plugin causes build error or missing data transformation (e.g., no images if sharp not configured)
• bookReducer + globalState (React Context, useReducer hook) — Manages application state: active category, search term, sort order; dispatches actions on user interaction
  • Failure mode: Stale state renders outdated book lists; missing dispatch causes UI controls to have no effect
• feed.js (React, array .filter() and .sort()) — Maps filtered/sorted books to bookcard components; applies active filter logic from context
  • Failure mode: Logic errors in filter/sort cause incorrect book visibility or ordering
• books.json (JSON, GraphQL schema inference) — Single source of truth for book metadata; schema must match gatsby query expectations and bookcard prop interface
  • Failure mode: Schema mismatch causes undefined props in components; missing fields breaks rendering
• undefined — undefined

How to make changes

Add a New Book

1. Add book object to app/src/data/books.json with required fields: title, author, category, year, goodreadsId, description (app/src/data/books.json)
2. Run utils/update_json_files.py to fetch and populate additional metadata from Goodreads API (utils/update_json_files.py)
3. Verify book appears in feed at app/src/pages/index.js by checking the correct category renders (app/src/pages/index.js)

Add a New Book Category

1. Add category object to app/src/data/categories.json with name and description (app/src/data/categories.json)
2. Update app/src/components/sidebar.js to include new category in navigation links (app/src/components/sidebar.js)
3. Gatsby will auto-generate category page via app/src/templates/categoryTemplate.js; verify routing works (app/gatsby-node.js)
4. Add books with category name matching new entry in app/src/data/books.json (app/src/data/books.json)

Modify Book Sorting or Filtering Logic

1. Define new filter/sort action types in app/src/context/bookReducer.js reducer function (app/src/context/bookReducer.js)
2. Add UI control (dropdown or button) in app/src/components/sortByDropdown.js or app/src/components/feed.js (app/src/components/sortByDropdown.js)
3. Dispatch new action from globalState context in app/src/context/globalState.js provider (app/src/context/globalState.js)
4. Update app/src/components/feed.js to apply new filter/sort logic when rendering books (app/src/components/feed.js)

Why these technologies

• Gatsby — Static site generation enables fast, SEO-friendly book discovery site with no backend infrastructure; integrates GraphQL for data querying
• React Context API — Lightweight client-side state management for filter/sort without Redux overhead; sufficient for single-page feature set
• Bootstrap + React-Bootstrap — Accelerates UI component development with pre-built responsive grid and button components; minimal custom CSS needed
• Python data pipeline — Separates data maintenance from frontend; enables scheduled updates from Goodreads API without touching frontend code

Trade-offs already made

• Static site generation (Gatsby) vs server-rendered site

  • Why: No real-time book updates needed; curated list is manually maintained; lower operational cost and faster page loads
  • Consequence: Books require rebuild and redeploy to reflect changes; no dynamic pricing or availability sync

• Client-side filtering/sorting vs server-side

  • Why: Dataset is small (hundreds of books); reduces backend complexity; users can instantly filter without round-trip
  • Consequence: All books must load into browser memory; not scalable beyond ~5,000 items

• Python utility scripts vs JavaScript data pipeline

  • Why: Goodreads API integration is one-time maintenance task; Python ecosystem has mature web scraping/API libraries
  • Consequence: Developers must maintain Python environment separate from Node stack; potential version management friction

Non-goals (don't propose these)

• Real-time book availability or pricing sync
• User authentication or personalization beyond local bookmarks
• E-commerce checkout or purchase integration
• Community reviews or user-generated content
• Full-text search across book content
• Mobile app (web-only, responsive design)

Traps & gotchas

No visible env vars: This is a static site with no .env file—all config is hard-coded (Gatsby config in gatsby-config.js). Gatsby build quirks: gatsby-node.js must run successfully to generate category pages; deleting categories.json breaks build. Data format strictness: books.json must match exact schema that feed.js expects (title, author, rating, year, category fields); adding optional fields requires component updates. No local API: All data is bundled at build time; you cannot add a backend API call without restructuring. Husky pre-commit hooks: Commits will lint/format staged files automatically; if you bypass with --no-verify, CI may still reject. Reading List persistence: Stored only in React Context (volatile); page refresh loses bookmarks unless you add localStorage (see app/src/context/globalState.js—currently missing localStorage integration).

Architecture

Concepts to learn

• Static Site Generation (SSG) with Gatsby — This project uses Gatsby to pre-render all pages at build time (including dynamic category pages), not at request time; understanding SSG vs server-side rendering is critical for modifying data flow and page generation logic.
• React Context API — globalState.js and bookReducer.js use Context API instead of Redux to manage reading list state across components; this is the core pattern for features like bookmarking and filtering.
• Reducer Pattern (useReducer hook) — bookReducer.js implements a Redux-like pattern to handle bookmark actions (ADD_BOOKMARK, REMOVE_BOOKMARK); understanding this is essential for modifying state logic.
• Gatsby Node API (gatsby-node.js) — gatsby-node.js programmatically generates category pages at build time from categories.json using createPage hook; modifying this file is how you add dynamic routing or data-driven pages.
• GraphQL in Gatsby — Gatsby's source plugins (gatsby-source-filesystem, gatsby-transformer-json) expose books.json and categories.json via GraphQL queries; templates like categoryTemplate.js use GraphQL to fetch filtered data at build time.
• Slugification — The slugify package is used to convert category names (e.g. 'Startups and Business') into URL-safe slugs (startups-and-business); essential for dynamic category page routing.
• Pre-commit Git Hooks (Husky + lint-staged) — Husky intercepts commits to run ESLint and Prettier via lint-staged, enforcing code style before code reaches the repo; bypassing with --no-verify can cause CI failures.

Related repos

• getify/You-Dont-Know-JS — Similar curated learning resource model (book collection with links); shows how to organize educational content in a GitHub-native format
• EbookFoundation/free-ebooks — Parallel curation project for free ebooks; demonstrates community-driven book indexing and categorization at scale
• janishar/nodejs-backend-architecture-typescript — Example of a Gatsby + Node backend architecture for a content site, relevant if Mind-Expanding-Books adds dynamic features (user reviews, ratings, backend search)
• netlify/gatsby-plugin-algolia — Popular search plugin for Gatsby sites; relevant if this project wants full-text book search beyond sidebar filtering

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Python CI/CD workflow for utils data pipeline validation

The utils/ folder contains Python scripts (gooodreads.py, update_json_files.py, housekeep.py) that generate/maintain app/src/data/books.json and app/src/data/categories.json, but there's no automated validation. A GitHub Action should test that these scripts run without errors and validate the output JSON schema before they're merged, preventing corrupted book data from reaching production.

• [ ] Create .github/workflows/python-utils-test.yml that installs utils/requirements.txt dependencies
• [ ] Add unit tests in utils/ directory (e.g., utils/test_update_json_files.py) that validate books.json and categories.json output structure
• [ ] Configure workflow to run on PRs modifying files in utils/ or app/src/data/
• [ ] Add validation for required fields in books.json (title, author, category, rating, etc.) as seen in app/src/components/bookcard.js

Add Jest tests for React components and context state management

The test script in package.json is a placeholder (echo "Write tests!"). With stateful components like app/src/context/bookReducer.js managing reading lists and app/src/components/bookcard.js displaying books, testing would catch regressions. This is especially important given the sorting/filtering logic in app/src/components/sortByDropdown.js.

• [ ] Create app/src/tests/ directory structure mirroring app/src/components/
• [ ] Add test file app/src/tests/bookReducer.test.js covering state transitions in app/src/context/bookReducer.js
• [ ] Add test file app/src/tests/bookcard.test.js for rendering logic, Amazon/Goodreads link generation in app/src/components/bookcard.js
• [ ] Update app/package.json scripts to run jest and add jest config with enzyme for React component testing
• [ ] Configure pre-commit hook in app/.husky/ to run tests (already have husky installed)

Document data contribution workflow and schema validation in CONTRIBUTING.md

CONTRIBUTING.md exists but likely lacks specifics on the data pipeline. New contributors adding books should understand how book data flows from utils/gooodreads.py → app/src/data/books.json → rendered components. There's also a utils/HOUSEKEEPING.md (maintenance docs) that should be cross-referenced. This prevents malformed submissions.

• [ ] Expand CONTRIBUTING.md with a 'Adding Books' section explaining the utils/ Python pipeline (how to run update_json_files.py, what config-sample.py requires)
• [ ] Document the required JSON schema for books.json entries (fields visible in app/src/data/books.json and used by bookcard.js: title, author, category, rating, imageUrl, etc.)
• [ ] Add reference to utils/HOUSEKEEPING.md as the maintenance guide for book metadata cleanup
• [ ] Include example: 'Run python utils/update_json_files.py and verify app/src/data/books.json output before submitting PR'
• [ ] Link utils/book_name_to_details.json purpose (temporary mapping file) for contributor clarity

Good first issues

• Add localStorage persistence to reading list: Currently app/src/context/globalState.js loses bookmarks on page refresh. Implement localStorage.getItem/setItem in useEffect hook to persist and restore bookmarked books across sessions.: Small: app/src/context/globalState.js
• Write unit tests for bookReducer: app/src/context/bookReducer.js handles bookmark add/remove logic but no tests exist (package.json test script is a TODO). Add Jest tests covering ADD_BOOKMARK, REMOVE_BOOKMARK, and edge cases.: Medium: app/src/context/bookReducer.js + new test file
• Extract book card schema validation: books.json is manually curated with no schema enforcement. Create a Joi/Yup schema file and validate at gatsby-node.js build time to catch missing/malformed fields early.: Small: app/gatsby-node.js, app/src/data/books.json

Top contributors

• @hackerkid — 9 commits
• @shubhamghimire — 5 commits
• @Saurontm — 3 commits
• @seemaj201274 — 3 commits
• @dnltsk — 2 commits

Recent commits

• 2844c5a — added something in the readme for the better understanding (Yubraj)
• 40024c5 — Update README.md (richk21)
• 4a44d35 — Delete .github/workflows/updatejson.yml (hackerkid)
• dd9807a — Remove credits and license from books category (coool9)
• 1182284 — Spelling and grammar in CONTRIBUTING.md (La5u)
• dafefcf — added 'Limitless', 'Brain Food' and 'Super Human' in README (yashviradia)
• 07f1f66 — fixes goodread button link not opening in new tab (love-sonkar)
• 56ef6ee — corrected 'Ryan Holding' to 'Ryan Holiday' (darshithpatel)
• 650d9ba — Adding book into the Autobiography and biographies section (XanderRubio)
• af2c330 — Update CONTRIBUTING.md (hackerkid)

Security observations

• High · Outdated Gatsby and React Dependencies — app/package.json. The project uses Gatsby 2.24.91 and React 16.10.2, which are significantly outdated and contain known security vulnerabilities. Gatsby 2.x reached end-of-life and no longer receives security updates. React 16.10.2 is also vulnerable to known XSS and other security issues. Fix: Upgrade to Gatsby 5.x+ and React 18.x+ with latest security patches. Run 'npm audit' and address all reported vulnerabilities immediately.
• High · Vulnerable ESLint Configuration Dependencies — app/package.json (devDependencies). ESLint 7.7.0, eslint-config-airbnb 18.2.0, and related linting dependencies are outdated and may contain security vulnerabilities. These should be updated to current versions. Fix: Update ESLint and related plugins to latest versions (ESLint 8.x+). Run 'npm audit --fix' to resolve known vulnerabilities.
• Medium · Hardcoded Configuration Template Exposed — utils/config-sample.py. The file 'utils/config-sample.py' suggests configuration credentials may exist in the repository. If actual config files with credentials are committed, they would pose a security risk. Fix: Ensure no actual configuration files with credentials are committed to the repository. Use environment variables for all sensitive configuration. Verify .gitignore properly excludes config files with credentials.
• Medium · No Content Security Policy Headers Configured — app/gatsby-config.js, app/gatsby-ssr.js. The Gatsby application lacks explicit Content Security Policy (CSP) headers which could allow XSS attacks. No security headers are visible in gatsby-config.js or other configuration files. Fix: Configure CSP headers in gatsby-config.js using plugins like 'gatsby-plugin-csp' or implement headers in deployment configuration. Define strict CSP policies to prevent inline script execution.
• Medium · Google Analytics Plugin with Unvalidated Configuration — app/package.json (gatsby-plugin-google-analytics). The gatsby-plugin-google-analytics v2.3.14 is outdated and may have security issues. Google Analytics tracking ID could be exposed in client-side code without proper validation. Fix: Upgrade to '@react-ga/core' or use gtag.js. Ensure tracking ID is properly configured and validated. Never expose sensitive identifiers in client-side code.
• Medium · Bootstrap 4.5.2 Outdated — app/package.json (dependencies: bootstrap). Bootstrap 4.5.2 is outdated and may contain known XSS vulnerabilities in CSS or component implementations. Fix: Upgrade to Bootstrap 5.x+ which includes security patches. Review changelog for any breaking changes and test thoroughly.
• Low · Missing HTTPS Enforcement Configuration — app/gatsby-config.js. No visible enforcement of HTTPS in Gatsby configuration or security headers, which could allow man-in-the-middle attacks in certain scenarios. Fix: Configure HTTPS enforcement through deployment platform (Netlify, Vercel, etc.). Add security headers including 'Strict-Transport-Security' (HSTS).
• Low · Prettier Version Pinned to Old Version — app/package.json (devDependencies). Prettier 1.19.1 is significantly outdated. While Prettier is a dev-only dependency with lower impact, it should be kept current. Fix: Update Prettier to version 3.x+. This is lower priority but should be addressed with other dependency updates.
• Low · Husky Pre-commit Hook Configuration — app/package.json (devDependencies and husky config). While Husky 4.3.0 provides useful security through git hooks, it's outdated. Current version is 8.x+. Fix: Update Husky to latest version. Ensure lint-staged properly validates all staged files before commit.
• Low · No Security — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.