Project Guidelines

Nimara Project Guidelines & Architecture

This skill helps you navigate Nimara's layered monorepo architecture and make correct decisions about where code belongs and how layers interact.

Quick Layer Reference

apps/                          # User-facing applications
├── storefront/                # Next.js customer-facing storefront
├── marketplace/               # Vendor dashboard, ledger, payouts
├── stripe/                    # Stripe payment integration app
└── automated-tests/           # CodeceptJS E2E tests

packages/                      # Shared, reusable code
├── domain/                    # Pure business logic (no framework deps)
├── infrastructure/            # External integrations (APIs, GraphQL)
├── foundation/                # Utilities, hooks, helpers
├── features/                  # Feature implementations (UI + logic)
├── ui/                        # Shared UI components (Shadcn-style)
└── config/                    # Shared configs (Tailwind, ESLint, etc.)

Package Layers Explained

1. Domain Layer (@nimara/domain)

Responsibility: Pure business logic, types, constants, entities—zero external dependencies.

What belongs here:

• TypeScript types and interfaces (Product, Order, User, etc.)
• Enums and constants (PaymentStatus, OrderStatus, etc.)
• DTOs (Data Transfer Objects) for serialization
• Pure utility functions with no side effects
• Error types and Result<T, E> pattern
• Business rules and validators

What does NOT belong here:

• Framework imports (React, Next.js, Node APIs)
• External API clients (Saleor, ButterCMS)
• Database operations
• HTTP requests
• Environment variables

Example structure:

packages/domain/
├── objects/
│   ├── Result.ts          # Result<T, E> type
│   └── Product.ts         # Product entity
├── types/
│   ├── Cart.types.ts
│   └── Order.types.ts
├── constants/
│   ├── paymentStatus.ts
│   └── orderStatus.ts
└── validators/
    └── emailValidator.ts

Key rule: Domain is a leaf package—it imports nothing from other Nimara packages.

2. Foundation Layer (@nimara/foundation)

Responsibility: Core utilities, React hooks, helpers—framework-aware but integration-agnostic.

What belongs here:

• React hooks (useLocalStorage, usePagination, etc.)
• Utility functions (formatPrice, formatDate, slugify, etc.)
• Constants and helpers used across apps
• Custom error classes
• Shared adapters for third-party libraries
• Shared type utilities and helpers

What does NOT belong here:

• Feature-specific logic (belongs in features or infrastructure)
• API clients or external integrations
• UI components (those go in ui)
• App-specific configurations

Example structure:

packages/foundation/
├── hooks/
│   ├── usePagination.ts
│   └── useLocalStorage.ts
├── utils/
│   ├── formatPrice.ts
│   ├── formatDate.ts
│   └── slugify.ts
└── types/
    └── common.types.ts

Key rule: Foundation is a leaf package—it depends only on domain.

3. Infrastructure Layer (@nimara/infrastructure)

Responsibility: External integrations (Saleor, ButterCMS, Algolia, Stripe, etc.) and GraphQL operations.

What belongs here:

• GraphQL queries and mutations (.graphql files + generated types)
• External API clients and service adapters
• Data providers (Saleor product provider, CMS provider, etc.)
• Serializers and transformers (raw API response → domain types)
• Use-cases that coordinate infrastructure calls
• Result-based error handling for external operations

What does NOT belong here:

• React components
• UI logic
• App-specific routing
• Server Actions (those live in apps)

Example structure:

packages/infrastructure/
├── saleor/
│   ├── queries/
│   │   ├── GetProducts.graphql
│   │   └── GetProducts.generated.ts
│   ├── mutations/
│   │   └── AddToCart.graphql
│   ├── client.ts           # Saleor client config
│   └── providers/
│       └── ProductProvider.ts
├── butter-cms/
│   ├── client.ts
│   └── providers/
│       └── PageProvider.ts
├── algolia/
│   ├── client.ts
│   └── search.ts
└── use-cases/
    ├── getProduct.ts
    ├── searchProducts.ts
    └── addToCart.ts

Key rule: Infrastructure depends on domain + foundation. Services in infrastructure should return Result<T, E> for operations that can fail.

4. Features Layer (@nimara/features)

Responsibility: Feature implementations—combining UI, state, and business logic into cohesive features.

What belongs here:

• Feature-specific React components
• Feature state management (Context, hooks)
• Feature-specific Server Actions
• Feature forms and validation
• Feature-specific utilities
• Feature documentation

What does NOT belong here:

