How rikhuijzer/fx works
1. Overall shape
- This is a Rust workspace with three crates: fx (the main server binary), fx-auth (authentication helpers), and fx-rss (RSS-related support).
- The main app serves both the public site and the authenticated authoring/admin surface for a self-hosted microblog.
2. Runtime entry point
- fx/src/main.rs starts the server; fx/src/lib.rs centralizes configuration and shared wiring.
- Environment-driven settings (FX_...) define the username/password, domain, storage paths, and optional trigger/backups behavior.
3. Request surface
- The app is split into public web pages, authenticated API endpoints, health checks, and static asset delivery.
- serve.rs, api.rs, and health.rs suggest distinct routing boundaries: browser UI, programmatic control, and container/liveness checks.
4. Content publishing pipeline
- Post content is authored in Markdown and rendered server-side.
- md.rs and html.rs handle the transform from stored post text into HTML, while the bundled static JS/CSS (style.css, script.js, katex.js, nodefer.js) provide client-side polish such as math and syntax-related behavior.
5. Data and persistence layer
- data.rs is the main persistence boundary; the README indicates a SQLite-backed site with plain-text file backup/export support.
- files.rs handles uploaded assets and image/file embedding, which are separate from the post text itself.
6. Search and discovery
- search.rs provides built-in lookup over the site’s content, matching the README’s “find it back later” workflow.
- discovery.rs and blogroll.rs indicate feed discovery/following as a first-class feature rather than an external add-on.
7. RSS and syndication
- fx-rss and fx/src/blogroll.rs are the syndication side of the system.
- The app can both publish its own feed(s) and ingest external RSS feeds into the blogroll, so the data flow is bidirectional: local posts out, external feeds in.
8. Authentication and admin boundaries
- Sensitive actions such as posting, editing, settings changes, backups, and downloads are protected by bearer-token/password auth.
- fx-auth encapsulates that boundary so the rest of the server can treat authenticated requests separately from anonymous readers.
9. Settings and operational controls
- settings.rs manages editable site metadata, such as the “about” text exposed via the API.
- health.rs and the README’s check-health command show that the service is designed to be supervised by Docker or similar container tooling.
10. Automation and external integrations
- trigger.rs supports notifying an external GitHub or Forgejo workflow when the site changes, which is how backup automation is wired.
- The README’s backup flow also exposes a downloadable archive endpoint, so the system can be exported as plain text plus assets and then committed elsewhere.
11. Testing and CI
- fx/tests/* contains integration coverage for the API and end-to-end behavior, showing that the boundaries are tested as a running service.
- GitHub Actions workflows (ci.yml, audit.yml) handle build verification and dependency/security auditing.
12. Key architectural boundary for a diagram
- The core diagram should show: browser/API clients → authenticated web server → persistence layer (SQLite + files) → optional external feed sources and trigger targets.
- Public reading, private writing, feed ingestion, search, and backup/export are the main flows to distinguish.
Main entry points: api.rs Admin API · lib.rs App core · serve.rs Public site · data.rs Site data
Components 17
Workspace
Rust workspace with app and support crates
- RSS crate · Shared RSS parsing and publishing support
fx-rss/src/lib.rs
Server
Main web service runtime and request boundaries
- Server bin · Starts the application server
fx/src/main.rs - App core · Centralizes configuration and shared server wiring
fx/src/lib.rs - Public site · Anonymous browser-facing pages and static delivery
fx/src/serve.rs - Admin API · Programmatic control surface for posting and management
fx/src/api.rs - Health check · Liveness and supervision checks
fx/src/health.rs - Auth helper · Bearer-token and password authentication support
fx-auth/src/lib.rs - Static assets · Bundled CSS and JavaScript for the site
fx/src/static/style.css
Content
Publishing, storage, and discovery subsystems
- Site data · Main storage layer for posts, settings, and exports
fx/src/data.rs - Asset files · Uploaded assets and embedded file handling
fx/src/files.rs - Markdown · Parses authored post text
fx/src/md.rs - HTML render · Converts stored content into HTML output
fx/src/html.rs - Search · Finds content later across the site
fx/src/search.rs - Settings · Editable site metadata such as about text
fx/src/settings.rs - Blogroll · Tracks followed feeds and syndicated entries
fx/src/blogroll.rs - Discovery · Discovers external feeds and sources
fx/src/discovery.rs - Change trigger · Notifies external GitHub or Forgejo workflows
fx/src/trigger.rs
Connections 19
- Server bin → App core: boots · Binary starts the shared application wiring
- App core → Public site: serves · Routes public reading pages
- App core → Admin API: exposes · Routes authenticated admin operations
- App core → Health check: checks · Exposes container and liveness probes
- Admin API → Auth helper: protects · Sensitive operations require authentication
- Public site → Static assets: loads · Serves bundled client-side assets
- Admin API → Site data: writes · Persists posts, settings, backups, and exports
- Public site → Site data: reads · Reads stored content for public pages
- Site data → Asset files: stores · Keeps uploaded assets separate from post text
- Site data → Markdown: parses · Uses Markdown as the authoring format
- Markdown → HTML render: renders · Transforms stored markup into HTML output
- Public site → HTML render: delivers · Serves rendered content to browsers
- Admin API → Search: queries · Supports built-in lookup over site content
- Admin API → Settings: updates · Edits site metadata through the admin surface
- Blogroll → Discovery: finds · Uses discovery to locate external feeds
- Blogroll → RSS crate: parses · Shares RSS handling with the support crate
- Admin API → Blogroll: syncs · Manages followed feeds and syndication state
- Change trigger → Admin API: hooks from · Fires on site changes for external automation
- RSS crate → Blogroll: feeds · Supports publishing and ingesting syndication data