# 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 🧠_