THE AI ALMANAC

01Context

A living reference for AI concepts designed for both precise lookup and connected reading. The current edition organizes 791 terms in a tactile, book-inspired interface.

02Problem

AI references often separate simple explanations from technical ones and leave readers to bridge related concepts themselves. The Almanac gives each term several reading levels, related entries, and multiple navigation paths in one place.

03Constraints

1. 01Generate direct, crawlable routes and metadata for glossary terms and social previews.
2. 02Preserve the existing React book interface and page-turn behavior while adding static route generation.
3. 03Keep reading history, bookmarks, collections, and sound preferences available without an account or server database.
4. 04Keep the book readable and operable across desktop, tablet, and mobile viewports.

04Architecture

Astro owns the document shell, static routes, metadata, and generated Open Graph assets. It mounts the existing React reader as a client island. Typed term data supplies the glossary and its navigation, search, timelines, and related concepts.

Astro app shell

Provides the shared document layout, metadata, styles, and React island across the home, About, and term routes.

Static route and preview generator

Creates a clean `/term/<slug>/` page and a term-specific `/og/<slug>.svg` social image for each entry.

React book interface

Handles page turns, explanation modes, A–Z navigation, overlays, keyboard shortcuts, and in-app history.

Typed glossary and search

Stores definitions and relationships in TypeScript and supports ranked suggestions, aliases, and natural-language prompts.

Browser reading library

Persists reading history, bookmarks, collections, and sound preferences in localStorage.

05Decisions

06Trade-offs

07Performance

• ↯Astro generates term routes and social preview assets at build time rather than fetching them from a runtime content API.
• ↯Reader history, bookmarks, collections, and sound preferences stay client-side in localStorage.

08Challenges

• #Keeping clean term URLs and browser history aligned with in-app navigation, search, keyboard shortcuts, and legacy hash links.
• #Preserving the book's proportions and legibility as its panels and navigation reflow on narrow screens.

09Learnings

• →A static route layer can improve direct access and social metadata while a client island retains a distinctive interactive reading experience.
• →A structured term model can power search, related entries, multiple explanation modes, and timeline views without duplicating the source content.

10Retrospective

A next pass could render each entry's primary definition directly in Astro while leaving the reader controls in React. That would give crawlers and readers useful term content before the interactive island hydrates.