Files

Sven 5e50d7aceb docs: add CLAUDE.md and memory files for AP threading context

CLAUDE.md covers patch authoring rules, post-type discovery, the two
reply compose paths, ap_timeline insertion timing, fork dependencies,
and common debugging entry points.

memory/ contains three files:
- project_activitypub.md — data flows, syndicator config, all AP patches
- project_architecture.md — FreeBSD jails, MongoDB collections, actor URLs
- feedback_patches.md — patch pattern, known fragile points, threading gotchas

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-30 08:30:32 +02:00

2.4 KiB

Raw Blame History

Server Architecture

Infrastructure

FreeBSD jails — Indiekit runs in an isolated jail
nginx — reverse proxy; must forward Host: blog.giersig.eu and X-Forwarded-Proto: https for Fedify to construct correct canonical URLs (see patch-ap-federation-bridge-base-url)
MongoDB — 10.100.0.20:27017, database indiekit, auth source admin
Redis — optional; URL via REDIS_URL env var; used for AP activity queue

Publication URLs

publicationBaseUrl = https://blog.giersig.eu (from PUBLICATION_URL env or hardcoded default)
applicationBaseUrl = same (from INDIEKIT_URL env)
GitHub repo: svemagie/blog, branch main

Internal Fetch

Several patches rewrite outbound HTTP fetches to use internal jail addresses instead of going through the public internet / nginx:

patch-micropub-fetch-internal-url — Micropub post creation fetches
patch-bluesky-syndicator-internal-url — Bluesky syndicator
_toInternalUrl() helper in microsub/activitypub controllers

Collections (MongoDB)

Collection	Contents
`posts`	Micropub post data (path + properties)
`ap_timeline`	Incoming + outgoing AP posts; key: `uid`
`ap_notifications`	Mentions, replies, likes, boosts received
`ap_followers`	Follower actor URLs
`ap_following`	Following actor URLs
`ap_activities`	Activity log (outbound + inbound)
`ap_profile`	Own actor profile (name, icon, url)
`ap_interactions`	Likes and boosts performed by own account

ActivityPub Actor

Handle: activityPubHandle from AP_HANDLE env → GITHUB_USERNAME (svemagie) → hostname prefix
Full handle: @svemagie@blog.giersig.eu
Actor URL: https://blog.giersig.eu/activitypub/actor
AP objects served at: https://blog.giersig.eu/activitypub/objects/note/{+id}
- Own reply posts: /activitypub/objects/note/replies/{slug}

Patch Infrastructure

Patches live in scripts/patch-*.mjs. Each script:

Checks if already applied (MARKER string)
Looks for OLD_SNIPPET in node_modules target file
Replaces with NEW_SNIPPET if found
Reports result to stdout

Both postinstall and serve scripts in package.json run all patches in order. Some patches (e.g. patch-microsub-reader-ap-dispatch) only appear in serve, not postinstall. New AP patches are appended at the end of the AP patch chain (after patch-ap-federation-bridge-base-url).

2.4 KiB Raw Blame History