How nntrn/what-im-reading works
Main Components
a. Data Processing Layer
• Input: annotations.json (external data source)
• JQ Processing Scripts (scripts/annotations.jq, books.jq)
• Data Transformation Pipeline
b. Static Site Generation Layer
• Jekyll Engine
• Layouts (_layouts/)
• Components (_includes/)
• Page Templates (_pages/)
c. Asset Management
• CSS Assets
• JavaScript Components
• Data Files (books.json, genres.json, stats.json)
Flow and Relationships
[External Annotation Data] → [Data Processing Scripts] → [Generated JSON Files]
• ↓
[Jekyll Templates] ←→ [Layouts] → [Static Site Generator] ← [Data Files]
• ↓ ↓
[Include Components] → [Final Static HTML/CSS/JS Output]
Component Details
• Book data generation
• Activity data generation
• Genre data generation
• Statistics generation
• Word data processing
Architectural Patterns to Highlight
• Static Site Generation pattern
• Data Transform Pipeline pattern
• Component-based templating (Jekyll includes)
• GitHub Pages deployment model
Deployment/Hosting
• File types (JSON, HTML, CSS, JS)
• Process flows
• Build steps
• External dependencies
This will give other engineers a clear understanding of:
• How data flows through the system
• Where transformations occur
• How the static site is assembled
• Where customization points exist
Remember to indicate the GitHub Actions automation that can trigger updates via the repository dispatch event, as shown in the README's curl command example.