Vlozi Blog Engine — Product Vision

⚠️ VISION DOC — This describes where the product is going, not where it is today. For the current implemented API surface, see blog-service.md and sdk-reference.md.

The goal: Build a headless blog engine so good that any Vlozi user can have a world-class blog running on their platform in under 10 minutes — with an editor that rivals Notion, management that rivals WordPress, and integration as simple as 3 lines of code.

What We're Building

Vlozi Blog Engine is a fully managed, multi-tenant, headless blog system that ships as a core feature of the Vlozi platform. It consists of three pillars:

┌─────────────────────────────────────────────────────────────────┐
│                       Vlozi Blog Engine                          │
├──────────────────┬──────────────────┬───────────────────────────┤
│   ✏️ Editor       │   📊 Management   │   🔌 Integration           │
│                  │                  │                           │
│  Write like      │  Manage like     │  Integrate like           │
│  Notion          │  WordPress       │  Stripe                   │
├──────────────────┼──────────────────┼───────────────────────────┤
│ Block editor     │ Dashboard        │ REST API                  │
│ Slash commands   │ Analytics        │ JavaScript SDK            │
│ AI writing       │ Team workflows   │ React components          │
│ Media library    │ SEO toolkit      │ Webhooks                  │
│ Live preview     │ Scheduling       │ Pre-built themes          │
└──────────────────┴──────────────────┴───────────────────────────┘

Pillar 1 — The Editor ✏️

An editor so good that sellers actually enjoy writing content.

Block-Based Rich Editor

Media & Embeds

Writing Experience

AI Assistant (Future)

Pillar 2 — Blog Management 📊

Everything sellers need to run a professional content operation.

Post Management

Scheduling & Publishing

Organization

SEO Toolkit

Analytics (Future)

Pillar 3 — Integration 🔌

Integration so simple, a developer can go from zero to blog in 10 minutes.

REST API

A complete, well-documented, versioned REST API:

# Public (API Key auth)
GET    /blog/public/posts              → List published posts (paginated)
GET    /blog/public/posts/:slug        → Get post by slug (HTML content)
GET    /blog/public/posts/:slug/json   → Get post by slug (TipTap JSON)
GET    /blog/public/categories         → List categories
GET    /blog/public/categories/:slug   → Posts by category
GET    /blog/public/tags               → List tags
GET    /blog/public/tags/:slug         → Posts by tag
GET    /blog/public/search?q=          → Full-text search
GET    /blog/public/feed/rss           → RSS feed
GET    /blog/public/feed/atom          → Atom feed
GET    /blog/public/sitemap.xml        → XML sitemap
 
# Admin (JWT auth)
POST   /blog/admin/posts              → Create post
GET    /blog/admin/posts              → List all posts (any status)
GET    /blog/admin/posts/:id          → Get post by ID
PUT    /blog/admin/posts/:id          → Update post
DELETE /blog/admin/posts/:id          → Delete post (soft)
POST   /blog/admin/posts/:id/publish   → Publish
POST   /blog/admin/posts/:id/unpublish → Unpublish
POST   /blog/admin/posts/:id/schedule  → Schedule
POST   /blog/admin/posts/:id/duplicate → Duplicate
 
CRUD   /blog/admin/categories          → Full CRUD
CRUD   /blog/admin/tags                → Full CRUD
 
GET    /blog/admin/posts/:id/versions  → List versions
POST   /blog/admin/posts/:id/restore/:versionId → Restore version
 
POST   /blog/admin/media/upload        → Upload image
GET    /blog/admin/media               → List media
DELETE /blog/admin/media/:id           → Delete media

JavaScript SDK

Current SDK: @vlozi/blog — see sdk-reference.md for the real API. The examples below are the vision-state interface.

// Install
npm install @vlozi/blog
 
// Initialize
import { VloziClient } from '@vlozi/blog'
 
