Blog Module — Implementation Roadmap
Author: Socrates 🧠
Date: 2026-04-20
Status: Approved — Phase 3 unblocked
File Structure
hoffdesk-api/
blog/
__init__.py
router.py ← FastAPI routes (public + admin)
models.py ← Pydantic request/response models
service.py ← Business logic (CRUD, publish, search)
storage.py ← SQLite + Markdown I/O
builder.py ← Static site generation (Jinja2 → HTML)
templates/
post.html.j2 ← Individual post template
index.html.j2 ← Blog index template
category.html.j2 ← Category archive template
tag.html.j2 ← Tag archive template
feed.xml.j2 ← RSS 2.0 feed template
sitemap.xml.j2 ← Sitemap template
static/ ← Symlinked from shared/design-tokens/
data/
blog/
posts/ ← Markdown source (git-tracked)
building-multi-agent-home-dashboard/
index.md
images/
dashboard-hero.jpg
another-post/
index.md
blog.db ← SQLite metadata (gitignored)
dist/ ← Generated static HTML (gitignored)
blog/
index.html
building-multi-agent-home-dashboard/
index.html
category/
engineering/
index.html
tag/
openclaw/
index.html
feed.xml
sitemap.xml
api/
posts.json
posts/
building-multi-agent-home-dashboard.json
Implementation Phases
Phase 1 — Core API + Storage (Week 1)
| # | Task | Depends On | Owner |
|---|---|---|---|
| 1.1 | Set up blog module structure in hoffdesk-api | — | Socrates |
| 1.2 | Implement storage.py — SQLite schema, Markdown parsing, CRUD |
1.1 | Socrates |
| 1.3 | Implement models.py — Pydantic models matching API spec |
1.1 | Socrates |
| 1.4 | Implement service.py — business logic layer |
1.2, 1.3 | Socrates |
| 1.5 | Implement router.py — public read endpoints |
1.4 | Socrates |
| 1.6 | Wire blog router into main FastAPI app | 1.5 | Socrates |
| 1.7 | Write integration tests for public API | 1.6 | Socrates |
Deliverable: Working read API at localhost:8000/api/blog/*
Phase 2 — Admin API + Publishing (Week 1-2)
| # | Task | Depends On | Owner |
|---|---|---|---|
| 2.1 | Implement admin write endpoints (CRUD) | 1.6 | Socrates |
| 2.2 | Publish/unpublish actions with static generation | 2.1, 3.1 | Socrates |
| 2.3 | Cloudflare Access auth verification (header checks) | 2.1 | Socrates |
| 2.4 | Rebuild/regenerate CLI commands | 2.2 | Socrates |
| 2.5 | Admin endpoint tests | 2.2 | Socrates |
Deliverable: Working admin API at localhost:8000/api/blog/admin/*
Phase 3 — Static Generation + Deployment (Week 2)
| # | Task | Depends On | Owner |
|---|---|---|---|
| 3.1 | Jinja2 templates for HTML generation | Daedalus D1 tokens | Socrates + Daedalus |
| 3.2 | builder.py — static site generation pipeline |
3.1 | Socrates |
| 3.3 | Deploy pipeline: static output → Cloudflare Pages | 3.2 | Wadsworth |
| 3.4 | Webhook integration for auto-deploy | 3.3 | Socrates |
| 3.5 | RSS feed generation | 3.2 | Socrates |
| 3.6 | Sitemap generation | 3.2 | Socrates |
Deliverable: Published blog posts live at hoffdesk.com/blog/
Phase 4 — Admin UI + Polish (Week 2-3)
| # | Task | Depends On | Owner |
|---|---|---|---|
| 4.1 | HTMX admin interface for post management | Daedalus design | Daedalus + Socrates |
| 4.2 | Markdown editor with live preview | 4.1 | Daedalus |
| 4.3 | Image management (git-based workflow) | 3.3 | Socrates |
| 4.4 | Search endpoint (FTS5) | 1.7 | Socrates |
| 4.5 | Related posts algorithm | 1.7 | Socrates |
Deliverable: Complete blog with admin UI
Dependencies on Daedalus
| What | When | Blocking? |
|---|---|---|
| Design tokens / CSS for blog templates | Phase 3.1 | Yes — can't generate styled HTML without them |
| Blog index page layout (HTMX or static?) | Phase 3.1 | Yes — determines template structure |
| Admin UI design | Phase 4.1 | Yes — but Socrates can build functional-first, Daedalus skins later |
| Post page layout design | Phase 3.1 | Yes — determines Jinja2 template structure |
| Responsive image strategy | Phase 3 | Partially — can start with simple <img> |
Resolved Design Decisions (Daedalus + Socrates)
| # | Question | Decision | Rationale |
|---|---|---|---|
| 1 | Post page layout | Full HTML pages | SEO-primary; static HTML at edge, indexable by crawlers |
| 2 | Category/tag archive | Card grid (2-col desktop, 1-col mobile) | Matches post index; visual scanning on wider screens |
| 3 | Admin UI | Functional-minimal first, Daedalus skins later | Socrates builds plumbing in Phase 4; Daedalus designs admin in Sprint 2 |
| 4 | Image handling (MVP) | Simple <img> only |
No images on cards in Sprint 1; <picture>/srcset deferred to Sprint 2 |
| 5 | RSS feed | Full content, RSS 2.0 | Content strategy mandates full-content; RSS 2.0 wider support |
| 6 | Search (Sprint 1) | Client-side Fuse.js | Lightweight; backend FTS5 reserved for scale |
Template files are in workspace-daedalus/blog/templates/ — ready for Socrates to wire into builder.py.
This document lives at shared/project-docs/blog/blog-implementation-roadmap.md
Socrates 🧠