Blog Service — Technical Documentation

1. Logger          → hono/logger — logs all requests
2. DB Middleware    → Creates/caches Neon connections from BLOG_DATABASE_URL and CORE_DATABASE_URL
3. Gateway Guard   → Validates x-gateway-key against GATEWAY_SECRET (comma-separated)
                   → Hydrates RequestContext from trusted headers:
                     x-tenant-id, x-user-id, x-user-permissions
4. requireTenant   → Rejects requests without tenant_id (400)
5. requirePermission("blog:posts.*")   → Post admin routes — checks permissions array
   requirePermission("blog:posts.read/create/update/delete") → Category admin routes (reuses post scopes)
   requirePermission("blog:posts.read/create/update/delete") → Tag admin routes (reuses post scopes)
                                            "system:owner" auto-bypasses all

// Create Post
{
  title: string (1-255 chars, required),
  content: any (optional, defaults to {}),
  seoTitle: string (optional),
  seoDescription: string (optional),
  excerpt: string (optional),
  featuredImageUrl: string URL | null (optional),
  categoryId: string (optional),
  tags: string[] (optional, max 10),
  scheduledFor: string datetime | null (optional),
}
 
// Update Post
{
  title?: string (1-255 chars),
  content?: any,
  slug?: string (lowercase, hyphens, 1-200 chars),
  seoTitle?: string,
  seoDescription?: string,
  excerpt?: string,
  featuredImageUrl?: string URL | null,
  categoryId?: string | null,
  tags?: string[] (max 10),
  scheduledFor?: string datetime | null,
}
// Refinement: at least one field must be provided
 
// List Posts
{
  page: number (min 1, default 1),
  limit: number (min 1, max 100, default 10),
  category: string (optional, filter by category slug),
  tag: string (optional, filter by tag slug),
  search: string (optional, max 200, case-insensitive title+excerpt match),
  sort: "publishedAt" | "title" | "createdAt" (default: "publishedAt"),
  order: "asc" | "desc" (default: "desc"),
  status: "draft" | "published" | "scheduled" (optional),
}
 
// Create/Update Category
{
  name: string (1-100 chars, required),
}
 
// Create/Update Tag
{
  name: string (1-50 chars, required),
}

{
  "counts": { "total": 42, "draft": 10, "published": 30, "scheduled": 2 },
  "deltas": { "last7d": 5, "last30d": 18 },
  "healthFlags": { "hasUnpublishedDrafts": true, "hasScheduledPosts": true },
  "recentEdits": [ { "id", "title", "slug", "status", "updatedAt" } ],
  "upcoming": [ { "id", "title", "slug", "scheduledFor" } ],
  "topCategories": [ { "name", "slug", "postCount" } ],
  "topTags": [ { "name", "slug", "postCount" } ]
}

/blog/admin/*  → authMiddleware (JWT) → blog.proxy → blog-service /admin/*
/blog/public/* → apiKeyMiddleware     → blog.proxy → blog-service /public/*

apps/blog-service/
├── src/
│   ├── index.ts                    # Hono app + middleware pipeline
│   ├── context.ts                  # RequestContext type augmentation
│   ├── db/
│   │   ├── client.ts               # Neon serverless + Drizzle setup
│   │   └── schema.ts               # 5 tables: blog_posts, blog_categories, blog_tags, blog_post_tags, blog_overview_snapshots
│   ├── middleware/
│   │   ├── auth.middleware.ts       # requirePermission + requireTenant
│   │   ├── credit-guard.middleware.ts  # Charge credit before handler; refund on failure/idempotency
│   │   └── db.middleware.ts         # DB connection middleware (BLOG + CORE, cached per isolate)
│   ├── routes/
│   │   ├── admin/posts.ts           # 11 admin endpoints (CRUD + lifecycle + soft-delete/restore)
│   │   ├── admin/categories.ts      # 4 admin endpoints (CRUD)
│   │   ├── admin/tags.ts            # 4 admin endpoints (CRUD)
│   │   ├── mcp/                     # 20 MCP tool endpoints (read + write)
│   │   ├── public/posts.ts          # 2 public endpoints (list + get-by-slug, with category/tag)
│   │   ├── public/categories.ts     # 1 public endpoint (list with published post counts)
│   │   └── public/tags.ts           # 1 public endpoint (list with published post counts)
│   ├── schemas/
│   │   ├── post.schema.ts           # Post validation schemas (with filter params)
│   │   ├── category.schema.ts       # Category validation schemas
│   │   └── tag.schema.ts            # Tag validation schemas
│   ├── services/
│   │   └── post.utils.ts            # ID generation + slug uniqueness
│   └── utils/
│       └── tiptap-renderer.ts       # TipTap JSON → sanitized HTML
├── drizzle/                         # Migration files
│   ├── 0000_wild_sage.sql
│   ├── 0001_fluffy_hedge_knight.sql
│   └── 0002_new_maelstrom.sql
├── drizzle.config.ts
├── wrangler.toml                    # Worker config (port 8791)
└── package.json

npm run dev        # wrangler dev --env-file=.env (local on :8791)
npm run deploy     # wrangler deploy --minify (production)
npm run generate   # drizzle-kit generate (create migration)
npm run migrate    # drizzle-kit migrate (apply migration)
npm run db:push    # drizzle-kit push (push schema to DB)
npm run studio     # drizzle-kit studio (DB browser)