Guides

Litestore's repository comes with eight written guides that explain how the codebase expects to be extended. Read this page to find out which guide to open before you add a page, a model, a module or start a refactor.

The guides are eight Markdown files in .claude/guides/, 1,813 lines in total. A 749-line .claude/CLAUDE.md links to them and states the principles they build on.

They are written for an AI agent working in the repository, so that Claude Code makes changes that follow the conventions already in place.

They are still ordinary prose, though. Reading them yourself is the fastest way to learn how the codebase expects to be extended.

The guides teach judgement rather than syntax. The 25 scripts/check-*.ts harness checks catch a convention you forgot. The guides catch the more expensive mistake of building the wrong thing correctly.

How they hang together

.claude/CLAUDE.md starts with a row of links to all eight guides. After that come four instructions that tell you which one to read:

Before you change money, refunds, stock, identity, soft-delete visibility, cache invalidation, events/activity or auth, read ../GUARANTEES.md. A convenience rule in .claude/guides/ never overrides a system promise.
When you compose a feature, read Platform Primitives first.
When you build anything non-trivial, run the Design Review checklist.
For any net-new page, component, model or module, and for any refactor, read Before You Build.

The rest of CLAUDE.md sets out the principles the guides expand on: Guarantees over tolerance. Deletion over accumulation. Composition over extraction.

CLAUDE.md also contains these sections:

The table column standards
The admin tone system
The "Compute, Don't Cache" rule, including why a lifecycle status enum counts as a cache
"Trace to the Sink", about data flows that lead nowhere
The canonical-cascade rule
The six-step method for approaching a task

The eight guides

Here are the eight files with their length in lines:

design-review.md         56
before-building.md       95
platform-primitives.md   48
new-entity.md           109
code-style.md           269
data-api.md             273
ui-components.md        426
project-specific.md     537

You read the three shortest before you write anything. The three longest are references you come back to while you write.

design-review.md

This guide is 56 lines long. Read it before you build anything non-trivial.

It asks five questions you answer before writing code:

Should this exist at all?
Does a primitive already own it?
Does it fight the system it lives in?
Is the scope the minimum that satisfies the ask?
Does it cross a line that needs a human?

It ends with five warning signs that you are on the wrong track:

Overriding most of a component's default classes
Adding a column for something you could compute
Building a card nobody asked for
Minting a primitive without grepping
Duplicating a sibling

It takes about two minutes, and you do it before you build.

before-building.md

This guide is 95 lines long. Read it before you add a net-new page, model or module, and before any refactor.

It sets three hard rules:

Clone the nearest sibling. If you cannot name that file, stop and ask.
Treat the request as a ceiling, not a floor.
Add nothing that has no consumer today.

It then tells you what to clone for each of the four kinds of net-new work, which are a surface, a model, a module and a refactor.

For surfaces, a table names the exact file to copy and the primitives each one requires. It covers these surfaces:

An admin list page
An admin detail page
A settings card
A form or dialog
A web dashboard page
A storefront page

The model section names the traps people actually fall into:

Adding an enum
Caching a derived value
A speculative field with no reader
A Json DSL column driving behaviour

platform-primitives.md

This is the shortest guide, at 48 lines. Read it before you build a feature out of machinery that already exists.

It is a single table of the platform's standard ways of doing things, with one row per concept:

Lifecycle derived from decision timestamps (deriveTimestampStatus)
Time-windowed liveness computed on read
One canonical *_WHERE predicate, so a count and its list page cannot disagree
Publish gates
Transition legality
Definition registries keyed by a real union with satisfies
BaseCRUD for persistence
Polymorphic ownerType/ownerId references
The single Translation table
emitOperatorAlert as the one alert fan-out
The lib/import/ runtime
resolveStorefrontPage() for composition
Task definitions
Severity projection
SeoSubject

Each row names an example file and what enforces the rule.

If you want to write your own version of anything in the table, you have to say which of four problems the existing primitive had:

It is missing a capability.
It cannot express the rule.
It needs too much boilerplate.
You did not know it existed.

new-entity.md

This guide is 109 lines long. Read it when you add a new admin entity from start to finish.

It is an ordered checklist of the fifteen places you register a new admin entity:

The Prisma model
Permissions
Role grants
The server module
Activity logging
The soft-delete path
Cache tags
Sidebar nav
Section tabs
App pages
Components
The picker registry
Row indicators
Seed data
Dashboard widgets

Each step is tagged MECHANICAL, JUDGMENT, SILENT TRAP or ENFORCED. The tags show you which missed steps break the build and which ones fail without any sign.

Coupons is the entity to use as a template.

The guide also points out the traps. For modules with multi-word names, the AdminModule key differs from its value (socialMedia: "social_media"), and permission literals use the value form.

code-style.md

This guide is 269 lines long. Read it whenever you write TypeScript in this codebase.

It covers these conventions:

Function declarations for pure functions, arrow functions for server actions
The find/get/fetch/create/is/to verb standard
Platform-agnostic naming
Co-located types
Const objects instead of TypeScript enums
The ~/ path alias
cx from ~/utils/cva
Structured error returns instead of thrown strings
Schema-level validation with UI-level display
The no-backwards-compatibility rule, which forbids type aliases, function aliases and re-exports when renaming

See Code style for the parts of this guide that scripts check.

data-api.md

This guide is 273 lines long. Read it when you touch CRUD, queries, server actions or money.

It describes the data layer:

BaseCRUD mutation factories (createAction, updateAction, deleteAction, duplicateAction), with hand-written query actions around the module's read API
Activation prerequisites through lib/activation-rules.ts
API route error handling
Money formatting through fromCents, because a raw object literal fails on Prisma Decimal
The two server-action error patterns, and how to consume the [data, error] tuple

It also has a section on Prisma field names. It lists the model names that differ from what people expect:

db.shipping   not ShippingZone
db.coupon     not Discount
db.collab     not Affiliate

Finally, it gives four questions to answer before you change prisma/schema.prisma. The first asks which promise in GUARANTEES.md the change enforces.

ui-components.md

This guide is 426 lines long. Read it when you build or change UI.

It tells you which existing component to use before you write a new one.

It covers these topics:

Sprite icons through <Icon />
The styling token rules
The semantic layout components, and when className is legitimate
Stack usage, with a full props reference
The empty-state rules: EmptyList for an inline list or grid, AdminEmptyState with presets for admin tables, and why you must update an empty state when the UI it describes changes
Layout and two-column boundary rules
A variant reference for Badge and Button
The component name casing convention

project-specific.md

This is the longest guide, at 537 lines, and it applies only to Litestore's admin. It covers these topics:

AdminCardHeader action patterns
Inline editing with EditableField for simple fields, and a header action for complex content
adminTokens type safety
The TrackedLink component, and the ref-parameter naming convention that makes storefront link analytics comparable
The AdminEntityTable wrapper
The four useAdminMutation hooks (useAdminMutation, useFieldUpdate, useBulkMutation, useCreateMutation)
How to organise server-action files, and when to split one
Inline table-cell editing

Which guide to read

If you are about to build anything non-trivial, start with design-review.md.

If you are adding something net-new, such as a page, a component, a model or a module, or if you are refactoring, read before-building.md. Then find the sibling you will clone.

If you are building a feature out of machinery that already exists, read platform-primitives.md first. If you write your own version instead, be ready to say which of the four problems the primitive had.

If you are adding an admin entity, work through new-entity.md in order.

While you write, pick the reference for the layer you are in. Use code-style.md for TypeScript and data-api.md for CRUD, queries, server actions and money. Use ui-components.md for UI and project-specific.md for the admin.

Before any change to money, refunds, stock, identity, soft-delete visibility, cache invalidation, events, activity or auth, read ../GUARANTEES.md first.

A convenience rule in .claude/guides/ never overrides a system promise.