====== Architecture Notes ======

**Source**

This is a fork of aaronpk/webmention.io, hosted at git.folk.zone. The working copy is in server/webmention/ in the homelab repo.

**Stack**

- Ruby 2.7 (Sinatra app)
- MariaDB 11 (database)
- Redis 7 (caching)
- Rackup (application server, port 9019)

**Key dependencies**

- mysql2 gem: Database driver
- libxml-ruby: XML/HTML parsing
- indieauth_server: Self-serve sign-in (defaults to indieauth.com)
- xray_server: Microformats parsing (defaults to xray.p3k.io)

**Important notes from upstream**

The Ruby version is pinned to 2.7 because the bundler version (1.16.1) uses the untaint method that was removed in Ruby 3.0. Do not upgrade Ruby without addressing this.

The libxml-ruby gem is a known pain point. It can fail compiling against newer libxml2 versions. The gem version in Gemfile.lock must match what is available in the base image.

**External dependencies**

The service relies on two external services:

1. indieauth.com for self-serve sign-in (could be deprecated in favor of indielogin.com)
2. xray.p3k.io for microformats parsing of source pages

These are third-party hosted services that the self-hosted webmention server depends on. This means even though the service is self-hosted, it still relies on external infrastructure for some functionality.

**Avatar storage**

The upstream codebase includes ca3db configuration for AWS-backed avatar storage. This has been disabled in the folk.zone deployment. Avatar storage is not currently implemented. This would need either local disk storage patching or AWS credentials to enable.


===== See Also =====

  * [[indieweb:start|Return to indieweb]]