> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evomarketing.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Frontend overview

> Next.js admin dashboard architecture

The EVO Dialed frontend is a **Next.js 15** application using the App Router, deployed to Vercel. It serves as the admin console for the EVO team.

## Technology stack

| Component  | Technology        | Purpose                 |
| ---------- | ----------------- | ----------------------- |
| Framework  | Next.js 15        | React-based admin UI    |
| React      | React 19          | UI library              |
| Styling    | Tailwind CSS v4   | Utility-first CSS       |
| Components | shadcn/ui         | Component library       |
| State      | TanStack Query v5 | Server state management |
| Auth       | Better Auth       | Session management      |
| Realtime   | ActionCable       | WebSocket connections   |
| Icons      | Phosphor Icons    | Icon library            |
| Hosting    | Vercel            | Edge deployment         |

## Directory structure

```
app/
  (auth)/           # Login, invite, password reset
  (app)/            # Authenticated routes
    team/           # Admin pages
    community/      # Creator pages
  (public)/         # Public share pages
  api/              # API route handlers

components/
  app-shell/        # Main layout, navigation
  ui/               # shadcn/ui primitives
  team/             # Admin components
  creator/          # Creator components

lib/
  api/              # API client layer
  auth.ts           # Server auth config
  auth-client.ts    # Client auth hooks
  action-cable.ts   # WebSocket client
  utils.ts          # Shared utilities
```

## Route groups

| Group       | Purpose                                  |
| ----------- | ---------------------------------------- |
| `(auth)/`   | Login, invite acceptance, password reset |
| `(app)/`    | Authenticated product routes             |
| `(public)/` | Public share pages                       |

### Admin routes (`/team/*`)

| Route                   | Purpose               |
| ----------------------- | --------------------- |
| `/team/dashboard`       | Admin overview        |
| `/team/brands`          | Brand management      |
| `/team/creators`        | Creator roster        |
| `/team/creator-roster`  | New revamped roster   |
| `/team/pipeline`        | Brand pipeline        |
| `/team/mission-control` | Campaign board        |
| `/team/metrics`         | Analytics             |
| `/team/brand-deals`     | Job board admin       |
| `/team/ambassadors`     | Ambassador program    |
| `/team/announcements`   | Creator announcements |

### Creator routes (`/community/*`)

| Route                     | Purpose             |
| ------------------------- | ------------------- |
| `/community/get-started`  | Onboarding wizard   |
| `/community/brand-deals`  | Browse deals        |
| `/community/chats`        | Community messaging |
| `/community/leaderboards` | Monthly rankings    |

## Key concepts

### User roles

```typescript theme={null}
// Admin (EVO team)
user.userTyp === "evo"

// Creator
user.userTyp === "creator"
```

Navigation is role-based - admins see `/team/*` routes, creators see `/community/*` routes.

### Feature flags

```typescript theme={null}
// lib/feature-flags.ts
export const featureFlags = {
  creatorMetaOauth: boolean,
  appReviewer: boolean,
  ambassadorProgram: boolean,
}
```

## App Shell

The main layout wraps authenticated pages.

**File:** `components/app-shell/app-shell.tsx`

Features:

* Collapsible sidebar navigation
* Header with user menu
* Notification bell
* Global search
* Real-time subscriptions

### Navigation

**File:** `components/app-shell/nav-items.ts`

Role-based navigation items:

* Admin items for EVO team
* Creator items for content creators
* Conditional items based on feature flags

## Conventions

From project rules:

1. **Brand selection must use searchable combobox** - never plain `<Select>`
2. **Never read localStorage during render unguarded** - wrap in try/catch
3. **Wrap non-critical creator widgets in `SilentErrorBoundary`**
4. **Route-only UI goes in `_components/` subdirectories**

## Running locally

```bash theme={null}
# Install dependencies
npm install

# Configure environment
cp .env.example .env.local
# Edit .env.local

# Start development server
npm run dev
```

The admin dashboard runs at `http://localhost:3001`.

## Pre-push checklist

```bash theme={null}
npm run typecheck
npm run lint
```

## Related documentation

* [Pages](/frontend/pages) - Route structure
* [Components](/frontend/components) - UI components
* [API Client](/frontend/api-client) - Backend communication