Analytics (@wrelik/analytics)

The @wrelik/analytics package serves as a specialized adapter for server-side analytics within the Wrelik ecosystem. Its primary purpose is to provide a unified interface for interacting with PostHog, ensuring that application code remains decoupled from specific vendor SDKs. By wrapping the PostHog client, this package enforces consistent event naming conventions and standardized error handling across all Wrelik applications.

As a core service within the wrelik-kit monorepo, it follows the project's "adapter-first" architecture. This design philosophy ensures that if the underlying analytics vendor needs to be changed, modifications are isolated to this package rather than being scattered throughout multiple application repositories.

Sources: README.md:9-14, README.md:43-45, DECISIONS.md:16-19

Architecture and Vendor Integration

The package is built as a wrapper around the posthog-node library. It is designed to minimize the surface area of the analytics API exposed to application developers, focusing only on the functionality required by the ecosystem.

Key Components

The following diagram illustrates the relationship between the application layer, the Wrelik analytics adapter, and the third-party vendor:

This structure ensures that the Application Code never directly interacts with posthog-node.

Sources: packages/analytics/package.json:16-17, DECISIONS.md:21-25, packages/eslint-config/index.js:31-34

Implementation Standards

To maintain architectural integrity, the repository employs strict linting rules and development guidelines.

Import Restrictions

The project uses eslint-plugin-only-warn and custom no-restricted-imports rules to prevent developers from bypassing the adapter. Direct imports of posthog-node will trigger a linting error, directing developers to use @wrelik/analytics instead.

Sources: packages/eslint-config/index.js:31-34

Dependency Structure

The package is managed using pnpm and built using tsup, producing both CommonJS and ESM outputs.

{
  "dependencies": {
    "posthog-node": "^3.6.3",
    "@wrelik/errors": "workspace:*"
  }
}

Sources: packages/analytics/package.json:7-17

Data Flow and Usage

When an application records an analytical event, the flow follows a specific sequence to ensure the data is captured and any issues are handled by the centralized error package.

The diagram shows the synchronous path for event tracking and the fallback mechanism for error reporting.

Sources: README.md:43-45, DECISIONS.md:11-13, DECISIONS.md:21-25

Summary

The @wrelik/analytics package is a critical infrastructure component that standardizes how Wrelik applications handle product analytics. By abstracting PostHog behind a consistent interface and enforcing its use through ESLint, the project achieves vendor-agnosticism and reduces the risk of SDK-specific technical debt. This approach aligns with the core principles of the wrelik-kit repository: providing "intentionally boring" but highly reliable infrastructure.

Sources: README.md:5-7, README.md:73-75