thefoldwithin-earth/docs/CODE_REVIEW.md

Code Review: The Fold Within

Architecture Assessment

Current State

• Minimal static site with custom Node.js index generator
• Markdown files served directly by Cloudflare Pages
• Index generation runs at build time
• No separate HTML templates for fieldnotes

Issues Identified

1. Rendering Pipeline

Current: Markdown → Cloudflare Pages (built-in) → HTML
Problem: Can't control metadata display, timestamps

2. Timestamp Display

Problem: Sidebar shows ctime, not originalDate
Fix: Generator must output originalDate, template must use it

3. No Frontend Templates

Current: index.json has data, but templates don't use it
Fix: Create HTML templates with full metadata injection

4. Missing Build Configuration

Missing: _routes.json, _headers, _redirects
Impact: Can't optimize caching, redirects, headers

---

Best Practices Recommendations

Phase 1: Quick Wins (This Session)

• Enhanced index generator with full metadata
• Replace generate-index.mjs with enhanced version
• Update Cloudflare Pages build command

Phase 2: Infrastructure (This Week)

• Add _headers for caching, security headers
• Add _routes.json for URL handling
• Create HTML template for fieldnotes
• Build step: markdown → HTML with metadata

Phase 3: Full SSG (Future)

• Migrate to proper SSG (Astro, Hugo, or custom)
• Templates separated from content
• Component-based frontend
• Full SEO optimization

---

Code Quality Metrics

Strengths

✅ Clean index generation logic ✅ Separation of concerns (extractors, parsers, generators) ✅ Proper error handling ✅ Cron-based automation ✅ Multi-platform mirroring

Areas for Improvement

❌ No linting (ESLint, Prettier) ❌ No testing (Jest, PyTest) ❌ No type checking (TypeScript, Pyre) ❌ No code coverage tracking ❌ No documentation generation

---

Action Items

Immediate

1. Replace generate-index.mjs with enhanced version
2. Test enhanced generator locally
3. Push to trigger Pages rebuild

Short-term

1. Add _headers for security + caching
2. Create fieldnote HTML template
3. Document build process

Long-term

1. Add linting + formatting
2. Add tests
3. Migrate to proper SSG