Module Boundary Enforcement

This document explains how module boundaries are technically enforced in the admin panel, not just by convention.

Why Technical Enforcement?

“At scale, discipline fails.”

Your architecture relies on clear boundaries:

✅ packages/ui - Pure UI components
✅ packages/core - Business logic and API calls
✅ apps/panel - Application that uses both

Without enforcement, developers can accidentally:

❌ Import @monorepo/solid-pkg-ui from packages/core
❌ Import @monorepo/solid-pkg-core from packages/ui
❌ Use deep imports like @monorepo/solid-pkg-ui/src/components/Button

ESLint Rules

We use ESLint’s no-restricted-imports rule to enforce boundaries automatically.

Rule 1: UI Cannot Import Core

// ❌ WRONG - This will fail ESLint
// In packages/ui/src/components/UserCard.tsx
import { useUser } from '@monorepo/solid-pkg-core';

export function UserCard() {
  const user = useUser(); // ❌ UI should not know about business logic
  return <div>{user.name}</div>;
}

// ✅ CORRECT - Pass data as props
// In packages/ui/src/components/UserCard.tsx
interface UserCardProps {
  userName: string;
}

export function UserCard(props: UserCardProps) {
  return <div>{props.userName}</div>;
}

// In apps/panel/src/routes/users.tsx
import { UserCard } from '@monorepo/solid-pkg-ui';
import { useUser } from '@monorepo/solid-pkg-core';

export default function UsersPage() {
  const user = useUser();
  return <UserCard userName={user.data?.name} />;
}

Error Message:

❌ UI package cannot import from core package.
Keep UI components pure and framework-agnostic!
If you need business logic, pass it as props or use dependency injection.

Rule 2: Core Cannot Import UI

// ❌ WRONG - This will fail ESLint
// In packages/core/src/services/userService.ts
import { Button } from '@monorepo/solid-pkg-ui';

export function createUser() {
  // ❌ Business logic should not depend on UI
  return <Button>Create</Button>;
}

// ✅ CORRECT - Keep business logic UI-agnostic
// In packages/core/src/services/userService.ts
export async function createUser(userData: UserData) {
  return apiClient.post('/users', userData);
}

// In apps/panel/src/routes/users.tsx
import { Button } from '@monorepo/solid-pkg-ui';
import { createUser } from '@monorepo/solid-pkg-core';

export default function CreateUserPage() {
  const handleCreate = () => createUser(formData);
  return <Button onClick={handleCreate}>Create</Button>;
}

Error Message:

❌ Core package cannot import from UI package.
Business logic should be UI-agnostic!
If you need UI components, move the logic to the app layer.

Rule 3: No Deep Imports

// ❌ WRONG - Deep imports bypass the public API
import { Button } from "@monorepo/solid-pkg-ui/src/components/Button";
import { apiClient } from "@monorepo/solid-pkg-core/src/api/client";

// ✅ CORRECT - Use the public API
import { Button } from "@monorepo/solid-pkg-ui";
import { apiClient } from "@monorepo/solid-pkg-core";

Error Message:

❌ Deep imports are not allowed!
Use the public API instead:
  import { Component } from "@monorepo/solid-pkg-ui"
  import { hook } from "@monorepo/solid-pkg-core"

Running the Linter

Check for Violations

cd admin
pnpm lint

Auto-Fix (where possible)

cd admin
pnpm lint:fix

In CI/CD

Add to your CI pipeline:

# .github/workflows/ci.yml
- name: Lint Admin Panel
  run: |
    cd admin
    pnpm lint

Architecture Diagram

┌─────────────────────────────────────┐
│         apps/panel                  │
│  (Can import from both)             │
│  ✅ import from @monorepo/solid-pkg-ui  │
│  ✅ import from @monorepo/solid-pkg-core│
└─────────────────────────────────────┘
           │                │
           │                │
           ▼                ▼
┌──────────────────┐  ┌──────────────────┐
│  packages/ui     │  │  packages/core   │
│  (UI only)       │  │  (Logic only)    │
│  ❌ Cannot import│  │  ❌ Cannot import│
│     from core    │  │     from ui      │
└──────────────────┘  └──────────────────┘

Benefits

1. Prevents Circular Dependencies ✅

Without enforcement:

ui → core → ui → core → ... (infinite loop)

With enforcement:

app → ui
app → core
(No cycles possible)

2. Enforces Clean Architecture ✅

UI Layer: Presentation only
Core Layer: Business logic only
App Layer: Orchestration

