Documentation #

These are implementation notes for the Coves AppView. Each doc holds what the code cannot tell you: invariants, the reasons behind decisions, contracts between components, and procedures. If the code and a doc disagree, the code is right and the doc needs fixing.

Start with the project README and CONTRIBUTING.md.

Working on the code #

• ARCHITECTURE.md: package layering, server startup, config loading, migrations.
• LOCAL_DEVELOPMENT.md: the dev stack, ports, and local PLC/PDS identity.
• TEST_ARCHITECTURE.md: test tiers, the testkit, and what make ci enforces.
• LEXICON_PUBLISHING.md: publishing social.coves.* schemas. A test checks this runbook.
• Lexicon schemas and schema fixtures.

Subsystems #

• POSTS.md: author-owned posts, community admission, visibility, comments, and the legacy post cutover.
• FEEDS.md: timeline, Discover, community feeds, search, and Hot ranking.
• COMMUNITIES.md: community accounts, handles, and credentials.
• BRIDGED_IDENTITY.md: identity-event handle refresh, the per-DID lock, the handle sweep, origin fields, and name@host lookup for bridged accounts.
• AGGREGATORS.md: how aggregators register, get authorized, and post.
• MODERATION.md: server-admin removal, NSFW labels, and the modlog.
• NOTIFICATIONS.md: in-app notifications, upvote groups, seen state, and retention.
• MEDIA.md: the image proxy, CSAM scanning, caching, and purges.

Security #

• SECURITY_MODEL.md: auth, write-path, and firehose trust rules.
• SSRF_SECURITY.md: rules for outbound requests.
• CREDENTIAL_ENCRYPTION.md: how stored credentials are sealed, and key recovery.
• SECURITY.md: reporting a vulnerability.

Operations #

• PRODUCTION_DEPLOY.md: Compose projects, Caddy routing, and the frontend deploy.
• PRODUCTION_BACKUPS.md: backup timers and restore.
• Aggregators: Kagi News, Reddit Highlights, Bluesky Topics, account and API-key setup.

Plans #

plans/ holds designs for work that is not built yet. Delete a plan when it ships, after moving its lasting rules into the subsystem doc.

• IMAGE_UPLOADS.md: user image uploads in posts and comments.
• NOTIFICATIONS_CLIENTS.md: web and mobile notification clients.
• MODERATION_LABELS.md: federated moderation through signed labels.

Deferred bugs and feature requests go in the central backlog, not in this folder.