Analytics Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/hooks/useFathom.ts
• src/hooks/usePostHog.ts
• src/pages/_app.tsx
• package.json
• meilisearch-docs-scraper.config.json
• src/pages/api/llms-docs.md.ts

The railways-docs project integrates multiple analytics and data collection services to monitor user engagement and provide functionality like search. The primary user-facing analytics are handled by Fathom and PostHog, which are initialized at the application's root component.

Data is also collected and processed for internal purposes, such as populating the Meilisearch index to power the documentation search and generating a consolidated text file of all documentation for Large Language Model (LLM) consumption. This integration is configured through environment variables and custom React hooks.

Core Integration Architecture

The analytics services are initialized globally within the main application component, MyApp. This ensures that tracking is active on all pages. The initialization is managed by custom hooks, useFathom and usePostHog, which read configuration from environment variables.

This diagram illustrates the initialization flow when the application starts.

Configuration

The analytics integration relies on environment variables to provide the necessary API keys and configuration details.

Variable	Service	Description
NEXT_PUBLIC_FATHOM_CODE	Fathom	The tracking code for the Fathom Analytics site.
NEXT_PUBLIC_POSTHOG_API_KEY	PostHog	The public API key for the PostHog project.
NEXT_PUBLIC_POSTHOG_HOST	PostHog	The host URL for the PostHog instance (e.g., https://app.posthog.com).

Sources: src/pages/_app.tsx:11-18

Dependencies

The project utilizes specific npm packages to facilitate the integration with third-party analytics services.

Package	Version	Description
fathom-client	^3.1.0	Official client for Fathom Analytics.
posthog-js	^1.242.0	Official JavaScript SDK for PostHog.
meilisearch	^0.32.3	Client for Meilisearch, used for the search index.

Sources: package.json:20, package.json:30, package.json:24

Fathom Analytics

Fathom is used for privacy-focused website analytics. The integration is encapsulated in the useFathom custom hook.

useFathom Hook

This hook is responsible for loading the Fathom tracking script and registering a listener for route changes to track pageviews automatically.

• Initialization: On component mount, it calls Fathom.load() with the tracking code and the site URL (docs.railway.com). The includedDomains option ensures that tracking is only active on the specified domain.
• Pageview Tracking: It subscribes to the Next.js router's routeChangeComplete event. When a route change is detected, it calls Fathom.trackPageview() to record the new page view.
• Cleanup: The hook returns a cleanup function that unsubscribes from the routeChangeComplete event when the component unmounts to prevent memory leaks.

Sources: src/hooks/useFathom.ts:5-22, src/pages/_app.tsx:11-12

The following sequence diagram shows the process of tracking a page view with Fathom when a user navigates to a new page.

PostHog Analytics

PostHog is used for product analytics. Its integration is managed by the usePostHog hook, which is simpler than the Fathom one as it only handles initialization.

usePostHog Hook

This hook's sole responsibility is to initialize the PostHog client when the application loads.

• Initialization: It calls posthog.init() with the API key and host URL retrieved from environment variables. This loads the PostHog script and prepares it for tracking events. Automatic page view tracking is likely handled by the PostHog library itself upon initialization, though this is not explicitly stated in the source code.

Sources: src/hooks/usePostHog.ts, src/pages/_app.tsx:15-18

Ancillary Data Collection

Besides user analytics, the project employs other data collection and processing mechanisms for internal features.

Meilisearch Indexing

The documentation search is powered by Meilisearch. A scraper is configured to periodically read the documentation content and update the search index. This is a form of data collection for the purpose of providing search analytics and results.

The configuration file meilisearch-docs-scraper.config.json defines the selectors used to extract content from the HTML.

Selector Key	CSS Selector	Description
lvl0	.sidebar .current-section	The main section title from the sidebar.
lvl1	.docs-content h1	The main page title.
lvl2	.docs-content h2	Section headings.
lvl3	.docs-content h3	Subsection headings.
lvl4	.docs-content h4	Sub-subsection headings.
text	.docs-content p, .docs-content li, ...	The main text content to be indexed.

Sources: meilisearch-docs-scraper.config.json:8-20

LLM Data Consumption API

An API endpoint at /api/llms-docs.md is designed to provide the entire documentation content as a single, formatted text file for consumption by Large Language Models (LLMs). This endpoint reads all markdown files, extracts their frontmatter and content, cleans them by removing code blocks and other markup, and concatenates them into one response.

This process can be seen as a form of data aggregation for analytical or training purposes by an external or internal AI system.

The flow for this API endpoint is as follows: