diff --git a/What k-ap Does %28and Doesn%27t Do%29.-.md b/What k-ap Does %28and Doesn%27t Do%29.-.md new file mode 100644 index 0000000..e698eae --- /dev/null +++ b/What k-ap Does %28and Doesn%27t Do%29.-.md @@ -0,0 +1,63 @@ +# What k-ap Does (and Doesn't Do) + +k-ap is a **protocol layer**, not a social platform. It handles the ActivityPub plumbing so you can focus on your domain — content, users, UI, business logic. + +--- + +## What k-ap owns + +| Responsibility | Detail | +|----------------|--------| +| HTTP signature verification | All inbound inbox requests are verified before any handler is called | +| Inbox routing and dispatch | `POST /inbox` and `POST /users/{id}/inbox` — dedup, activity dispatch | +| Outbox pagination | `GET /users/{id}/outbox` — cursor-based `OrderedCollection` | +| Featured (pinned posts) collection | `GET /users/{id}/featured` — `OrderedCollection` from your `ApContentReader` | +| WebFinger | `GET /.well-known/webfinger` — JRD with aliases | +| NodeInfo | `GET /.well-known/nodeinfo` redirect + `GET /nodeinfo/2.0` | +| HTTP signature creation | Signs all outbound delivery requests | +| Follower graph management | Follow, Accept, Reject, Undo(Follow), Move migration | +| Activity deduplication | Every inbound activity checked via `ActivityRepository` before processing | +| Broadcast delivery | Resolves follower inboxes, deduplicates, signs, delivers | +| Remote actor cache | Fetches and caches remote actor JSON via `ActorRepository` | + +## What you own + +| Responsibility | Detail | +|----------------|--------| +| Content types | What goes inside Create/Update — Note, Article, Video, etc. | +| User storage | Creating, finding, and persisting local users | +| Database layer | All seven traits are your data access layer | +| Actor/followers/following HTTP routes | Need content negotiation — k-ap provides helpers, you own the route | +| UI and application logic | Feed generation, notifications, search, etc. | +| Blocklist population | k-ap checks the blocklist; you populate it | +| Job queue | Optional — k-ap spawns in-process by default; you wire it up for workers | + +--- + +## The trait boundary + +k-ap calls into your code through seven focused traits. You implement them against whatever database or storage layer you use. k-ap never touches storage directly. + +``` +k-ap library + │ + ├── calls ActivityRepository (you implement) + ├── calls FollowRepository (you implement) + ├── calls ActorRepository (you implement) + ├── calls BlocklistRepository (you implement) + ├── calls ApUserRepository (you implement) + ├── calls ApContentReader (you implement) + └── calls ApObjectHandler (you implement) +``` + +Each trait has a focused, narrow scope. See [The Seven Traits](The-Seven-Traits) for full detail. + +--- + +## Why not domain-specific? + +ActivityPub federates activities, not content types. A `Create(Note)` from Mastodon and a `Create(Article)` from a blog platform have the same activity structure — only the wrapped object differs. k-ap handles the activity layer and lets you decide what your objects look like. + +This means k-ap works equally well for microblogging, movie logging, book tracking, music sharing, or any other domain. + +--- \ No newline at end of file