Roller Hub

Part of the Simple Agility stack. Roller is the stack's customer communication component: the authoritative sovereign platform where the business engages directly with customers, subscribers, and collectors (SA-7).

Roller is an independent fork of Apache Roller 6.2 modernized for modern containerized operations: Spring Boot, Java 25, PostgreSQL, Markdown-only authoring, and native agent automation via API tokens and Model Context Protocol (/api/mcp).

flowchart TD
    subgraph Sourcing_and_Intake["Stockroom Operations"]
        SR[Stockroom Intake & WMS]
        FLAG["Operator Flag:<br/>'Feature on Blog'"]
        SR --> FLAG
    end

    subgraph Agent_Publisher["Agent Publishing Pipeline"]
        BA["Roller Publishing Agent<br/>(Blogger-Agent Refactor)"]
        ASSETS[("blog-assets CDN<br/>(GitHub Media Storage)")]
        FLAG -->|Item Payload: Photos, Notes, Link| BA
        BA -->|Embed Featured Media| ASSETS
    end

    subgraph Roller_Platform["Roller Production Fleet (docker1)"]
        MCP["Roller MCP Server<br/>(/api/mcp)"]
        API["Automation API<br/>(/api/v1/entries)"]
        WLOG["Reselling Weblog<br/>(Estate Finds & Spotlights)"]
        LM["listmonk Newsletter<br/>(/newsletter/subscribe)"]
        UMAMI["Umami Analytics<br/>(Privacy-first telemetry)"]
        
        BA -->|Bearer Token: Role POST| MCP
        BA -->|Direct Draft Submission| API
        MCP --> WLOG
        API --> WLOG
        WLOG --> LM
        WLOG --> UMAMI
    end

    subgraph Customer_Touchpoints["Customer Outbound"]
        READERS["Public Readers & Collectors<br/>(Organic Search & Social)"]
        SUBSCRIBERS["Email Subscribers<br/>(Weekly Curated Roundups)"]
        EBAY["Active eBay Listings<br/>(Direct Conversion)"]
        
        WLOG --> READERS
        LM --> SUBSCRIBERS
        WLOG -.->|Direct Purchase Link| EBAY
    end

1. The Customer Communication Surface

Three interconnected services provide sovereign customer outreach without third-party platform lock-in:

1. Weblog Engine (Roller) — Powers multi-weblog publishing, entry drafts, scheduled posts, category indexing, and rich Atom feeds. For the reselling business, Roller hosts the primary showcase weblog.
2. Newsletter Engine (listmonk) — Manages opt-in subscriber lists, automated email campaigns, and digest broadcasts, fed directly from subscription forms on the blog (/newsletter/subscribe).
3. Analytics Engine (Umami) — Privacy-first, cookie-free reader telemetry served from the blog's own domain to measure article retention and campaign conversion without ad-blocker degradation.

Production is strictly containerized: since the 2026-10-18 cutover, host docker1 runs docker-compose.prod.yml (Caddy on port 8084) behind Cloudflare ingress (HostDocker1, HomeLabFleetAndIngress). The docker2 stack is stopped.

2. Reseller Customer Flywheel & Inventory Spotlights

Per architectural decision SA-8, inventory items transition from warehouse intake to public customer stories through an operator-assisted pipeline:

1. Intake & Triage Identification: When an intake item is cataloged in Stockroom (e.g. rare antiquarian books, vintage audio, estate collectibles), the operator flags the item as Feature on Blog.
2. Automated Content Assembly: The publishing agent (blogger-agent refactored as the native Roller publisher, SA-INIT-01) extracts the item's catalog facts, physical dimensions, condition notes, upright photographs, and generated eBay listing permalink.
3. Draft Staging: The agent crafts an engaging historical or collector spotlight and stages the draft post on the reselling weblog using Roller's /api/mcp or REST API.
4. Editorial Review: The operator reviews the staged draft in Roller, fine-tunes narrative tone if desired, and publishes or schedules the entry.
5. Cross-Channel Synergies & Attribution: Published entries drive organic search traffic, inform newsletter subscribers, and link directly to active eBay listings, store coded coupons, or direct inquiry forms. Traffic-to-sale conversion is tracked and attributed per the SimpleAgilityAttributionRFC framework (SA-12).

3. Agent Integration & Native Automation

Roller v0.2.0 introduces first-class agent automation primitives:

• Scoped API Tokens: Tokens are generated with role-based boundaries (POST, EDIT_DRAFT, or ADMIN) and optionally restricted to a specific weblog handle.
• Model Context Protocol (/api/mcp): AI coding and publishing agents (such as Antigravity, Claude Code, or autonomous schedulers) connect directly to Roller via MCP. See RollerMcp for minting commands and protocol capabilities.
• Media Management: Featured images and inline photographs are pushed to the blog-assets CDN repository, ensuring fast, cached image delivery without burdening the application container.
• Agent Editing (v0.4.0): Agents revise live posts in place - entries get by anchor, find/replace edits guarded by contentHash/expectedContentHash (Wikantik's update_page scheme), fields for small responses, revisions with notes, diffs and restore, and per-entry SEO audits. See RollerMcp.

4. Stack Standards & Telemetry Roadmap

Roller conforms to Simple Agility fleet standards (SimpleAgilityDecisionLog, SimpleAgilityTelemetryContract):

• Deployment Identity: Named service_instance="roller-prod" on host docker1 (SA-5).
• Logging Standard: Emitting Elastic Common Schema (ECS) JSON on stdout through Log4j2 JsonTemplateLayout with service.name=roller and trace.id propagation (SA-6, tracked on SimpleAgilityTelemetryAdoption as Phase 1 adoption items R1–R5 and sequenced on SimpleAgilityRoadmap).
• Metrics Endpoint: Exposing Spring Boot /actuator/prometheus for scraping by jakemon's host Alloy agent.

5. Navigation & Runbooks

See Also

• SimpleAgilityStackHub — Ecosystem topology, ownership principles, and shared data backbone.
• ResellingHub — Business rules, listing style guides, and inventory triage policies.
• SimpleAgilityDecisionLog — Binding architectural decisions (SA-7 customer communication, SA-8 spotlight flow).
• RollerBlogPlatform — Technical architecture of the modern Spring Boot / Java 25 Roller fork.

Additional Cluster Reference Pages

• HostDocker2 — Host: docker2 — Application Host (CrafterCMS)
• RollerTelemetryHandoffSpec — Roller Telemetry Handoff Specification: ECS JSON Logging and Prometheus Metrics
• RollerW3tPlugins — Roller w3t Feature Worktrees (Shortcodes, Leaflet, JSON-LD)