# post4.fun Backend API Documentation

> Complete backend specification for post4.fun — an imageboard/forum/news aggregator hybrid. Stack: Cloudflare Workers + Hono, D1 (SQLite) + Drizzle ORM, R2, Queues, KV, Lucia Auth, Nuxt 4 frontend.

## Purpose

This site documents every API domain, data model, business rule, error code, and scheduled task for the post4.fun platform. Each document is self-contained and versioned independently. All documents are available as raw markdown at /docs/<filename>.md.

## Documents

- [Project Index](/docs/00-index.md): Architecture rules, global conventions, build order, tech stack overview.
- [Auth & Security](/docs/01-auth-security.md): Registration, login (3-layer rate limiting), sessions (Lucia), ban redirect middleware, can() permission helper.
- [Users & Profiles](/docs/02-users-profiles.md): User model, settings, notifications, follows, blocks, fan/hater opinions, political leaning, cosmetics, username changes, account deletion.
- [Boards Core](/docs/03-boards-core.md): Board creation, prefix system (/b/ /n/ /p/ /g/ /u/ /a/ /z/), access modes, post filters, moderator levels and permissions, board standing, lifecycle states, events, the /z/ admin prefix.
- [Content: Posts, Replies, Votes & Scoring](/docs/04-content-posts-replies.md): 7 post types, reply nesting, content state machine, vote system, awards, boosts, polls, drafts, scoring algorithms (hot/trending/controversial/top), self-delete penalty.
- [Governance](/docs/05-governance.md): Vote of No Confidence (VoNC), board elections, board inquiries with summons and verdicts, moderation actions, ban appeals.
- [Economy](/docs/06-economy.md): Coins (internal), credits (real money, x402 only), coin gifting, dual-ledger treasury, prize pools, awards, membership tiers, mod credit pots, withdrawals.
- [Ads Platform](/docs/07-ads-platform.md): Ad submission, escrow, review, round-robin display, impression/click tracking, auto-reject, two slot types (user_slot, board_slot).
- [Media & Storage](/docs/08-media-storage.md): Upload pipeline, R2 bucket structure, media object model, link embeds (async OG fetch), unlockable board packs, video thumbnails, orphan cleanup.
- [Feeds, Search & Discovery](/docs/09-feeds-search-discovery.md): Feed types (homepage, member, board, discovery, profile), sort modes, FTS5 search, board recommendations, leaderboards, direct messages, pagination rules, SEO.
- [Admin Platform](/docs/10-admin-platform.md): Full admin_settings key reference, site_config, user management, site roles, board categories, membership tiers, treasury allocation, badge admin, /z/ board management.
- [Scheduled Tasks](/docs/11-scheduled-tasks.md): All cron jobs and async queue consumers with schedules, business logic, and edge cases.
- [Badges & Roles](/docs/12-badges-roles.md): Role badges (site and board level), post status badges, user status badges, user achievement badges with tier system.

## Key Architecture Decisions

- All timestamps are Unix epoch integers (seconds). Never ISO strings.
- All multi-statement DB writes use D1 batch(). No sequential writes.
- Soft deletes everywhere. Hard deletes only via explicit data retention policies.
- R2 keys never exposed in API responses. All media served via /api/v1/media/<uuid>.
- Treasury uses FLOOR() rounding. Remainder always goes to general_balance.
- can() is a pure function. Never queries the database. Middleware pre-loads all permission data.
- Board identity (slug, name, prefix) is immutable after creation.
- author_role_snapshot on posts/replies is permanent. Never updated.
- All configurable limits live in admin_settings. Nothing hardcoded.

## Raw Document Access

All 13 specification documents are accessible as plain text markdown:

/docs/00-index.md
/docs/01-auth-security.md
/docs/02-users-profiles.md
/docs/03-boards-core.md
/docs/04-content-posts-replies.md
/docs/05-governance.md
/docs/06-economy.md
/docs/07-ads-platform.md
/docs/08-media-storage.md
/docs/09-feeds-search-discovery.md
/docs/10-admin-platform.md
/docs/11-scheduled-tasks.md
/docs/12-badges-roles.md