---
name: Repository conventions
description: How an app scaffolded with create-raredays-app is laid out, its always-on pnpm workflow, and where each @raredays/* capability lives.
topics: [repo-conventions]
tags: [getting-started]
---

# Repository conventions

This app was scaffolded with `create-raredays-app`. The framework's
`@raredays/*` packages are workspace deps and ship their own skills, all
auto-discovered via the `DependencyBoundary` in `skillex.json`.

## Layout

```
app/
├── (app)/          # App shell (sidebar layout); no auth gate, each page checks the session like protected/page.tsx
├── (marketing)/    # Public landing page
├── api/            # Route handlers: `widgets/` sample API, `dev/` login/logout
├── demo/           # Sample pages (delete or replace)
├── protected/      # Example page gated on a session + permission
├── lib/
│   └── runtime.ts  # Provider composition root — edit here to swap providers
├── globals.css     # Tailwind v4 entry; scans @raredays/* dists for utilities
├── layout.tsx      # Root layout — wraps app in RaredaysProvider
└── theme.override.css  # Generated by `pnpm theme:build` from site.spec.ts
db/                 # Drizzle schema + migrations
mocks/              # MSW handlers (node + browser setups)
public/             # Static assets + mockServiceWorker.js
scripts/            # build-theme.mjs (behind `pnpm theme:build`)
site.spec.ts        # Single source of truth for site config — feeds theme:build
```

## Always-on workflow

```sh
pnpm install           # auto-runs skillex refresh via postinstall
pnpm dev               # Next dev server
pnpm dev:mocks         # Dev with MSW intercepting fetch
pnpm test              # vitest run (node-mode tests)
pnpm check             # lint + format:check + style + typecheck (gate before commit)
```

## Where things live in the framework

- `@raredays/core` — provider/port pattern, `RaredaysProvider`, env-config, ports
- `@raredays/components` — design system components (Tailwind v4, shadcn-flavored)
- `@raredays/identity` (+ `identity-better-auth`) — auth, sessions, organizations
- `@raredays/billing` (+ `billing-stripe`) — subscriptions, webhooks → events
- `@raredays/notifications` — in-app + email notification port
- `@raredays/cms` (+ `cms-hygraph`, `cms-bridge`) — headless CMS port + canonical-id bridge
- `@raredays/engagement` — declarative engagement tables (bookmarks, history, tags)
- `@raredays/state-machine` — typed state machine primitive
- `@raredays/i18n` — locale-aware translations + formatters
- `@raredays/mocks` — MSW setup for node + browser

Run `pnpm exec skillex query --package "@raredays/<name>"` for any of them
to see canonical usage patterns.