Blog System — Complete Workflow & Debugging Guide

1. Browser → GET /dashboard/blog
   │
2. BlogList.tsx calls fetchBlogPosts()
   │  → GET /api/blog/admin/posts  (Next.js API route)
   │
3. /api/blog/[...slug]/route.ts
   │  → imports proxy.ts handler
   │  → getToken({ req }) extracts JWT from NextAuth session
   │  → Builds headers:
   │     - Sets Authorization: Bearer <access_token>
   │     - Deletes host, cookie, connection headers
   │  → Forwards to: ${NEXT_PUBLIC_GATEWAY_URL}/blog/admin/posts
   │
4. Gateway (blog.proxy.ts)
   │  → authMiddleware verifies JWT via verifyAccessToken(token, JWT_PUBLIC_KEY)
   │  → Extracts tenant_id, user_id, permissions from JWT payload
   │  → Injects headers: x-tenant-id, x-user-id, x-user-permissions, x-gateway-key
   │  → Deletes host header
   │  → Forwards via BLOG_SERVICE binding to: /admin/posts
   │
5. Blog Service (index.ts middleware chain)
   │  → Logger (logs all requests)
   │  → dbMiddleware (creates DB connection from BLOG_DATABASE_URL)
   │  → Gateway secret check (validates x-gateway-key against GATEWAY_SECRET)
   │  → Context hydration (reads x-tenant-id, x-user-id, x-user-permissions)
   │  → requireTenant middleware (ensures tenant_id is present)
   │  → requirePermission("blog:posts.update") on /admin/* routes
   │
6. Route handler (routes/admin/posts.ts)
   │  → Queries DB with tenant_id scope
   │  → Returns JSON response
   │
7. Response flows back: Blog Service → Gateway → Proxy → Browser

1. Consumer App calls VloziClient.blog.list()
   │  → GET ${baseUrl}/blog/public/posts?page=1&limit=10
   │  → Headers: Authorization: Bearer <api_key>
   │
2. Gateway (blog.proxy.ts)
   │  → apiKeyMiddleware("blog") validates API key + scope
   │  → Extracts tenant_id from API key record
   │  → Injects: x-tenant-id, x-gateway-key
   │  → Forwards via BLOG_SERVICE binding to: /public/posts
   │
3. Blog Service processes request (same middleware chain, minus permission check)
   │  → Only returns published posts with publishedAt != null
   │  → Converts TipTap JSON → HTML for single post endpoints

// Request body (validated by createPostSchema)
{
  "title": "My Post",             // required, 1-255 chars
  "content": {},                   // optional, TipTap JSON
  "excerpt": "...",                // optional
  "seoTitle": "...",               // optional
  "seoDescription": "...",        // optional
  "featuredImageUrl": "https://...", // optional
  "categoryId": "cat_uuid",       // optional
  "tags": ["tag_uuid"],           // optional, max 10
  "scheduledFor": "2026-06-01T10:00:00Z" // optional ISO datetime
}
 
// Response
{ "id": "post_uuid", "status": "draft" }

// Request body (validated by updatePostSchema — at least 1 field required)
{
  "title": "Updated Title",        // optional
  "content": {},                    // optional
  "slug": "custom-slug",           // optional
  "excerpt": "...",                 // optional
  "seoTitle": "...",                // optional
  "seoDescription": "...",         // optional
  "featuredImageUrl": "https://...", // optional
  "categoryId": "cat_uuid",        // optional
  "tags": ["tag_uuid"],            // optional, max 10
  "scheduledFor": null             // optional, null to clear
}
 
// Response
{ "status": "saved" }

// Query params (validated by listPostsSchema)
?page=1&limit=10&category=slug&tag=slug&status=draft|published|scheduled&search=text&sort=publishedAt|title|createdAt&order=asc|desc
 
// Response
{
  "data": [
    { "id": "...", "title": "...", "status": "draft|published|scheduled", "seoDescription": "...", "updatedAt": "..." }
  ],
  "meta": { "page": 1, "limit": 10, "total": 42, "totalPages": 5 }
}

// Response — full post object
{
  "id": "...", "tenantId": "...", "authorId": "...",
  "title": "...", "slug": "...", "content": { /* TipTap JSON */ },
  "excerpt": "...", "featuredImageUrl": "...",
  "status": "draft|published|scheduled",
  "categoryId": "...", "seoTitle": "...", "seoDescription": "...",
  "scheduledFor": null, "publishedAt": null,
  "createdAt": "...", "updatedAt": "..."
}

