admin/docs/apps-architecture/react-frontend/layers/shared.md

Shared Layer

Table of Contents

• Purpose
• Recommended Structure
  • UI Components
    • Purpose
    • Core Principles
      1. Simple Components
      2. Composable Design
      3. Easily Customizable
      4. No Business Logic
    • Styling Strategy
      • Styling Philosophy
      • Technology Stack
  • Hooks
  • Utilities
  • Libraries
  • Assets
  • Styles

Purpose

The shared layer contains global reusable building blocks used across the entire application. The goal is to keep these utilities framework-level and reusable across the entire application.

shared/
├── ui/                       # dumb or basic UI components
│   ├── Button.tsx
│   ├── Modal.tsx
│   └── Card.tsx
│
├── widgets/                  # reusable composed UI blocks
│   ├── DataGrid/
│   └── screens/
│
├── forms/                    # reusable form composition helpers
│   └── composed/
│
├── editors/                  # reusable editor integrations
│   ├── tinymce/
│   └── image_input/
│
├── hooks/                    # reusable hooks
│   ├── useDebounce.ts
│   ├── useToggle.ts
│   └── useLocalStorage.ts
│
├── lib/                      # pure helpers & utilities
│   └── formatDate.ts
│
├── assets/                   # images, icons, fonts
│   ├── icons/
│   └── fonts/
│
└── styles/                   # global CSS, variables, Tailwind overrides
    ├── globals.css
    └── variables.css

Recommended Structure

shared/
|
| --- ui/                # primitive UI components
|
| --- widgets/           # reusable composed UI blocks
|
| --- forms/             # reusable form composition
|
| --- editors/           # reusable editor wrappers
|
| --- hooks/             # generic reusable hooks
|
| --- utils/             # pure helper functions
|
| --- lib/               # pure helpers and utility services
|
| --- assets/            # images, icons, fonts
|
| --- styles/            # global styling
|
| --- constants/         # global constants

UI Components

Purpose

The goal of the UI layer is to provide simple, composable, and customizable components that can be reused across the application.

• components are simple building blocks
• components are composable
• components are fully customizable
• components are not tied to business logic

UI components should behave like Lego blocks that can be combined into larger UI structures.

Core Principles

1. Simple Components

Examples:

• Button
• Input
• Card
• Modal
• Dropdown

2. Composable Design

Components must support composition. Composition allows developers to build complex UI without modifying base components.

Example:

<Card>
  <CardHeader />
  <CardContent />
  <CardFooter />
</Card>

<Button>
  <Icon />
  Save
</Button>

3. Easily Customizable

UI components should allow customization through:

• className
• variants
• props
• composition

<Button variant="outline" size="lg">
  Save
</Button>

4. No Business Logic

UI components must remain presentation-only. May include local state.

They should NOT:

• call API
• use React Query
• contain form submission logic
• contain domain-specific logic

Styling Strategy

Styling Philosophy

Styling follows these principles:

• Utility-first styling
• Design tokens for consistency
• Component-level styling
• Variants instead of style duplication
• Minimal custom CSS

Technology Stack

• TailwindCSS - primary styling system
• class-variance-authority (CVA) - component variants
• CSS variables - design tokens
• Radix primitives - accessible UI building blocks

Custom CSS should be minimal and centralized.

Hooks

The shared/hooks/ folder contains generic reusable hooks. These hooks must not depend on entities or business logic.

shared/hooks/
| --- useDebounce.ts
| --- useToggle.ts
| --- usePrevious.ts
| --- useLocalStorage.ts

Utilities

The shared/utils/ folder contains pure helper functions. These functions should be stateless and reusable

shared/utils/
| --- formatDate.ts
| --- formatCurrency.ts
| --- generateId.ts
| --- sleep.ts

Libraries

The shared/lib/ folder contains pure helpers and utility services.

Examples include:

• date formatting helpers
• name formatting helpers
• URL/file path helpers
• phone-number formatting helpers

shared/lib/
| --- time/
| --- phone_number/
| --- resolveFileURL.ts

Assets

The shared/assets/ folder stores static resources used across the application.

shared/assets/
| --- icons/
| --- fonts/

Styles

The shared/styles/ folder contains global styling resources.

Typical usage:

• CSS variables
• Tailwind configuration extensions
• global resets

shared/styles/
| --- globals.css
| --- variables.css
| --- tailwind.css