NewsChart - Human Contribution Summary

9 min read

Here’s Claude’s summary of my (human) contributions to the NewsChart project. This is based on summarising the Claude Code session transcripts. Current as at May 2026 — project still in progress.

Project Leadership & Direction

  • End-to-End Delivery: Conceived and led NewsChart from idea to live production site at newschart.rossarnold.uk, managing scope, architecture, and release cadence throughout.
  • Full-Stack Split: Took sole ownership of the Java/Spring Boot backend — designing and implementing all backend code independently, with Claude Code acting as frontend developer for the React/TypeScript side.
  • Release Management: Drove a steady release cadence (15+ versioned releases across the project lifetime), authoring changelog entries, proposing version numbers, and triggering deployments via GitHub Actions.
  • Go-Live Planning: Maintained a detailed MVP-GOLIVE.md checklist covering security hardening, infrastructure, monitoring, accessibility, SEO, and operational readiness; systematically worked through and checked off items.
  • Public Repo Readiness: Led an audit pass before making the repo public, identifying and resolving issues around package naming (email address embedded in package path), hardcoded IP addresses in CI, and repo professionalism.
  • Portfolio Framing: Shaped all user-facing explanatory content (README, Method page, Credits page) with the explicit goal of demonstrating engineering quality to a portfolio audience.

Architecture & Technical Decision-Making

  • Backend Architecture: Designed the pipeline orchestrator pattern (BasePipelineOrchestrator, separate orchestrators per source), scheduler configuration, and PipelineStep abstraction, making active Java design decisions throughout (e.g. choosing records over classes, deciding thread count, reviewing method signatures).
  • Multi-Source AI Integration: Decided to run Gemini directly (preserving it as a redundancy path) while routing Perplexity, OpenAI ChatGPT, and future sources through OpenRouter — explicitly reasoning about native search grounding, integration effort, and provider redundancy.
  • Model Selection: Actively selected and revised AI model strings (e.g. upgrading from gemini-2.5-flash to gemini-2.5-flash after a data quality regression; reasoning about cost vs quality trade-offs between GPT and Perplexity).
  • LLM Response Robustness: Identified recurring failure modes — models inventing enum values, prepending narrative text before JSON, API version mismatches — and directed the engineering approach for each (e.g. introducing LlmCallout DTO to decouple model output from domain enums; stripping text before the first open brace).
  • Prompt Design: Wrote and iterated the AI news prompt, making explicit editorial decisions: wanting true international perspective without forcing geographic spread; preventing models from surfacing training-data-era stories; not imposing “humanitarian impact” bias; keeping the same prompt across all models as a fair comparison test.
  • Data Model Decisions: Decided on a single MongoDB collection for all sources rather than per-source collections, reasoning about query simplicity and future flexibility; changed CalloutStats.count from Long to Integer based on own judgement; reviewed and directed backend pagination implementation.
  • Concurrency Philosophy: Deliberately chose single-threaded sequential pipeline execution (“easier to trace, no particular hurry, running on a free Oracle VM”) rather than parallelism.
  • Dependency & Build Management: Led migration from Create React App to Vite after identifying that react-scripts was 4 years stale; evaluated Dependabot PRs for both Maven and npm, directing which to merge, close, or investigate; managed OWASP dependency-check setup including OSS Index credentials and CI workflow scheduling.
  • Cost & Metrics Design: Actively designed the AI metrics feature (latency, token counts, cost per call) via structured design sessions and grill-me interviews, making key decisions: static price lookup table over dynamic API calls, same MongoDB collection for all sources, try/finally for cost capture, date-bucketed storage for future multi-call scenarios.

Feature Definition & Requirements Specification

  • Core Map Visualisation: Specified the callout layout algorithm requirements and iterated on it extensively — directing scoring weight changes, bounding box corrections, line-crossing penalty tuning, minimum connector distance adjustments, and removal of ineffective heuristics based on visual inspection of screenshots.
  • Coverage Map (Heatmap) Feature: Defined the heatmap view from scratch: normalised colour scale across all sources (so the same colour means the same count regardless of source), a horizontal legend pill with explanatory text, subtle pulse animation for high-count countries, and the “XX stories from <source>” summary text. Explicitly rejected non-standard colour conventions after researching mainstream heatmap palettes.
  • Mobile Story List and Country Drill-Down: Specified the mobile layout redesign — separate banner above map, hamburger menu for controls, fixed footer, mobile-specific story list panel below the map, scrollable country ranking list for coverage mode. Directed pagination behaviour (consistent modal height on non-final pages; size-to-fit on first page).
  • Keyboard Navigation: Specified left/right arrow key navigation for the date timeline, with explicit requirement to disable it when the callout detail overlay is open.
  • Accessibility Implementation: Drove the tab order specification, ARIA attributes, focus management, and elimination of invisible tab stops. Later directed the full accessibility testing strategy (Playwright/axe for end-to-end, per-component axe tests for unit level) and an accessibility statement page.
  • Contact Modal: Decided on a “contact me” modal with both LinkedIn and email links after reasoning that LinkedIn-only would exclude non-members; directed its placement in the footer on both desktop and mobile.
  • Projection and Source UI: Decided to keep Natural Earth and Mercator projections, removing Equal Earth as redundant; set Natural Earth as the default. Set source order as Gemini → Perplexity → ChatGPT → NYT and Gemini as the default. Directed storage of user preferences in localStorage.
  • UI Label Decisions: Changed “Story Counts” to “Coverage Map”, “Day View” to “Daily”, and directed introduction of a single source-of-truth constants file after noticing a label inconsistency between the radio button and the status pill.

