Introduction & Core Principles
Relevant source files
The following files were used as context for generating this wiki page:
The wrelik-kit is a centralized monorepo containing vendor-agnostic adapters, shared utilities, and configuration packages designed for the Wrelik application ecosystem. It serves as the definitive integration boundary between application logic and third-party services, ensuring that the infrastructure remains "intentionally boring" and highly maintainable.
The primary purpose of this repository is to standardize integrations and enforce development discipline across all Wrelik applications. By providing a unified set of @wrelik/* packages, the system reduces code duplication and prevents direct vendor SDK leakage into application repositories.
Sources: README.md:1-10, README.md:46-51
Architectural Philosophy
The architecture is built upon an "adapter-first" mentality. This approach mandates that applications never interact directly with external service providers (e.g., Clerk, Neon, PostHog). Instead, applications consume these services through internal wrappers that define a stable API surface.
Core Principles
- Adapter-First Architecture: All third-party services must be accessed through an internal package.
- Vendor Agnosticism: Standardizing interfaces makes it easy to replace vendors (e.g., switching S3 providers) without rewriting application code.
- Explicit Boundaries: Minimal surface area is exposed to application developers to reduce complexity.
- Strict Integrity: The repo contains no placeholders, stubs, or mock logic; it is treated as production infrastructure.
Sources: README.md:14-22, DECISIONS.md:17-21
Data Flow & Integration Layer
The following diagram illustrates how the wrelik-kit acts as an intermediary layer between application code and external infrastructure.
The diagram shows that applications must import vendor functionality exclusively through the adapter packages provided in the kit.
Sources: README.md:53-57, DECISIONS.md:3-12
Package Ecosystem
The repository is organized into three distinct categories: Core, Services, and Tooling.
Core Packages
These packages form the foundation of the application stack, handling critical concerns like identity and data persistence.
| Package | Purpose | Primary Vendor/Tech |
|---|---|---|
@wrelik/auth | Authentication, RBAC, and session handling. | Clerk |
@wrelik/db | Prisma client singleton and multi-tenant helpers. | Neon (Postgres) |
@wrelik/storage | File uploads and signed URL management. | Cloudflare R2 |
@wrelik/errors | Typed application errors and Sentry integration. | Sentry |
@wrelik/config | Typed environment variables via Zod. | dotenv/Zod |
Sources: README.md:26-37, DECISIONS.md:3-12
Service Adapters
Secondary services are wrapped to enforce naming conventions and consistent event-driven patterns.
@wrelik/analytics: Wraps PostHog to enforce event naming standards.@wrelik/email: Manages Resend integrations and React-based templates.@wrelik/jobs: Wraps Inngest for serverless background processing.
Sources: README.md:41-45, DECISIONS.md:9-12
Governance & Enforcement
The project uses automated tooling to ensure the core principles are not bypassed during development.
Linting & Import Restrictions
The @wrelik/eslint-config package includes strict no-restricted-imports rules. This prevents developers from accidentally importing raw vendor SDKs (like @clerk/nextjs or @prisma/client) directly into their projects, forcing them to use the approved @wrelik/* alternatives.
// Example of restricted imports in ESLint configuration
'no-restricted-imports': [
'error',
{
paths: [
{ name: '@clerk/nextjs', message: 'Please use @wrelik/auth instead.' },
{ name: '@prisma/client', message: 'Please use @wrelik/db instead.' }
]
}
]
Sources: packages/eslint-config/index.js:15-35
Versioning Strategy
The repository utilizes Changesets for managing releases. Every change that impacts a package must be accompanied by a changeset file, which dictates the semver bump (patch, minor, or major).
Sources: CONTRIBUTING.md:21-39, package.json:10-12
Usage Standards
To maintain the integrity of the monorepo, specific rules define what code is eligible for inclusion:
- Shared Logic: Code must be used by at least two applications to be considered "shared."
- No UI Components: UI logic belongs in a dedicated design system, not here.
- Minimal Tests: Every package must include tests (e.g., using
vitest) to validate its integration logic. For instance,@wrelik/authincludes tests to ensure thatrequireUsercorrectly throws anAuthRequiredErrorwhen session data is missing.
Sources: CONTRIBUTING.md:1-19, packages/auth/src/index.test.ts:5-15
Summary
The wrelik-kit is the foundational infrastructure layer for the Wrelik ecosystem. By enforcing an adapter-first architecture through centralized configurations and strict linting rules, it ensures that application code remains decoupled from specific third-party vendors, facilitating long-term maintainability and flexibility.
Sources: README.md:1-10, DECISIONS.md:17-21