# rikhuijzer/fx architecture

> Architecture diagram of the GitHub repository rikhuijzer/fx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rikhuijzer/fx
- Repository: https://github.com/rikhuijzer/fx

## Overview

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: [`fx/src/api.rs`](https://github.com/rikhuijzer/fx/blob/main/fx/src/api.rs) (Admin API), [`fx/src/lib.rs`](https://github.com/rikhuijzer/fx/blob/main/fx/src/lib.rs) (App core), [`fx/src/serve.rs`](https://github.com/rikhuijzer/fx/blob/main/fx/src/serve.rs) (Public site), [`fx/src/data.rs`](https://github.com/rikhuijzer/fx/blob/main/fx/src/data.rs) (Site data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_rss["RSS crate<br/>syndication library<br/>[lib.rs]"]
end

subgraph group_server["Server"]
  node_fx_main["Server bin<br/>binary entrypoint<br/>[main.rs]"]
  node_fx_lib["App core<br/>wiring and config<br/>[lib.rs]"]
  node_serve["Public site<br/>web routes<br/>[serve.rs]"]
  node_api["Admin API<br/>authenticated routes<br/>[api.rs]"]
  node_health["Health check<br/>ops endpoint<br/>[health.rs]"]
  node_auth["Auth helper<br/>auth boundary<br/>[lib.rs]"]
  node_static_assets["Static assets<br/>client assets<br/>[style.css]"]
end

subgraph group_content["Content"]
  node_data[("Site data<br/>persistence boundary<br/>[data.rs]")]
  node_files["Asset files<br/>upload storage<br/>[files.rs]"]
  node_md["Markdown<br/>content transform<br/>[md.rs]"]
  node_html["HTML render<br/>rendering<br/>[html.rs]"]
  node_search["Search<br/>content lookup<br/>[search.rs]"]
  node_settings["Settings<br/>site metadata<br/>[settings.rs]"]
  node_blogroll["Blogroll<br/>feed aggregation<br/>[blogroll.rs]"]
  node_discovery["Discovery<br/>[discovery.rs]"]
  node_trigger["Change trigger<br/>external hook<br/>[trigger.rs]"]
end

node_fx_main -->|"boots"| node_fx_lib
node_fx_lib -->|"serves"| node_serve
node_fx_lib -->|"exposes"| node_api
node_fx_lib -->|"checks"| node_health
node_api -->|"protects"| node_auth
node_serve -->|"loads"| node_static_assets
node_api -->|"writes"| node_data
node_serve -->|"reads"| node_data
node_data -->|"stores"| node_files
node_data -->|"parses"| node_md
node_md -->|"renders"| node_html
node_serve -->|"delivers"| node_html
node_api -->|"queries"| node_search
node_api -->|"updates"| node_settings
node_blogroll -->|"finds"| node_discovery
node_blogroll -->|"parses"| node_rss
node_api -->|"syncs"| node_blogroll
node_trigger -.->|"hooks from"| node_api
node_rss -.->|"feeds"| node_blogroll

click node_fx_main "https://github.com/rikhuijzer/fx/blob/main/fx/src/main.rs"
click node_fx_lib "https://github.com/rikhuijzer/fx/blob/main/fx/src/lib.rs"
click node_serve "https://github.com/rikhuijzer/fx/blob/main/fx/src/serve.rs"
click node_api "https://github.com/rikhuijzer/fx/blob/main/fx/src/api.rs"
click node_health "https://github.com/rikhuijzer/fx/blob/main/fx/src/health.rs"
click node_auth "https://github.com/rikhuijzer/fx/blob/main/fx-auth/src/lib.rs"
click node_data "https://github.com/rikhuijzer/fx/blob/main/fx/src/data.rs"
click node_files "https://github.com/rikhuijzer/fx/blob/main/fx/src/files.rs"
click node_md "https://github.com/rikhuijzer/fx/blob/main/fx/src/md.rs"
click node_html "https://github.com/rikhuijzer/fx/blob/main/fx/src/html.rs"
click node_search "https://github.com/rikhuijzer/fx/blob/main/fx/src/search.rs"
click node_settings "https://github.com/rikhuijzer/fx/blob/main/fx/src/settings.rs"
click node_blogroll "https://github.com/rikhuijzer/fx/blob/main/fx/src/blogroll.rs"
click node_discovery "https://github.com/rikhuijzer/fx/blob/main/fx/src/discovery.rs"
click node_trigger "https://github.com/rikhuijzer/fx/blob/main/fx/src/trigger.rs"
click node_rss "https://github.com/rikhuijzer/fx/blob/main/fx-rss/src/lib.rs"
click node_static_assets "https://github.com/rikhuijzer/fx/blob/main/fx/src/static/style.css"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rss toneBlue
class node_fx_main,node_fx_lib,node_serve,node_api,node_health,node_auth,node_static_assets toneAmber
class node_data,node_files,node_md,node_html,node_search,node_settings,node_blogroll,node_discovery,node_trigger toneMint
```

## Components

### Workspace

Rust workspace with app and support crates

- [RSS crate](https://github.com/rikhuijzer/fx/blob/main/fx-rss/src/lib.rs): syndication library · Shared RSS parsing and publishing support · `fx-rss/src/lib.rs`

### Server

Main web service runtime and request boundaries

- [Server bin](https://github.com/rikhuijzer/fx/blob/main/fx/src/main.rs): binary entrypoint · Starts the application server · `fx/src/main.rs`
- [App core](https://github.com/rikhuijzer/fx/blob/main/fx/src/lib.rs): wiring and config · Centralizes configuration and shared server wiring · `fx/src/lib.rs`
- [Public site](https://github.com/rikhuijzer/fx/blob/main/fx/src/serve.rs): web routes · Anonymous browser-facing pages and static delivery · `fx/src/serve.rs`
- [Admin API](https://github.com/rikhuijzer/fx/blob/main/fx/src/api.rs): authenticated routes · Programmatic control surface for posting and management · `fx/src/api.rs`
- [Health check](https://github.com/rikhuijzer/fx/blob/main/fx/src/health.rs): ops endpoint · Liveness and supervision checks · `fx/src/health.rs`
- [Auth helper](https://github.com/rikhuijzer/fx/blob/main/fx-auth/src/lib.rs): auth boundary · Bearer-token and password authentication support · `fx-auth/src/lib.rs`
- [Static assets](https://github.com/rikhuijzer/fx/blob/main/fx/src/static/style.css): client assets · Bundled CSS and JavaScript for the site · `fx/src/static/style.css`

### Content

Publishing, storage, and discovery subsystems

- [Site data](https://github.com/rikhuijzer/fx/blob/main/fx/src/data.rs): persistence boundary · Main storage layer for posts, settings, and exports · `fx/src/data.rs`
- [Asset files](https://github.com/rikhuijzer/fx/blob/main/fx/src/files.rs): upload storage · Uploaded assets and embedded file handling · `fx/src/files.rs`
- [Markdown](https://github.com/rikhuijzer/fx/blob/main/fx/src/md.rs): content transform · Parses authored post text · `fx/src/md.rs`
- [HTML render](https://github.com/rikhuijzer/fx/blob/main/fx/src/html.rs): rendering · Converts stored content into HTML output · `fx/src/html.rs`
- [Search](https://github.com/rikhuijzer/fx/blob/main/fx/src/search.rs): content lookup · Finds content later across the site · `fx/src/search.rs`
- [Settings](https://github.com/rikhuijzer/fx/blob/main/fx/src/settings.rs): site metadata · Editable site metadata such as about text · `fx/src/settings.rs`
- [Blogroll](https://github.com/rikhuijzer/fx/blob/main/fx/src/blogroll.rs): feed aggregation · Tracks followed feeds and syndicated entries · `fx/src/blogroll.rs`
- [Discovery](https://github.com/rikhuijzer/fx/blob/main/fx/src/discovery.rs): feed discovery · Discovers external feeds and sources · `fx/src/discovery.rs`
- [Change trigger](https://github.com/rikhuijzer/fx/blob/main/fx/src/trigger.rs): external hook · Notifies external GitHub or Forgejo workflows · `fx/src/trigger.rs`

## Connections

- 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