• Shared UI primitives (those go in ui)
• Core utilities (those go in foundation)
• Business logic (that's domain)

Example structure:

packages/features/
├── checkout/
│   ├── Checkout.tsx
│   ├── CheckoutProvider.tsx
│   ├── useCheckout.ts
│   ├── checkoutFormSchema.ts
│   └── _actions/
│       └── completeCheckout.ts
├── product-search/
│   ├── ProductSearch.tsx
│   ├── SearchFilters.tsx
│   └── useProductSearch.ts
└── user-account/
    ├── AccountSettings.tsx
    ├── useUserProfile.ts
    └── _actions/
        └── updateProfile.ts

Key rule: Features depends on all packages (domain, foundation, infrastructure, ui). This is the only layer that depends on everything.

5. UI Layer (@nimara/ui)

Responsibility: Reusable UI components and design system—presentational, not business logic.

What belongs here:

• UI primitives (Button, Input, Card, Modal, etc.)
• Form components
• Layout components
• Icons and SVGs
• Design tokens and theme utilities
• Shared styles and Tailwind extensions

What does NOT belong here:

• Business logic
• Feature-specific components
• State management
• Server Actions

Example structure:

packages/ui/
├── components/
│   ├── Button.tsx
│   ├── Input.tsx
│   ├── Modal.tsx
│   ├── Card.tsx
│   └── Form/
│       ├── FormField.tsx
│       └── FormError.tsx
├── icons/
│   ├── ChevronDown.tsx
│   └── ShoppingCart.tsx
├── layouts/
│   ├── Container.tsx
│   └── Grid.tsx
└── theme/
    └── colors.ts

Key rule: UI is a leaf package or minimal-dependency—imports only domain and foundation if needed.

Dependency Flow (CRITICAL)

The dependency direction is unidirectional:

domain (leaf)
   ↑
foundation (leaf)
   ↑
infrastructure ─┐
   ↑             │
   └─ domain    │
   └─ foundation│
                ├→ features
   ui (leaf)    │
   ↑            │
ui ─────────────┘
   ↑
   └─ domain, foundation

apps (storefront, stripe)
   ↑
   └─ features, infrastructure, ui, foundation, domain

In practice:

• Apps import from: features, infrastructure, ui, foundation, domain
• Features import from: infrastructure, ui, foundation, domain (all packages!)
• Infrastructure imports from: domain, foundation
• Foundation imports from: domain only
• Domain imports from: nothing (pure business logic)
• UI imports from: domain, foundation (minimal)

What NEVER happens:

• ❌ Domain imports anything else
• ❌ Infra imports from Features, UI, or apps
• ❌ Foundation imports from Infra, Features, or UI
• ❌ Apps import from other apps

Decision Tree: Where Does This Code Belong?

Question 1: Is it pure business logic (no framework, no API calls)?

• Yes → domain
  • Type definitions, constants, validators
• No → Next question

Question 2: Is it a utility/helper function or React hook?

• Yes → foundation
  • Helper functions, hooks, adapters
• No → Next question

Question 3: Is it an external API integration or GraphQL operation?

• Yes → infrastructure
  • API clients, GraphQL, data providers
• No → Next question

Question 4: Is it a reusable UI component (no business logic)?

• Yes → ui
  • Buttons, inputs, modals, layouts
• No → Next question

Question 5: Is it a feature combining UI + logic?

• Yes → features
  • Checkout form, product search, account settings
• No → It's app-specific → Put in apps/storefront/ or apps/stripe/

Common Scenarios

Scenario 1: Add a new payment method integration

1. Domain: Add payment type/status constants

   // packages/domain/constants/paymentStatus.ts
   export const PAYMENT_METHODS = {
     CREDIT_CARD: "credit_card",
     DIGITAL_WALLET: "digital_wallet",
   } as const;

2. Infrastructure: Create the payment provider + GraphQL mutations

   packages/infrastructure/payments/
   ├── mutations/CreatePayment.graphql
   ├── mutations/CreatePayment.generated.ts
   └── providers/PaymentProvider.ts

3. Features: Create the payment form component

   packages/features/payment-form/
   ├── PaymentForm.tsx
   └── usePayment.ts

4. App: Use in checkout page

   // apps/storefront/src/app/[locale]/(checkout)/payment/page.tsx
   import { PaymentForm } from '@nimara/features';
   export default function PaymentPage() {
     return <PaymentForm />;
   }

Scenario 2: Add a utility function

1. Check if it's domain logic (pure business rules): If yes → domain
2. Check if it's a helper used across features: If yes → foundation
3. If feature-specific: Keep it in the feature folder

Dependency Management (CRITICAL)

RULE: NEVER automatically install new dependencies. ALWAYS require explicit user approval first.

Why This Matters

• Dependencies affect bundle size, security, and maintenance burden
• Each package adds complexity and potential conflicts
• Alternatives exist and should be evaluated first
• Team should agree on tech choices