Learning Medusa

# Architecture Deep Dive: Admin Dashboard Integration

The Medusa Admin dashboard is a React application that connects to your backend API. Understanding how to extend it with widgets and UI routes is essential for building complete features.

## Admin Dashboard Architecture

```
┌─────────────────────────────────────────────────┐
│  Admin Dashboard (React + Vite)                 │
│  Running at: http://localhost:9000/app          │
│                                                 │
│  ┌──────────────┐    ┌──────────────┐          │
│  │   Widgets    │    │  UI Routes   │          │
│  │  (Inject)    │    │  (New Pages) │          │
│  └───────┬──────┘    └───────┬──────┘          │
│          │                   │                  │
│          └────────┬──────────┘                  │
│                   │                             │
│                   ▼                             │
│           ┌──────────────┐                      │
│           │   JS SDK     │                      │
│           └──────┬───────┘                      │
└──────────────────┼─────────────────────────────┘
                   │ HTTP Requests
                   ▼
┌─────────────────────────────────────────────────┐
│  Backend API (Node.js)                          │
│  Running at: http://localhost:9000              │
│                                                 │
│  ┌──────────────┐    ┌──────────────┐          │
│  │  API Routes  │    │  Workflows   │          │
│  └──────┬───────┘    └───────┬──────┘          │
│         │                    │                  │
│         └──────────┬─────────┘                  │
│                    ▼                            │
│           ┌──────────────┐                      │
│           │   Modules    │                      │
│           └──────────────┘                      │
└─────────────────────────────────────────────────┘
```

## Widgets vs. UI Routes

### Widgets: Extend Existing Pages

**What**: React components injected into existing admin pages at predefined zones

**When to use**:
- Adding information to existing pages
- Displaying related data
- Extending core entities (products, orders, customers)

**Examples**:
- Show brand on product detail page
- Show reviews on product detail page
- Show shipping status on order detail page

```typescript
// Widget Example
import { defineWidgetConfig } from "@medusajs/admin-sdk"

const ProductBrandWidget = ({ data: product }) => {
  return <Container>Brand: {product.brand?.name}</Container>
}

export const config = defineWidgetConfig({
  zone: "product.details.before",  // Where to inject
})

export default ProductBrandWidget
```

### UI Routes: Create New Pages

**What**: Completely new pages in the admin dashboard

**When to use**:
- Managing custom entities
- Custom dashboards or reports
- Standalone administrative interfaces

**Examples**:
- Brands management page
- Reviews management page
- Custom analytics dashboard

```typescript
// UI Route Example
import { defineRouteConfig } from "@medusajs/admin-sdk"

const BrandsPage = () => {
  return (
    <Container>
      <Heading>Brands</Heading>
      <DataTable data={brands} />
    </Container>
  )
}

export const config = defineRouteConfig({
  label: "Brands",
  icon: TagSolid,
})

export default BrandsPage
```

## Key Differences

| Aspect | Widgets | UI Routes |
|--------|---------|-----------|
| Purpose | Extend existing pages | Create new pages |
| Location | Injected into zones | New URLs |
| Navigation | No sidebar entry | Sidebar menu item |
| File path | `src/admin/widgets/` | `src/admin/routes/` |
| Configuration | `defineWidgetConfig()` | `defineRouteConfig()` |
| Props | Receive page entity | No special props |

## Widget Integration Patterns

### Pattern 1: Display Widget (Read-Only)

Show information from linked entities:

```typescript
// Product Brand Widget - Display Only
const ProductBrandWidget = ({ data: product }: DetailWidgetProps<AdminProduct>) => {
  const { data: queryRes