1. User clicks "Login with Google" → NextAuth handles OAuth flow
2. NextAuth callback in [...nextauth]/route.ts:
   │  → Calls ${NEXT_PUBLIC_GATEWAY_URL}/auth/google with the Google token
   │  → Gateway's manager service validates & returns { access_token, refresh_token }
   │  → Tokens stored in NextAuth session: session.access_token = access_token
3. On subsequent requests:
   │  → getToken({ req }) reads the encrypted NextAuth cookie
   │  → Extracts token.access_token (the JWT signed by manager service)
   │  → This JWT contains: tenant_id, user_id, permissions[]

{
  "tenant_id": "tenant_xxx",
  "user_id": "user_xxx",
  "permissions": ["blog:posts.update", "team:members.invite", ...],
  "iat": 1709300000,
  "exp": 1709386400
}

apps/
├── blog-service/
│   ├── src/
│   │   ├── index.ts               ← Entry point, middleware chain
│   │   ├── context.ts             ← Hono context type augmentation
│   │   ├── middleware/
│   │   │   ├── auth.middleware.ts  ← requirePermission, requireTenant
│   │   │   └── db.middleware.ts    ← DB connection + caching
│   │   ├── routes/
│   │   │   ├── admin/posts.ts      ← Post CRUD + publish/unpublish/delete
│   │   │   ├── admin/categories.ts ← Category CRUD
│   │   │   ├── admin/tags.ts       ← Tag CRUD
│   │   │   ├── public/posts.ts     ← List + get by slug (published only)
│   │   │   ├── public/categories.ts ← List categories (published post counts)
│   │   │   └── public/tags.ts      ← List tags (published post counts)
│   │   ├── schemas/
│   │   │   ├── post.schema.ts      ← Post validation schemas
│   │   │   ├── category.schema.ts  ← Category validation schemas
│   │   │   └── tag.schema.ts       ← Tag validation schemas
│   │   ├── services/post.utils.ts ← ID generation, slugify, unique slug
│   │   ├── utils/tiptap-renderer.ts ← TipTap JSON → sanitized HTML
│   │   └── db/
│   │       ├── schema.ts          ← Drizzle table definitions + indexes
│   │       └── client.ts          ← DB client factory
│   ├── .env                       ← BLOG_DATABASE_URL
│   ├── .dev.vars                  ← GATEWAY_SECRET (local dev)
│   └── wrangler.toml              ← CF Worker config
│
├── gateway/
│   └── src/routes/blog.proxy.ts   ← Admin + Public proxy handlers
│
└── seller-dashboard/
    ├── .env.local                 ← NEXT_PUBLIC_GATEWAY_URL
    └── src/modules/blog/
        ├── api/
        │   ├── proxy.ts           ← Next.js API proxy (JWT forwarding)
        │   └── blog.admin.api.ts  ← Frontend API functions
        ├── pages/
        │   ├── BlogList.tsx       ← Post list page
        │   └── BlogEditor.tsx     ← Create/edit post page
        ├── editor/
        │   ├── BlogEditorCore.tsx  ← TipTap editor wrapper
        │   ├── BlogToolbar.tsx     ← Editor toolbar
        │   └── ...                 ← Dialogs, menus, extensions
        ├── components/SeoPanel.tsx ← SEO input fields
        └── store/
            ├── blog.slice.ts      ← Redux slice
            └── blog.types.ts      ← TypeScript types
 
packages/
├── blog-sdk/src/
│   ├── client.ts                  ← VloziClient (public API)
│   ├── types.ts                   ← Post, PaginatedResponse, Config
│   ├── index.ts                   ← Package exports
│   └── react/
│       ├── context.tsx            ← VloziProvider
│       ├── hooks.ts               ← usePosts, usePost
│       ├── components/            ← BlogList, BlogCard, BlogPost
│       └── utils.ts               ← cn() utility
│
└── core-types/src/blog.ts         ← BlogPost, BlogPostSummary types