Blog Engine — Frontend & UI Specification

Last Updated: 2026-04-02 Status: Active

This document outlines the detailed user interface structure, page layouts, and component interactions for the Blog Engine within apps/seller-dashboard (Next.js). It covers the admin authoring experience and the SDK-powered public consumption layer.

1. Primary Navigation

The Blog Engine lives under the main Dashboard sidebar as a top-level navigation item labeled "Blog".

Dashboard
├── ...
├── Blog
│   ├── All Posts
│   ├── Categories
│   ├── Tags
│   └── Integration Guide
├── Content Engine
├── AI Assistant
└── Settings

2. Page Specifications

2.1 Blog Post List (All Posts)

Path: /dashboard/blog

Purpose: Central hub for managing all blog posts across statuses. The workspace owner sees every post at a glance and can create, edit, or manage publication state.

UI Components:

• Header Bar:

  • Page title: "Blog Posts" with subtitle "Manage and publish your content."
  • "Categories" button (outline) — navigates to /dashboard/blog/categories
  • "Tags" button (outline) — navigates to /dashboard/blog/tags
  • "Integration Guide" button — navigates to /docs/blog (opens in new tab)
  • "Create New Post" button — permission-gated (blog:posts.create), navigates to /dashboard/blog/new

• Filter Bar (below header, above grid):

  • Category Filter — Select dropdown listing all tenant categories with post counts. "All Categories" clears the filter. Filters via server-side ?category=slug query param.
  • Tag Filter — Select dropdown listing all tenant tags with post counts. "All Tags" clears the filter. Filters via server-side ?tag=slug query param.
  • Status Filter — Select dropdown: All Status | Draft | Published. Filters via ?status= query param.

• Post Grid (md:grid-cols-2, xl:grid-cols-3):

  • Each card displays:
    • Status Badge — Published (green) or Draft (amber)
    • Category Badge — Displays assigned category name (if any), styled as a muted pill
    • Tag Pills — Up to 3 tags displayed as small pills below the title, +N more if truncated
    • Post Title — truncated to 2 lines
    • SEO Description — truncated to 3 lines, falls back to excerpt
    • Last Updated — relative timestamp
  • Cards link to /dashboard/blog/{id} for editing
  • Hover effect: subtle shadow elevation and border highlight

• Empty State:

  • Illustration with message: "No blog posts yet"
  • Prominent "Create your first post" CTA

• Loading State:

  • Skeleton grid matching the card layout

• Error State:

  • Error message with retry action

State Management: Posts are fetched via fetchBlogPosts(params?) on mount and whenever filters change. Categories and tags are fetched on mount for the filter dropdowns. All stored in the Redux blog slice (posts[], categories[], tags[], loading, error).

2.2 Blog Post Editor

Path: /dashboard/blog/new (create) | /dashboard/blog/{id} (edit)

Purpose: Full-featured content authoring environment for creating and editing blog posts. Supports rich text editing, media embedding, SEO optimization, and publication lifecycle management.

Editor Layout

Header Bar

Editor Tab — Rich Text Editor (TipTap)

The editor is powered by TipTap with a custom extension stack:

• BlogToolbar — Fixed toolbar above the editor canvas:

  • History: Undo / Redo
  • Style dropdown: Normal text, Heading 1–6
  • Inline formatting: Bold, Italic, Strikethrough, Code
  • Lists: Bullet, Ordered, Task list
  • Blocks: Blockquote, Code block, Table
  • Media: Link, Image (via MediaDrawer), YouTube embed

• Bubble Menu — Appears on text selection for quick inline formatting (bold, italic, strikethrough, code, link)

• Floating Menu — Appears on empty lines for block-level insertion

• Slash Commands — Type / to open a searchable command palette:

  • Headings (H1–H3)
  • Lists (bullet, ordered, task)
  • Blocks (blockquote, code block, horizontal rule)
  • Media (image, YouTube)
  • Table