const client = new VloziClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://your-gateway-url.com',
})
 
// Fetch posts
const { data, meta } = await client.blog.list({ page: 1, limit: 10 })
 
// Fetch single post
const post = await client.blog.get('my-first-post')
 
// Categories & Tags
const categories = await client.blog.categories.list()
const tags = await client.blog.tags.list()

React Components (Drop-in UI)

// Install
npm install @vlozi/blog
 
// Components are in @vlozi/blog/react
import { BlogList, BlogPost, VloziProvider } from '@vlozi/blog/react'
 
// Blog listing page
<BlogLayout>
  <BlogList apiKey="your-key" postsPerPage={12} />
</BlogLayout>
 
// Individual post page
<BlogLayout>
  <BlogPost apiKey="your-key" slug={params.slug} />
</BlogLayout>
 
// With customization
<BlogList
  apiKey="your-key"
  theme="dark"
  layout="grid"           // grid | list | magazine
  showExcerpt={true}
  showAuthor={true}
  showDate={true}
  showCategory={true}
  showReadingTime={true}
  showFeaturedImage={true}
  categoryFilter="technology"
  className="my-custom-class"
/>

Pre-Built Themes

Ship 3–5 ready-to-use blog themes:

Each theme is:

• Fully responsive
• Dark mode compatible
• Customizable via CSS variables
• Accessible (WCAG 2.1 AA)

Webhooks (Future)

// Events
{
  "events": [
    "post.created",
    "post.updated",
    "post.published",
    "post.unpublished",
    "post.deleted"
  ],
  "url": "https://your-site.com/api/blog-webhook",
  "secret": "whsec_..."
}

Use cases: trigger static site rebuilds, sync with email lists, push to social media.

Markdown Interoperability (Future)

To cater to power users and developers, the blog engine will aim to support deep Markdown integration over time:

Model Context Protocol (MCP) Server (Future)

To empower the next generation of automation, LogicSpike will provide a native MCP Server. This allows AI agents (like Claude, Antigravity, or ChatGPT) to securely connect to a workspace and act as autonomous content creators.

Capabilities for AI Agents:

• Context-Aware Drafting: Agents can read existing published posts to learn the workspace's tone and style before writing.
• Autonomous Publishing: Agents can draft, format (with TipTap JSON/Markdown), and publish posts directly to the live site.
• Content Maintenance: Agents can search for outdated articles and autonomously push updates to keep technical or time-sensitive content fresh.

Content Delivery

Dual Response Format

Every public post endpoint returns content in the format requested:

HTML Rendering

Server-side TipTap JSON → HTML with:

• Full node support (all block types including tables, task lists, embeds)
• XSS sanitization on all text, URLs, and attributes
• Clean semantic HTML5 (<article>, <figure>, <figcaption>, etc.)
• BEM-style CSS classes on every element for easy styling
• Responsive images with srcset and loading="lazy"
• Code blocks with <pre><code class="language-{lang}"> for client-side highlighting

Security Model

┌──────────────────────────────────────────────┐
│                  Gateway                      │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐ │
│  │ JWT Auth  │  │ API Key  │  │ Rate Limit │ │
│  │ (Admin)   │  │ (Public) │  │ per tenant │ │
│  └──────────┘  └──────────┘  └────────────┘ │
└──────────────────────────────────────────────┘
                      │
              x-gateway-key (shared secret)
                      │
┌──────────────────────────────────────────────┐
│             Blog Service                      │
│  ┌──────────────┐  ┌─────────────────┐       │
│  │ Gateway Guard │  │ Tenant Isolation│       │
│  │ (secret check)│  │ (every query)   │       │
│  └──────────────┘  └─────────────────┘       │
│  ┌──────────────┐  ┌─────────────────┐       │
│  │ Permission   │  │ Input Validation│       │
│  │ (blog:posts.*)│ │ (Zod schemas)   │       │
│  └──────────────┘  └─────────────────┘       │
└──────────────────────────────────────────────┘

