Guides

Litestore's repository comes with ten written guides that explain how the maintainers intend the codebase to be extended. Open the matching guide before you add a page, a model or a module, or start a refactor.

The guides are ten Markdown files in .claude/guides/, about 2,200 lines in total. A 747-line .claude/CLAUDE.md links to them and states the principles they build on.

The maintainers wrote them 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, and reading them yourself is the fastest way to learn how the maintainers intend the codebase to be extended.

The guides focus on design decisions rather than syntax. Biome and TypeScript catch formatting and type errors, and the guides cover the more expensive mistake of building something that shouldn't have been built at all. Each guide is also available as a skill that Claude Code runs by name, such as /before-building.

Guide index

.claude/CLAUDE.md starts with a row of links to all ten guides. After that come four instructions that name the guide to read for each kind of change.

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 sets the table column standards and the admin tone system. It explains the "Compute, Don't Cache" rule, including why a lifecycle status enum counts as a cache. Its "Trace to the Sink" section covers data flows that lead nowhere, and it states the canonical-cascade rule and the six-step method for approaching a task.

Guide files

Here are the ten files with their length in lines:

design-review.md         56
before-building.md       95
platform-primitives.md   47
schema-conventions.md    72
new-entity.md           110
code-style.md           269
data-api.md             275
project-specific.md     387
ui-components.md        421
style-guide.md          485

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

design-review.md

This guide is 56 lines long, and you read it before you build anything non-trivial. It takes about two minutes. It asks five questions you answer before writing code:

• Should this exist at all?
• Does a primitive already own it?
• Does it work against the rest of the code around it?
• 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. You might be overriding most of a component's default classes, adding a column for something you could compute, or building a card nobody asked for. You might also be minting a primitive without grepping, or duplicating a sibling.

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 names the existing code 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 an admin list page, an admin detail page, a settings card, a form or dialog, a web dashboard page and a storefront page.

The model section lists the mistakes people commonly make, such as adding an enum, caching a derived value, adding a speculative field with no reader, or letting a Json DSL column drive behaviour.

platform-primitives.md

This is the shortest guide, at 47 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, and each row names an example file and what enforces the rule.

To write your own version of anything in the table, you have to say which of four problems the existing primitive had. It might be missing a capability, it might not be able to express the rule, it might need too much boilerplate, or you might not have been aware it existed.

new-entity.md

This guide is 110 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:

1. The Prisma model
2. Permissions
3. Role grants
4. The server module
5. Activity logging
6. The soft-delete path
7. Cache tags
8. Sidebar nav
9. Section tabs
10. App pages
11. Components
12. The picker registry
13. Row indicators
14. Seed data
15. Dashboard widgets

The guide tags each step MECHANICAL, JUDGMENT, SILENT TRAP or ENFORCED. The tags mark which missed steps break the build and which ones fail silently. Use Coupons as the template entity.

code-style.md

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

Code style summarises this guide.

data-api.md

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

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

A section on Prisma field names lists the model names that differ from what people usually assume:

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 guarantee in GUARANTEES.md the change enforces.

ui-components.md

This guide is 421 lines long. Read it when you build or change UI, because it names the existing component to use before you write a new one.

It explains sprite icons through <Icon />, the styling token rules, and the semantic layout components, including when className is legitimate. It documents Stack usage with a full props reference. Its empty-state rules say to use EmptyList for an inline list or grid and AdminEmptyState with presets for admin tables, and to update an empty state when the UI it describes changes. It also covers layout and two-column boundary rules, a variant reference for Badge and Button, and the component name casing convention.

project-specific.md

This guide is 387 lines long, and it applies only to Litestore's admin.

It starts with a prop reference for the admin components and covers inline editing, where complex content gets a header action. It explains adminTokens type safety and the TrackedLink component, with the ref-parameter naming convention that makes storefront link analytics comparable. It documents the AdminEntityTable wrapper, and explains how to organise server-action files and when to split one.

schema-conventions.md

This guide is 72 lines long. Read it before you add or change a field in prisma/schema.prisma.

It asks you to give each fact the strongest owner that can enforce it. Conserved or globally unique facts belong in a Postgres constraint, index, trigger or view. Queryable business state belongs in a Prisma scalar or relation, request shapes belong in TypeScript and zod, and JSON is only for bounded, validated payloads that no money, stock, auth, identity or visibility rule depends on. It then lists the JSON fields that exist today and explains why each one is allowed.

style-guide.md

This is the longest guide, at 485 lines. It's a detailed reference for how code is written, from function declarations, comments and naming to icons, styling, form fields, error handling, CRUD modules, empty states and layout boundaries.

Reading order

Related