• Block Drag Handle — Appears on hover for drag-and-drop block reordering

• Table Controls — Row/column add/delete controls when a table is focused

• Footer Bar — Displays word count and estimated reading time

• Autosave — 30-second debounce in edit mode. Saves contentJson (TipTap JSON) to the backend.

Settings & SEO Tab

2.3 Category Management

Path: /dashboard/blog/categories

Purpose: Manage the taxonomy of blog posts. Categories are single-select, tenant-scoped, and provide the primary organizational axis for blog content.

Category List View

UI Components:

• Header Bar:

  • Page title: "Categories"
  • Back button — navigates to /dashboard/blog
  • "Create Category" button — permission-gated (blog:posts.create), opens the create dialog

• Category Table:

  • Columns: Name, Slug, Posts (count of posts using this category), Created, Actions
  • Actions column: Edit (pencil icon) and Delete (trash icon)
  • Rows are sorted alphabetically by name

• Create / Edit Dialog (shadcn Dialog):

  • Name Input — required, supports Enter to submit
  • Save — creates or updates the category. Slug is auto-generated server-side via slugify(name).
  • Validation: name must be unique within the tenant (backend returns 409 on slug conflict)

• Delete Confirmation:

  • Dialog: "Deleting this category will remove it from N posts. The posts themselves will not be deleted. Continue?"
  • Backend sets categoryId = null on affected posts (onDelete: 'set null')

• Empty State:

  • Message: "No categories yet. Create your first category to organize your blog posts."

2.4 Tag Management

Path: /dashboard/blog/tags

Purpose: Manage the flat tag taxonomy. Tags are multi-select, tenant-scoped, and provide a secondary cross-cutting organizational axis.

UI Components:

• Header Bar:

  • Page title: "Tags"
  • Back button — navigates to /dashboard/blog
  • "Create Tag" button — permission-gated (blog:posts.create), opens the create dialog

• Tag Table:

  • Columns: Name, Slug, Posts (count of posts using this tag), Actions
  • Actions column: Edit (pencil icon) and Delete (trash icon)
  • Rows are sorted alphabetically by name

• Create / Edit Dialog (shadcn Dialog):

  • Name Input — required, supports Enter to submit
  • Validation: name must be unique within the tenant (backend returns 409 on slug conflict)

• Delete Confirmation (shadcn AlertDialog):

  • Dialog: "Deleting "tag-name" will remove it from N post(s). The posts themselves will not be deleted."
  • Backend cascades delete through blog_post_tags junction table (onDelete: 'cascade')

• Empty State:

  • Message: "No tags yet. Tags are created automatically when you add them to posts, or create them here."

2.5 Integration Guide (SDK Documentation)

Path: /dashboard/docs/blog

Purpose: Embedded documentation that teaches workspace owners how to integrate the blog into their customer-facing website using the @vlozi/blog SDK.

Layout: Two-column — DocSidebar (left) + DocLayout (right) with lazy-loaded chapters.

Chapters:

Each chapter is lazy-loaded with Suspense boundaries and loading skeletons.

3. Component Architecture

3.1 Module File Structure