• Multi-tenant isolation: Every DB query is scoped by tenant_id — zero data leakage
• Admin endpoints: JWT auth → blog:posts.* permissions required
• Public endpoints: API Key auth → scoped to tenant
• Content sanitization: XSS prevention on render (HTML escape + URL protocol whitelisting)
• Rate limiting: Per-tenant, per-endpoint limits at the gateway level
• Direct access blocked: Blog service only accepts requests with valid x-gateway-key

Data Model (Vision — Aspirational)

⚠️ This ERD is the target schema, not the current one. Columns like og_image_url, canonical_url, expires_at, deleted_at and tables like blog_post_versions / blog_media do not exist yet. The live schema is in apps/blog-service/src/db/schema.ts and documented in blog-service.md.

What "Done" Looks Like

For the Seller (Dashboard User)

"I open my dashboard, click Blog, and I have a Notion-like editor where I can write beautifully formatted posts with images, code blocks, and embeds. I can organize with categories and tags, schedule posts for the future, see a live preview, and manage everything from a clean dashboard. SEO suggestions help me rank. Analytics show me what's working."

For the Developer (SDK Consumer)

"I install one npm package, pass my API key, and I have a fully functional blog on my site. I can use the pre-built React components for instant setup, or use the SDK to build a completely custom experience. The API is clean, well-documented, and returns exactly what I need."

For Vlozi (Platform)

"Blog is a core value-add that makes Vlozi sticky. Free-tier users get basic blogging (5 posts, 100MB media). Paid plans unlock unlimited posts, scheduling, analytics, AI writing, custom domains, and priority rendering. It requires zero infrastructure from users — we own the full stack."

Implementation Priority

Phase 1 — Foundation (Current + Quick Wins)

• TipTap editor with rich formatting
• CRUD + publish/unpublish
• Slug generation
• SEO title/description
• Media library integration
• TipTap → HTML renderer
• Fix autosave (wire onSave prop)
• Fix dark mode in menus
• Add undo/redo toolbar buttons
• Show word count + reading time
• Add featured image field
• Custom slug editing in UI

Phase 2 — Organization & Management

• Categories CRUD (API + Dashboard UI)
• Tags CRUD (API + Dashboard UI)
• Post→Category assignment
• Post→Tags assignment
• Soft-delete + trash
• Post list filtering (status, category, search)
• Bulk actions
• Post versioning

Phase 3 — Publishing & SEO

• Scheduled publishing
• OG image support
• Canonical URL
• SEO score/checklist
• Structured data (JSON-LD)
• RSS/Atom feed
• XML sitemap
• Live preview mode
• Publishing calendar

Phase 4 — Integration & SDK

• @vlozi/blog SDK package (shipped, v2.1.6)
• React components (@vlozi/blog/react)
• Complete public API (search endpoint, feeds, sitemap)
• Pre-built themes (Minimal, Magazine, Dev Blog)
• Full API documentation with examples
• Interactive API playground

Phase 5 — Advanced (Future)

• TipTap renderer: full node support (tables, tasks, YouTube, callouts, toggle)
• Webhook events
• Analytics dashboard
• AI writing assistant
• AI SEO suggestions
• Content expiry
• Multi-author workflows (In Review status)
• Custom domain for blog
• Full-text search

Competitive Positioning

Our edge: Blog isn't a standalone product — it's a deeply integrated feature of the Vlozi platform. Users get blog + auth + billing + team + media + analytics in one package, with an integration path that no standalone CMS can match.

This is the north star. Not everything ships at once, but every decision should move us toward this vision. When in doubt, ask: "Would a Notion user feel at home in the editor? Would a Stripe developer love the API? Would a WordPress user find the management complete?"

MCP note: The MCP server section above references "LogicSpike" — that's Vlozi. The capability description is accurate; the name was the old brand.