3. Catches Mistakes Early ✅

✅ Fails in development (IDE shows errors)
✅ Fails in CI (prevents bad PRs)
✅ Clear error messages (explains why it’s wrong)

4. Self-Documenting ✅

The ESLint config serves as documentation:

// This rule documents the architecture
'no-restricted-imports': [
  'error',
  {
    patterns: ['@monorepo/solid-pkg-core'],
    message: 'UI cannot import from core',
  },
],

Common Scenarios

Scenario 1: UI Component Needs Data

❌ Wrong:

// packages/ui/src/components/UserList.tsx
import { useUsers } from '@monorepo/solid-pkg-core'; // ❌ Violates boundary

export function UserList() {
  const users = useUsers();
  return <div>{users.data?.map(...)}</div>;
}

✅ Correct:

// packages/ui/src/components/UserList.tsx
interface UserListProps {
  users: User[];
  isLoading: boolean;
}

export function UserList(props: UserListProps) {
  if (props.isLoading) return <div>Loading...</div>;
  return <div>{props.users.map(...)}</div>;
}

// apps/panel/src/routes/users.tsx
import { UserList } from '@monorepo/solid-pkg-ui';
import { useUsers } from '@monorepo/solid-pkg-core';

export default function UsersPage() {
  const users = useUsers();
  return <UserList users={users.data ?? []} isLoading={users.isLoading} />;
}

Scenario 2: Core Needs to Show UI

❌ Wrong:

// packages/core/src/services/notificationService.ts
import { Toast } from '@monorepo/solid-pkg-ui'; // ❌ Violates boundary

export function showNotification(message: string) {
  return <Toast>{message}</Toast>;
}

✅ Correct:

// packages/core/src/services/notificationService.ts
export interface Notification {
  id: string;
  message: string;
  type: 'success' | 'error';
}

export function createNotification(message: string): Notification {
  return { id: nanoid(), message, type: 'success' };
}

// apps/panel/src/components/NotificationProvider.tsx
import { Toast } from '@monorepo/solid-pkg-ui';
import { createNotification } from '@monorepo/solid-pkg-core';

export function NotificationProvider() {
  const notification = createNotification('Success!');
  return <Toast>{notification.message}</Toast>;
}

Configuration

The ESLint config is located at:

admin/eslint.config.js

To modify the rules, edit this file and run:

cd admin
pnpm lint

Module Boundaries - Architecture overview
Public API - Public API surface
Adding Features - Where to add code

Getting Started

Development

UI Components

Module Boundary Enforcement

Module Boundary Enforcement

Why Technical Enforcement?

ESLint Rules

Rule 1: UI Cannot Import Core

Rule 2: Core Cannot Import UI

Rule 3: No Deep Imports

Running the Linter

Check for Violations

Auto-Fix (where possible)

In CI/CD

Architecture Diagram

Benefits

1. Prevents Circular Dependencies ✅

2. Enforces Clean Architecture ✅

3. Catches Mistakes Early ✅

4. Self-Documenting ✅

Common Scenarios

Scenario 1: UI Component Needs Data

Scenario 2: Core Needs to Show UI

Configuration

​Module Boundary Enforcement

​Why Technical Enforcement?

​ESLint Rules

​Rule 1: UI Cannot Import Core

​Rule 2: Core Cannot Import UI

​Rule 3: No Deep Imports

​Running the Linter

​Check for Violations

​Auto-Fix (where possible)

​In CI/CD

​Architecture Diagram

​Benefits

​1. Prevents Circular Dependencies ✅

​2. Enforces Clean Architecture ✅

​3. Catches Mistakes Early ✅

​4. Self-Documenting ✅

​Common Scenarios

​Scenario 1: UI Component Needs Data

​Scenario 2: Core Needs to Show UI

​Configuration

​Related Documentation

Module Boundary Enforcement

Why Technical Enforcement?

ESLint Rules

Rule 1: UI Cannot Import Core

Rule 2: Core Cannot Import UI

Rule 3: No Deep Imports

Running the Linter

Check for Violations

Auto-Fix (where possible)

In CI/CD

Architecture Diagram

Benefits

1. Prevents Circular Dependencies ✅

2. Enforces Clean Architecture ✅

3. Catches Mistakes Early ✅

4. Self-Documenting ✅

Common Scenarios

Scenario 1: UI Component Needs Data

Scenario 2: Core Needs to Show UI

Configuration

Related Documentation