src/modules/blog/
├── api/
│   ├── blog.admin.api.ts       # All admin API functions (posts + categories + tags)
│   └── proxy.ts                # Next.js API route proxy
├── components/
│   ├── CategorySelector.tsx    # Category dropdown for editor
│   ├── TagInput.tsx            # Tag autocomplete combobox for editor
│   ├── FeaturedImagePicker.tsx # Featured image selector
│   └── SeoPanel.tsx            # SEO metadata inputs
├── editor/
│   ├── BlogEditorCore.tsx      # TipTap editor wrapper
│   ├── BlogToolbar.tsx         # Formatting toolbar
│   ├── EditorBubbleMenu.tsx    # Inline formatting popup
│   ├── EditorFloatingMenu.tsx  # Empty-line action menu
│   ├── SlashCommand.tsx        # / command palette
│   ├── CommandList.tsx         # Command list UI
│   ├── BlockDragHandle.tsx     # Block drag-and-drop
│   ├── TableControls.tsx       # Table manipulation
│   ├── LinkDialog.tsx          # URL insertion modal
│   ├── YouTubeDialog.tsx       # YouTube embed modal
│   ├── tiptap.extensions.tsx   # Extension configuration
│   └── nodes/
│       └── ImageNodeView.tsx   # Custom image node
├── hooks/
│   └── useBlogStore.ts         # Redux state hook (posts, categories, tags)
├── pages/
│   ├── BlogList.tsx            # Post listing page (with filters)
│   ├── BlogEditor.tsx          # Post editor page
│   ├── CategoryList.tsx        # Category management page
│   └── TagList.tsx             # Tag management page
└── store/
    ├── blog.slice.ts           # Redux slice
    └── blog.types.ts           # State types (BlogPostSummary, BlogCategory, BlogTag)

Next.js Route Files:

src/app/dashboard/blog/
├── page.tsx                     # /dashboard/blog
├── BlogListWrapper.tsx
├── new/
│   ├── page.tsx                 # /dashboard/blog/new
│   └── BlogEditorWrapper.tsx
├── [id]/
│   ├── page.tsx                 # /dashboard/blog/:id
│   └── BlogEditorWrapper.tsx
├── categories/
│   ├── page.tsx                 # /dashboard/blog/categories
│   └── CategoryListWrapper.tsx
└── tags/
    ├── page.tsx                 # /dashboard/blog/tags
    └── TagListWrapper.tsx

3.2 State Management

Redux Slice Shape:

interface BlogState {
  posts: BlogPostSummary[];
  categories: BlogCategory[];
  tags: BlogTag[];
  loading: boolean;
  error?: string;
}

Actions: setLoading(), setPosts(), setCategories(), setTags(), setError(), resetBlog()

3.3 API Layer

All admin API calls go through the Next.js proxy (/api/blog/*) which injects the JWT from NextAuth before forwarding to the gateway.

Post Endpoints:

Category Endpoints:

Tag Endpoints:

4. SDK Components (Public Consumption)

The @vlozi/blog package provides pre-built React components and hooks for customer websites.

Canonical reference: sdk-reference.md is the ground-truth for all SDK APIs. This section is a quick overview; consult that doc for complete prop tables and edge cases.

4.1 Setup & Provider

import { VloziClient } from '@vlozi/blog';
import { VloziProvider } from '@vlozi/blog/react';
 
const client = new VloziClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://your-gateway-url.com',
});
 
<VloziProvider client={client}>
  <App />
</VloziProvider>

4.2 Available Hooks

4.3 Available Components

4.4 SDK Types

interface Post {
  title: string;
  slug: string;
  excerpt: string;
  content?: string;
  publishedAt: string;
  seoTitle?: string;
  seoDescription?: string;
  featuredImageUrl?: string | null;
  category?: Category | null;
  tags?: Tag[];
  readingTime?: number;
}
 
interface Category {
  name: string;
  slug: string;
  postCount?: number;
}
 
interface Tag {
  name: string;
  slug: string;
  postCount?: number;
}
 
interface ListParams {
  page?: number;
  limit?: number;
  category?: string;
  tag?: string;
  search?: string;
  sort?: 'publishedAt' | 'title' | 'createdAt';
  order?: 'asc' | 'desc';
}

4.5 SDK Client Methods

client.blog.list({ page?, limit?, category?, tag?, search?, sort?, order? })
client.blog.get(slug)
client.blog.categories.list()
client.blog.tags.list()

5. Permission Model

All blog actions in the seller dashboard are gated by granular permissions:

6. Responsive Design

The blog editor is primarily a desktop experience, but the post list adapts to smaller screens.

7. Confirmation Dialogs & Safety

The editor employs multiple safety nets to prevent accidental data loss: