# Package Catalog And Decision Notes

## Purpose

Track package decisions in one place:

- what is already used
- why it is used
- when to keep/remove/replace
- which packages are candidates for later MVPs

This file is decision support, not a lockfile replacement.

## Current Core Stack (Used Now)

### Runtime and App Foundation

- `bun`:
  workspace package manager + runtime for scripts and local dev.
- `next` + `react` + `react-dom`:
  app framework for `admin` and `web`.
- `typescript`:
  typed contracts across apps/packages.

### Data and Validation

- `prisma` + `@prisma/client` + `pg` + `@prisma/adapter-pg`:
  DB schema/migrations + typed DB access on PostgreSQL.
- `zod`:
  shared runtime validation for domain schemas and CRUD inputs.

### Auth, State, Data Fetching

- `better-auth`:
  admin auth/session + role metadata baseline.
- `zustand`:
  lightweight client state (e.g. locale/UI state).
- `@tanstack/react-query`:
  async state/query cache patterns for admin/public app data fetching.
- `@tanstack/react-form` and `@tanstack/react-table`:
  form/table primitives in admin workflows.

### UI and Styling

- `tailwindcss` + `@tailwindcss/postcss`:
  utility-first styling baseline.
- `class-variance-authority`, `clsx`, `tailwind-merge`:
  component variant + class composition in `@cms/ui`.

### Testing and Quality

- `vitest`, `@testing-library/react`, `@testing-library/jest-dom`, `@testing-library/user-event`, `msw`, `jsdom`:
  unit/integration tests + UI interaction + API mocking.
- `@playwright/test`:
  end-to-end tests.
- `@biomejs/biome`:
  lint/format/check baseline.
- `turbo`:
  monorepo task orchestration.

### Docs and Release Governance

- `vitepress`:
  docs site.
- `conventional-changelog-cli`:
  changelog generation from conventional commits.
- `@commitlint/cli` + `@commitlint/config-conventional`:
  commit message schema enforcement.

## Media and Color Processing Notes

### Why `sharp` is typically the default choice

`sharp` is usually the best baseline for server-side image processing because:

- strong performance and memory behavior
- reliable resize/crop/format conversion pipeline
- robust support for production workloads
- good integration in Node/Bun server contexts

Use cases for this CMS:

- generate artwork renditions (thumb/card/full/custom)
- normalize uploads and output formats
- create banner/promo safe-size outputs
- optional watermark compositing pipeline

### Color extraction package options

1. `node-vibrant`
- Best for: quick dominant palette extraction for UI accents and tagging.
- Tradeoff: less control over advanced color science.

2. `colorthief`
- Best for: simple dominant-color extraction with minimal setup.
- Tradeoff: more limited output and tuning compared to richer libraries.

3. `culori` / `chroma-js` (supporting libs, often combined with extractor)
- Best for: color manipulation, conversion, contrast checks, palette normalization.
- Tradeoff: not a full image extractor by itself.

Recommended approach:

- MVP2 start with `sharp` + `node-vibrant` + `culori`
- keep extraction pipeline behind an internal adapter so replacement is easy

## Candidate Packages For Later (Not Installed Yet)

### File Upload and Storage Abstraction

- `@aws-sdk/client-s3` (+ presign utilities):
  for S3/R2/object storage adapters and signed upload/download flows.
- `uploadthing` or custom presigned-upload implementation:
  faster admin upload UX with secure direct-to-storage path.

### Rich Text / Page Builder

- `tiptap`:
  rich editorial experience for pages/news.
- `@dnd-kit/core`:
  drag-and-drop block ordering/page-builder interactions.

### Media Pipelines / Jobs

- `bullmq` + `ioredis`:
  background job queue for heavy media transforms (watermark/video/etc).

### Commissions and CRM Extensions

- `@tanstack/react-virtual`:
  large admin tables (requests/customers) without rendering bottlenecks.

### Observability / Reliability

- `@sentry/nextjs`:
  app error monitoring.
- `pino`:
  structured logs for services/workflows.

## Add/Remove Decision Rules

When adding a package, document:

1. problem it solves
2. why existing stack is insufficient
3. expected maintenance/runtime cost
4. fallback/exit plan

When removing/replacing:

1. list impacted modules
2. verify tests and migration path
3. update this catalog and related ADR/docs