GKaszewski/k-ap
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity

wiki: add What k-ap Does page

Gabriel Kaszewski
2026-05-29 02:08:34 +00:00
parent 7a5c7a0c14
commit f6bda6d430
1 changed files with 63 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
What k-ap Does %28and Doesn%27t Do%29.-.md Normal file

@@ -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.
---