---

name: project-architecture description: When you need to understand the directory structure, open-core model, or where to add new code.

Project Architecture & Monorepo Structure

1. High-Level Layout

2. Core Rules

Open-Core Model

• Core: Everything in this repo is Open Source (MIT), except libs/ecommerce (if present).
• Premium: Private extensions live in libs/ecommerce.

Code Placement Decisions

• New UI Component: Go to libs/ui.
• New Helper Function: Go to libs/utils.
• New Database Query: Go to libs/db.
• New Page/Route: Go to apps/nextblock/app.
• CLI Logic: Go to apps/create-nextblock.

3. Dependency Graph Rules

• libs/* can depend on other libs/* (e.g., ui depends on utils).
• apps/* depend on libs/*.
• Crucial: libs/ui MUST NOT depend on apps/nextblock. This creates a circular dependency and breaks the build.

4. Template Syncing

• apps/create-nextblock/templates/nextblock-template is generated code.
• Do not edit it directly.
• Edit apps/nextblock instead, then run npm run sync:create-nextblock to update the template.