Infrastructure & Operations

  • Production Hosting: Stood up the Oracle Cloud VM, configured systemd service, nginx reverse proxy, and Cloudflare DNS/SSL. Walked through firewall rules, closing port 8080 from public access, and later closing port 22 in favour of Tailscale-only SSH.
  • Tailscale Networking: Directed the move to Tailscale for both CI/CD deployment and developer access, explicitly closing public SSH port 22 once Tailscale was confirmed working.
  • Grafana Monitoring: Directed the dashboard design — per-AI-provider sections rather than a single combined AI section, rate-based metrics rather than cumulative counters, distinction between lifetime and time-range-scoped panels. Added error log tracking panels and directed placement within the dashboard layout. Managed Grafana password reset issues and plugin configuration (disabled OnCall, configured email via Postfix).
  • JVM Tuning: Investigated heap sizing and GC options for the low-traffic Oracle VM, asking specific questions about SerialGC stop-the-world frequency and startup time implications; reviewed memory usage against prod Prometheus data.
  • Uptime Monitoring: Chose GitHub Actions as the uptime monitoring mechanism (leveraging existing account) with a 4-hour schedule, selecting a meaningful health endpoint and designing alert deduplication behaviour.
  • Local Dev Configuration: Specified and directed implementation of an application-local.properties that disables AI gateway calls on startup, with a mechanism to selectively re-enable individual sources via system properties.

Quality, Testing & Security

  • Layout Algorithm Test Suite: Designed and specified the layout testing framework from first principles: test cases must have 3 callouts each, tagging system for case metadata (e.g. needs-fix), separate viewport/projection dimensions, batch test execution, screenshot output for failed combinations only, and an API-fetching helper script for populating real-world cases from production.
  • Accessibility Testing Strategy: Directed the two-tier approach (Playwright/axe for page-level, per-component axe tests for unit level), specified which components warranted dedicated test files, and wired accessibility tests into both pre-commit and pre-push hooks. Added sitemap updates and CLAUDE.md notes to ensure future pages are included.
  • CI Pipeline Design: Identified and fixed a gap where ESLint errors were caught in CI but not locally; added ESLint to pre-commit hooks. Added npm audit to frontend CI. Added link checking workflows (post-deploy for internal links, weekly for all links). Questioned whether the layout test suite was running in CI and directed its inclusion.
  • Security Posture: Ran OWASP dependency checks, evaluated CVEs, authored suppression entries for unfixed upstream issues (e.g. Netty alphas), and directed the OWASP CI workflow setup including OSS Index credentials. Questioned and verified Tomcat CRITICAL issues and evaluated options for resolution. Prompted the addition of a Security section to the Credits page listing OWASP, Dependabot, GitHub Actions npm audit, and secret scanning.
  • Backend Code Review: Reviewed own backend changes before committing — asking Claude to flag issues, evaluate null-safety, question unused return values, and propose test coverage. Identified and fixed a StackOverflowError caused by a Mongo aggregation pipeline; extended test suppression of ApplicationReadyEvent to relevant test classes.
  • Data Quality Incident: Independently identified that Gemini data from a specific date range looked like training-data-era stories rather than live search results; directed investigation, identified the root cause as a prompt format change in v0.5.0, manually deleted bad data from production MongoDB, and validated the fix with a model upgrade.

User Experience & Product Direction

  • Mobile UX Overhaul: Identified that the floating controls panel obscured map callouts on mobile; directed the separation of controls into a banner and hamburger menu. Identified and fixed a callout tail rendering bug (partially visible under opaque box) and a map rendering regression on real Android hardware (traced via LAN testing on actual mobile device).
  • Method Page (How It Works): Specified the structure and tone of the Method page — non-technical user guide first, then AI/architecture details, then engineering practices. Made specific content decisions: NYT selected for its geocoding quality, Tailscale used for deployment security, SSH port 22 closed. Verified technical claims (e.g. whether Claude/Grok can be used with native search grounding via OpenRouter).
  • Credits Page: Iterated the Credits page structure multiple times — reordering sections by significance, correcting inaccurate descriptions of AI roles, separating data sources from frontend libraries, adding a Security section, and specifying accurate descriptions of how each AI source is used (e.g. distinguishing Gemini’s NYT summarisation role from its news search role).
  • Branding & SEO: Directed addition of og:image meta tags, provided a specific screenshot for the social preview image, added robots.txt and XML sitemap, and corrected the GitHub repo description for accuracy (“not in real time”).
  • Footer Navigation: Specified a logical ordering for footer links across multiple iterations; directed consistent left-alignment across SPA and static pages; resolved capitalisation inconsistencies using the shared constants file.

Documentation & Knowledge Management

  • CLAUDE.md Maintenance: Actively maintained the project CLAUDE.md, adding notes about deployment procedures, secrets management, how to run accessibility tests, when to update the sitemap, and proactive prompts for future Claude sessions (e.g. propose accessibility test updates when new UI elements are added, propose metrics tracking for new interactions).
  • README: Drove the README from a placeholder to a comprehensive document — proposing and selecting badges (Gemini, Grafana, Claude collaboration, CI status), writing the project pitch, correcting inaccurate feature descriptions, and adding screenshots.
  • Design Documentation: Maintained metrics-feature-decisions.md as a living design document, updating it through multiple rounds of design discussion and grill-me sessions to reflect final decisions on schema, collection strategy, pricing lookup approach, and frontend API shape.
  • Release Discipline: Consistently authored or reviewed changelog entries, insisting on descriptive commit messages for release commits rather than generic “chore: add CHANGELOG” messages.