TL;DR: Access Keys for easier API integration, fully integrated and secure MCP server on the way soon!

It took me a while to explore the latest trend. I usually sit back a bit when something new makes the rounds on X, Hacker News and all the other usual places.

To be fair, this may have been my downfall, I attempted to build a GPT-3 powered SaaS with a friend way back in 2020, ultimately we lost interest and I collosally failed to predict the explosion of GPTs in the coming years.

That being said, there was an attempt a few months ago to experiment with MCP. Back then, there were very few actual tools to work with MCP so I've revisited it this week and I'm quite excited!

Guess we're doin AI now?

Not quite. Storyden always aims to support the most minimal production-ready deployment possible. You can run it right now on your server with zero external dependencies. No OpenAI API keys, no PostgreSQL, no Redis. Everything is baked in, sane defaults, get going and enhance as you wish:

docker run -p 8000:8000 ghcr.io/southclaws/storyden

If you're not interested in AI at all, no worries! It'll never grace your Storyden deployment unless you ask it to. (and provide an OpenAI API key of course...)

The Bearer of Good News

In short: Storyden finally gets Authorization: Bearer support! This has been on the list since almost the beginning. Until now, the only way to talk to the API was with a Cookie header (which was recently reworked to be a much more secure stateful token, rather than a JWT-esque stateless token)

Access Keys

These work like most other SaaS apps. You can create a "Personal access key" which gives you a token. It can be revoked, expire and all that good stuff.

Not every member of a Storyden instance may do this, administrators must first issue a role with the permission USE_PERSONAL_ACCESS_KEYS in order for a member to be able to issue keys for their account.

Access Keys are essentially just another authentication method for an account. This means they inherit all the roles and permissions of the owner.

Which may have you asking, how do I implement a principle of least privilege?

Bot Accounts

Since permissions are simply bound to an account, and access keys simply provide access on behalf of an account, then creating scoped access is as simple as just creating another account!

"Accounts" in Storyden are lightweight, not bound to an identity such as an email or phone number. It was a conscious decision to use the word "Account" and not "User" for this reason.

In a future version, members with sufficient permissions will be able to create bot accounts with access keys. This feature will power new agentic workflows such as:

• Automated content moderators
• Shared link indexing from community platforms such as Discord
• Organising bots for tidying up wiki pages

And pretty much anything you can think of by composing together MCP servers with your favourite agentic framework like Pydantic AI or workflow engine such as n8n.

Go forth and build!

This marks an exciting near-future for Storyden. Access keys provide a secure and easy way to build integrations.

Bot accounts prepare the platform for an agentic future.

What's next?

I'm not sure but I've heard it involves WebAssembly sandboxed plugins... 👀

Whether you’re building a recommendation engine, semantic search, or adding context-aware responses, you’ll need to treat raw content as more than just a string. This post explores how Storyden approaches this challenge, and why it does things the way it does.

Text Is Not Enough

A lot of content systems store HTML in a database. WordPress does this, and so does Storyden. HTML is portable, standardised and very well understood. However, on its journey from fingers to file, Storyden does a bunch of processing to better understand the actual content structure to do some useful stuff with it.

This "useful stuff" facilitates features like:

• Sanitise, because you can't trust the client, XSS is still a thing!
• Run semantic search (though I'm still skeptical of how useful this is...)
• Summarize content for previews, cards, <title>, opengraph, etc.
• Detect both external and internal links
• Generate embeddings for an LLM to use in Retrieval-Augmented Generation

Sanitisation: Safety first

Before anything else, raw input is passed through a sanitiser. This strips out unsafe tags or attributes, but still allows the Storyden-specific URI scheme, sdr: which are internal reference links between pages, posts, members and more (you can read more about that here!)

This approach lets members write, POST or paste rich content (even from suspicious sources) without worrying about <script> tags, malicious inline styles, onclick, etc.

Structure over noise

After sanitising, the content is parsed into a structured tree via Go's html package. This isn't used for rendering or changing the content, but it is useful for extracting things like:

• External links: external URLs so that Storyden can index them in the Link Aggregator
• Internal links, or "references": sdr: URIs (e.g. sdr://thread/xyz123)
• Media: image sources (and maybe videos one day? 👀)
• Plaintext: the raw text content, useful for LLM-based summarisation (another thing I’m skeptical about in terms of usefulness, tbh)
• Short Summary: a preview-friendly summary, capped at ~128 characters
• Chunks: pieces of text with loosely defined boundaries

Chunking

or: why you clicked this post in the first place probably.

One of the most important things the Content type does is chunking: breaking large blocks of text into smaller, semantically coherent units.

Why do this?

Firstly, large language models operate within context limits and when you want to run inference using a piece of content, it's not always desirable to put the entire piece of content into the context window. Sometimes this is useful, like when I finish this post I might paste the entire thing into a GPT to proof-read it. But for other use-cases it's not going to yield the best results.

Secondly, and probably more importantly, the coordinates you get from vector embeddings become less and less localised the larger the text is. This isn't always the case technically, if you write 10 paragraphs about how cats enjoy laying in the sun, it will probably localise fairly well to a specific region in vector space. But people don't write like that. Forum users and directory curators don't write like that. Human writing bounces around, starting in one place and ending somewhere else.

So because semantic meaning matters, chunking needs to be aware of a few requirements:

• Chunk boundaries cannot be mid-sentence
• Chunks must be small enough to represent a fairly self contained unit of meaning.
• However, leniency must be allowed for longer spans of text, because it's humans behind the keyboard and humans are creative!

How does it work

Storyden uses a hybrid approach to chunking, first breaking down high level then going per-paragraph to split further.

First, it walks the HTML tree for paragraph-style elements like <p>, <h2>, <blockquote>, etc. to get a list of root level blocks, think paragraphs, headings, code blocks, quotes, etc.

func (c Content) Split() []string {
	r := []html.Node{}

	// first, walk the tree for the top-most block-content nodes.
	var walk func(n *html.Node)
	walk = func(n *html.Node) {
		if n.Type == html.ElementNode {
			if /* omitted for brevity: n.DataAtom is a top-level block element */ {
				r = append(r, *n)
				return // return, as we don't want to recurse into the tree.
			}
		} else if n.Type == html.TextNode {
			r = append(r, *n)
		}

		for c := n.FirstChild; c != nil; c = c.NextSibling {
			walk(c)
		}
	}
	walk(c.html)

	chunks := chunksFromNodes(r, roughMaxSentenceSize)

	return chunks
}

Then, chunksFromNodes recursively splits them again down to a rough sentence-size boundary (roughMaxSentenceSize which is 350 characters, based on research of the English language*). Boundaries are currently English/Latin-based only*, using basic terminal-punctuation (periods, exclamation, question, etc.)

func chunksFromNodes(ns []html.Node, max int) []string {
	chunks := []string{}

	for _, n := range ns {
		t := textfromnode(&n)
		if len(t) > max {
			chunks = append(chunks, splitearly(t, max)...)
		} else {
			chunks = append(chunks, t)
		}
	}

	return chunks
}

The core paragraph-level splitting is done in splitearly, which is applied when the first-pass chunk is too long (true in most cases.)

Leniency is applied by doubling the boundary (700 characters) and walking down until a punctuation boundary is found, this allows for larger chunks if someone wrote a very long paragraph.

In a worst case scenario (no boundaries were found, maybe you're discussing very long chenical names?) the last found space is used, or failing that, the upper boundary at position 700.

func splitearly(in string, max int) []string {
	var chunks []string
	var split func(s string)
	split = func(s string) {
		if len(s) <= max {
			chunks = append(chunks, strings.TrimSpace(s))
			return
		}

		upper := min(len(s), max) - 1
		if upper == -1 {
			// reached end of input stream
			return
		}

		lower := upper / 2
		boundary := upper
		fallback := -1
	outer:
		for ; boundary > lower; boundary-- {
			c := s[boundary]
			switch c {
			// very rudimentary sentence boundaries (latin only at the moment)
			case '.', ';', '!', '?':
				break outer
			// worst case: no boundaries found, use the closest space
			case ' ':
				if fallback == -1 {
					fallback = boundary
				}
			}
		}

		if boundary <= lower {
			if fallback > -1 {
				// worst case: no sent boundaries, split at fallback position.
				boundary = fallback
			} else {
				// worst case: no fallback either (the input string was a solid
				// block of text with no spaces or sentence boundaries.)
				boundary = upper
			}
		}

		left := strings.TrimSpace(s[:boundary])
		right := strings.TrimSpace(s[boundary+1:])
		chunks = append(chunks, left)

		if len(right) > 0 {
			split(right)
		}
	}
	split(in)

	return chunks
}

The result is a list of pretty well-formed, meaningful text chunks which are now close to perfect for vector embedding. For example, this very post that you're reading, when run through the chunking algorithm, yields these first 5 chunks:

Every piece of written content inside Storyden, be it a post, a page, a submission or a reply, flows through a single system: the Content type. It’s not just a blob of HTML. It’s a full-featured data structure that’s aware of links, references, summaries and chunks

And all of this is essential for ergonomic APIs as well as helping language models work well with the data.

Whether you’re building a recommendation engine, semantic search, or adding context-aware responses, you’ll need to treat raw content as more than just a string. This post explores how Storyden approaches this challenge, and why it does things the way it does.

(Note, this heading is probably not a useful extraction of semantic value now that I think about it... to resolve this, I'd remove headings from that initial rood element gathering step at the start.)

Text Is Not Enough

A lot of content systems store HTML in a database. WordPress does this, and so does Storyden. HTML is portable, standardised and very well understood. However, on its journey from fingers to file, Storyden does a bunch of processing to better understand the actual content structure to do some useful stuff with it.

This means when you ask a question or use other LLM-powered features on Storyden, it can search the coordinates of each paragraph of each post or page, rather than the much more vague and "averaged" embedding of entire documents.

Designed for RAG, but useful elsewhere

A lot of modern RAG systems use chunking, with various different algorithms (though, at the time of building this in 2023/2024 there were not a lot of resources available on the topic discussing different approaches, especially for rich HTML trees.)

And while chunking is primarily done for semantic search (almost useless) and Retrieval-Augmented Generation (boring), it has knock-on benefits across Storyden:

• Summary descriptions: for OpenGraph cards and <title> tags.
• Recommendations: Embedding at a more granular level allows more sophisticated recommendation algorithms.
• Filtering: when building context for a prompt, you can more easily discard irrelevant chunks using metadata.

What about internationalisation?

In short, it's hard. I'm an NLP nerd and I wrote my thesis on it while working for a company doing lots of NLP analysis of Ministry of Defence documents, it was hard back then with just English and we used tools like SpaCy. Language models do make some things easier but there still exists the fundamental problem of data pre-processing. Which is key to training models, and sometimes even necessary when using models like GPTs.

Much of NLP at that time was very procedural, using dictionaries and lookup tables of word types, stopwords, stemming, sentence-splitting, etc. I'm not sure how the industry has changed now but at that time, it was very manual in terms of procedural code running over text. There aren't many tricks you can use with language, especially English. Languages are messy, a product of ever evolving cultures with new words, grammatical structures, cases, slang and other elements popping up all the time. What I've done here may work with some European languages but it definitely not work as well with Persian, Arabic, Korean, Urdu, etc.

The challenge isn't just in the boundary markers, sentence size and characters. It can go deeper, for example some languages don’t use spaces to separate words at all, even the concepts of “paragraph” and “sentence” aren’t universal. And then there are languages like German, somewhat fusional/agglutinated, where a single sentence can contain what feels like an entire essay thanks to compound nouns and nested clauses. Or fully agglutinated languages like Turkish.

A solution that's multi-language would probably need to be a lot more declarative and less procedural.

Tasty chocolate chunks

This whole system might seem like a lot of complexity but language models are no different to classic artificial intelligence or NLP: your success depends on the quality of the input data. Chunking in such a way that's somewhat semantically aware of the structure (not hard-cutting mid sentence, etc) yields better results in the (very informal and unscientific) benchmarks I've run.

It also turns out splitting HTML is quite complex due to the different element types, leniency of HTML itself, and also just because the Go html.Node type is hella awkward to work with (but very powerful!)

If you’ve got a forum, directory, wiki, or anything that revolves around lots of human-written content, and you want to add actual intelligence on top of it, this approach will get you far.

You can try this out right now:

docker run -p 8000:8000 ghcr.io/southclaws/storyden

Or check the getting started documentation. Note: in order to enable LLM features (they are aggressively opt-in, as it's not for everyone) you must enable the Semdex (semantic index) by:

• providing a vector database - for quick testing you can use Storyden's embedded vector database, Chromem (read more)
• providing a language model - for now, OpenAI is the only supported provider (read more)

If you're interested in checking out how it works, you can read the code and tests on GitHub.

I hope this article was helpful, spread the word if you enjoyed it!

MediaWiki has this concept of "info boxes" which display basic attributes about the topic. They are present on almost every medium to large Wikipedia page and often link out to broader category pages such as locations, years, genres, styles, people, companies, etc.

These are essentially relations, in a big graph. However, the way MediaWiki implements them is just another piece of content on the page. If I click "dreampunk" in the above infobox for British-American vaporwave duo, ２８１４ (to which much of the Storyden code was written) I land on the Wikipedia page for the dreampunk music genre, and on that page is a backlink to ２８１４ somewhere in the content.

Where this breaks down a bit is when I click the "ambient" link and land on the Wikipedia page for the ambient genre. There is no backlink to ２８１４. This is because those relationships are defined at the hypermedia layer. If I wanted to build a graph analysing the relationships between ２８１４ and their associated genres, similar acts, related people, etc. I would need to parse the content itself as the underlying relationships are not expressed in any other way.

Finding all the artists under "ambient" would not be possible solely from the "ambient" Wikipedia page; I would need to essentially scan every single Wikipedia page that exists and filter for those that have "ambient" in their "Genres" infobox.

Those of you who know relational database query planners would identify this as a "full table scan" as opposed to an index scan.

It's worth noting that this observation is not a problem for Wikipedia, its purpose is not to perform analytical processes on the knowledge graph, its purpose is to provide a free and open source of crowd-sourced and fact-checked information. One of the most important endeavours of our modern society.

For Storyden, we wanted to avoid having relationships buried in free text and instead make them first-class data citizens.

Entity-Attribute-Value

(not to be confused with Entity-Component System)

Storyden's goal is to make a community's collective knowledge organised, searchable and discoverable. Whether that's through discussion, curation or collection.

(the precursor to this was an indie fashion directory called Threadbase I started to build in 2018, but that's a story for another day!)

This made a relation graph an attractive concept to build in, something that did not exist in most "wiki" platforms. A big inspiration was Notion's "database" feature, where pages in the tree can exist within a structured table where attributes of the page itself become columns in that table. Essentially creating a very user-friendly relational database.

So how do you implement a relational database inside a relational database?

There are two ways to do this:

1. Actually just surface the relational database itself as an API.

   This approach means that when you add a property to a page the application runs an alter table add column command against the database. Your database table structure is the user's interface into the properties and relations within the content itself.

2. Implement an entity-attribute-value pattern

   The approach Storyden takes, where an additional table stores property names and values which are then related to the actual pages.

Notion seems to use a hybrid of both approaches where SQLite acts as a relational cache with a "real" schema, then the cloud persistence implements some flavour of EAV. When you load a Notion page, the property queries run on the fast SQLite instance after the bulk of the data is loaded from the cloud store.

Storyden is much simpler and just has one database: SQLite or PostgreSQL, whichever floats your boat. And on-the-fly schema modifications sound complex and could make migrations a nightmare. So I opted for EAV.

Now, while the EAV pattern offers flexibility without needing to keep tabs on the underlying database schema, it comes with tradeoffs. Both of these databases are heavily optimized for relational queries over fixed-column schemas, where indexes, statistics, and query planners can make efficient decisions based on known, static table structures.

With EAV, the key-value nature of the data model complicates what would normally be a simple column filter or join into multi-table joins and lookups.

For example, to sort a set of nodes that represent companies by their founded_year, it can’t use a direct index scan on a founded_year column, it would need to join the properties table to find the correct key and then filter or sort on the resulting rows. This makes it difficult for the query planner to optimize because the database cannot prebuild indexes across what are effectively row-based dynamic fields.

As with any technical decision, there are compromises. I chose EAV because it was (somewhat) easier to implement for now. I am but a sole developer and this product is not a money-maker, I don't have a team of people smarter than me (that would be great!) so I've chosen a dumb solution. If I had chosen a dynamic schema approach, it would have increased the testing surface area massively, and a bug in that kind of system carries a higher risk. I chose low risk at the cost of slightly reduced performance.

Properties today

As of this post, the API is almost fully implemented, it only lacks data type implementations (which is a challenge in and of itself, given every cell is just a text type) so if you're a user of the API only, you can take advantage of this now!

The Storyden frontend currently exposes properties as a basic table on Library Pages. Table views, filtering and other features are on the near-term roadmap so keep an eye out!

What's next?

Now that this feature has landed in the API side, I have big plans for the knowledgebase side of Storyden's product offering. This unlocks:

• Database tables, like Notion but social!
• Big directories that are easy to navigate, filter and search
• Pre-filtered views of database nodes, referenced in other pages

Who is this for? Some ideas themed on early adopter feedback sessions:

• Video game communities who want to keep track of item stats in a structured way
• Curators who want to maintain a community contributed directory of resources
• Gear nerds who want to catalogue their favourite tools, devices, etc.

Technical overview

If you came here for the details, here's how Node Properties are implemented.

Library Pages are a tree structure, so internally they are called "Library Nodes". Being a tree structure, this means each node may have many children. When properties come into play, this means all children of a given node must share the same set of possible properties. Properties are organised into "property schemas" to ensure this fact.

In data modelling terms, this means for every group of nodes with an identical parent_node_id the property_schema_id must be also identical. So all the nodes with some parent A, also must use the schema X

The schema itself may have fields, fields are defined once to save space and make changing field names or types easy. This means that a node has one schema and that schema has many fields.

Property values are stored separately from the underlying property schema, because each node in a set will have many property values, each value maps to a schema field. This means that a node has zero or many property values but always zero or one schema.

<Mermaid chart="erDiagram NODES { TEXT id PK TEXT parent_node_id FK TEXT property_schema_id FK TEXT sort } PROPERTY_SCHEMAS { TEXT id PK } PROPERTY_SCHEMA_FIELDS { TEXT id PK TEXT name TEXT type TEXT sort TEXT schema_id FK } PROPERTIES { TEXT id PK DATETIME created_at TEXT value TEXT node_id FK TEXT field_id FK }

NODES ||--o{ PROPERTIES : has
PROPERTY_SCHEMAS ||--o{ PROPERTY_SCHEMA_FIELDS : defines
NODES }o--|| PROPERTY_SCHEMAS : uses
PROPERTIES }o--|| PROPERTY_SCHEMA_FIELDS : for

" />

Other than the schema itself, properties are quite loose, a set of children may hold a subset of property values. For example, given 3 nodes under "Items" only one or two of those nodes may have a property value for "Weight".

Some query use-cases

An API consumer will care about a few different perspectives of this data structure. For example, you may want to get a single node without its children and see its "child node schema". This would be the schema that all child nodes of that schema share. This "child node schema" is not actually stored on the parent node itself because root nodes have no parent and this would restrict the ability for root level nodes to have properties. For this reason, the schema itself is referenced by the nodes directly, allowing root level nodes to hold a schema and properties.

Querying property schemas of nodes

To solve this use-case, the siblings and the parent are queried to gather all fields. So if the parent node also has a schema, you get both in one query:

with
  sibling_properties as (
    select
      ps.id         schema_id,
      min(psf.id)   field_id,
      min(psf.name) name,
      min(psf.type) type,
      min(psf.sort) sort,
      'sibling' as source
    from
      nodes n
      left join nodes sn on sn.parent_node_id = n.parent_node_id
      inner join property_schemas ps on ps.id = sn.property_schema_id
      or ps.id = n.property_schema_id
      inner join property_schema_fields psf on psf.schema_id = ps.id
    where
      n.id = $1
    group by ps.id, psf.id
  ),
  child_properties as (
    select
      ps.id         schema_id,
      min(psf.id)   field_id,
      min(psf.name) name,
      min(psf.type) type,
      min(psf.sort) sort,
      'child' as source
    from
      nodes n
      inner join nodes cn on cn.parent_node_id = n.id
      inner join property_schemas ps on ps.id = cn.property_schema_id
      inner join property_schema_fields psf on psf.schema_id = ps.id
    where
      n.id = $1
    group by ps.id, psf.id
  )
select
  *
from
  sibling_properties
union all
select
  *
from
  child_properties
order by source desc, sort asc

Another use-case is you pull one node that's a child of a parent node. You want to see this node's schema and its values. This one is easy, the schema is already stored on the node itself so it's just a quick join against properties of that node - which is a direct relationship. However, because the properties themselves only store the values of properties, the schema and schema fields are still required in the query. Values are related to schema fields by the field ID.

Some useful observations for schemas and values:

• Schemas don't change often, usage patterns often see rare but relatively large bursts of mutations (when a user is setting up a new page or editing columns) followed by no changes for a while. This allows caching to come into play and this is easy to implement over the top of the current node repository as properties are queried separately, not joined against the node itself.
• While schema data involves some pretty gnarly queries, the sizes of actual schemas are in the 10s of rows.
• The actual bottleneck is in the node queries themselves, where parent nodes may contain hundreds or thousands of children so more work on optimisation will focus on these read paths rather than property value/schema write paths.

Sorting nodes by their EAV values

One of the more complex and performance sensitive areas is querying all children of a node and operating on the property values to perform filtering or sorting. This is currently implemented as a separate query to pull the properties in a table result and joined in-application to the nodes being queried. The sorting itself is still performed in the database when pulling the property values. The ordered result is then used to sort the list of nodes in-application while mapping the results to the nodes.

const querySortedByPropertyValue_sqlite = `
select
  n.id id
from
  nodes n
  left join properties p on n.id = p.node_id
  inner join property_schema_fields f on p.field_id = f.id and f.name = $1
where
  n.id in (%s)
order by
  case f.type
    when 'text'      then p.value
    when 'number'    then cast(p.value as real)
    when 'timestamp' then cast(p.value as datetime)
    when 'boolean'   then cast(p.value as integer)
    else p.value

  end %s

limit  %d
offset %d
`

const querySortedByPropertyValue_postgres = `
select
  n.id id
from
  nodes n
  left join properties p on n.id = p.node_id
  inner join property_schema_fields f on p.field_id = f.id and f.name = $1
where
  n.id in (%s)
order by
  case f.type when 'text'      then p.value                            end %s,
  case f.type when 'number'    then cast(p.value as numeric)           end %s,
  case f.type when 'timestamp' then cast(p.value as timestamp)         end %s,
  case f.type when 'boolean'   then cast(p.value as boolean)           end %s,
  p.value %s
limit  %d
offset %d
`

In classic SQL-doesn't-have-a-standard-that-anyone-cares-about fashion, we need two separate queries here, one for PostgreSQL/CockroachDB and another for SQLite.

Another irritating fact is you can't parameterise anything in a query, only certain types of syntax so certain parts of this query must be (dangerously) injected using string formatting primitives before being passed to the database's own argument mapping. So there's a mix of $ positional arguments and % format specifiers. It'll probably stay this way for the next 50 years so don't hold your breath for improvements...

Okay, ranting aside, this query gets us a list of node IDs sorted by the given property value, based on its declared data type. The case-switch in the order by clause allows us to lexographically sort text while correctly sorting other types such as numbers, timestamps and booleans.

Pulling the whole tree while filtering nodes with many children

This use-case of "database nodes" that hold many children that looks somewhat like a relational database on the surface introduces another problem. Storyden's sidebar will give you the whole tree, and if one of those nodes has 1,000 children because it's being used as a "database page" with a bunch of properties rendered as a table, that's a problem.

So, to solve this, nodes have a column called hide_child_tree which, when true, will omit the children of that node (not the node itself) from the tree. This means the node that contains 1,000 children will still be visible in the sidebar, but its children will not and React will not try to render thousands of DOM nodes.

This is achieved by checking the hide_child_tree in the recursive part of the tree-traversal recursive CTE. What this does is it tells the query engine to stop recursing once that clause yields a false outcome resulting in the immediate row being emitted but none of its children will be iterated and the query continues to the next sibling to continue walking the tree.

with recursive children (parent, id, sort, depth) as (
    select
        parent_node_id,
        id,
        sort,
        0
    from
        nodes
    where %s
union
    select
        d.parent,
        s.id,
        s.sort,
        d.depth + 1
    from
        children d
        join nodes parent_node on parent_node.id = d.id
        join nodes s on d.id = s.parent_node_id
    where
        parent_node.hide_child_tree = false
)
select
    distinct n.id       node_id,
    n.account_id        node_account_id,
    n.visibility        node_visibility,
    n.sort              node_sort_key,
    depth
from
    children
    inner join nodes n on n.id = children.id
    inner join accounts a on a.id = n.account_id

-- optional where clause
%s

order by
    depth, node_sort_key

Again, <SQL rant />, %s is there at the bottom to dynamically inject more clauses to the query. No injection here as the rest of the code that constructs this query inserts $ positional arguments and passes the user-supplied fields into the database's arguments not the raw string query. The code is a mess, please don't look for it.

Conclusion

It works. It's not perfect, and it is begging for improvements but it works. And it has fairly deep end-to-end test coverage so that's a win!

If you'd like to contribute to this mess, please check out the project's GitHub page! https://github.com/Southclaws/storyden

TL;DR: New site! New docs! Bit of a brand refresh and some reflections on direction. What 2025 holds for the launch of stable production-ready-to-use.

The last entry was a sort of "how we got here". The conclusion was that the idea of a community knowledge-base is at the core of Storyden.

That doesn't remove the forum aspect, it plays on it. Internet forums of the 2000s, which I grew up on, solved a problem for that era. This is a new era with new problems so rehashing phpBB or SMF won’t cut it.

Most of my circles live on Discord, but good luck finding that great link someone shared last month.

Since launching the project, I've received some great feedback via this form one stuck out to me and really resonated with the north star that has guided Storyden's development over the last couple of years:

Discord is too real time -- Discourse is too detached from people's daily work. So we need a way to create HN + Discord

Which, really nails the origins and reasons I started the project. See any of the other articles on this site to dive deeper.

Try it out right here, right now!

Visit our community Storyden instance: https://makeroom.club/

Or get started here and run one yourself:

docker run -p 8000:8000 ghcr.io/southclaws/storyden

So what next? Keep building out features ad infinitum? No.

This site is brand new, along with some touch-ups to the brand identity and a whole lot more documentation.

New Site

The new homepage for Storyden runs on Fumadocs which I was extremely happy to discover on an X thread. It's a documentation site builder for Next.js which replaces Nextra in all the ways I wanted it to.

Nextra was great, but it suffered from a few weird issues I couldn't figure out, plus it was stuck on the old "Pages" mode of Next.js, making certain newer functionality of the framework more difficult to use.

Fumadocs runs on the latest Next.js version with the "App" directory system. As a Next.js nerd this pleases me somewhat! It also means I can more easily use layouts, opengraph images, custom page designs, etc. Great work Fuma Nama, no notes.

Brand Refresh

My partner said I should stop obsessing over design details and just ship the product. Which, yes, she has a point. But a bit of burnout, getting stuck on some complex features (node properties was a nightmare) and attempted fundamental changes to the frontend (RxDB is really complicated) was cured by a weekend of obsessing over typefaces, colour palettes, styleboards, kerning, more colours and other good design stuff I just really enjoy.

So yes, was a rebrand necessary before the product is even "released"? No. Was it necessary for my mental health? Certainly.

The new mark uses this beautiful typeface I found by the Identity Letters foundry, designed by Moritz Kleinsorge. It's a perfect balance of smart-casual playfulness that fits Storyden so well.

The rest of the type is set with:

• Work Sans by Wei Huang for general interface body text
• Hedvig Serif by Kanon Foundry for longform body text
• Intel One Mono by Frere-Jones Type for code examples

What's ready?

So, you can deploy Storyden right now. To production. And have lots of fun.

All the fundamentals are documented now, peruse the new pages and begin imagining how useful it could be to your community.

You can:

• Run a discussion forum
• Let your members sign up with just a username, an email or go full OAuth2 with Discord, Google and GitHub (more on the way!)
• Run a directory
• Let your members contribute to the library and grow your collective information repository, whether it's links to cool sites, items in a video game organised by stats, your favourite indie clothing brands, whatever floats your boat!
• Enable AI features for asking, semantic search and automated organisation

You can't: (yet)

• Connect to Discord/WhatsApp/Slack: for me, these would close the gap between where my folks hang out and where we want to store all the great links they share. There are a few features I want to get right here so this bit is top of mind for the next iteration.
• Organise nodes by property in database views: I am shamelessly copying Notion here but in the spirit of solving my own problems, I want to go deep down the directory route and make Storyden the easiest place to build well-organised directories. The foundation is there (node properties) but the UI needs love and the APIs need smarter filtering, grouping, etc.
• Extend the platform: this is a huge one, and what I believe makes any software product long-lived. Go beyond the boundaries I've created and really turn your Storyden into whatever you want. Spoiler: it involves extremely simple WebAssembly stdin/stdout RPC.

What's next?

On the product side: those three things right above ☝️

On the marketing side: figure out how to really gain proper traction, find the people who share the problems that I'm solving for myself and sell the dream!

Hosted: for the non-technical folks, a simple hosting platform. Harder than it seems but fun to build and surprisingly cheap enough to offer just a free tier for the time being (full transparency: business administration is time consuming and not something I really want to deal with right now) reach out if you want to be in the first cohort!

Open source: there have been a lot of interesting problems solved in the dark depths of the Storyden codebase, one goal is to pull out some of those bits and libraryise them for easier use in the open source community.

Anyway, I've got a friend's wedding to attend now so, until next time 👋

Barney

These goals have evolved over 2024 as I've narrowed the focus of the project, found a direction where I'm happy with the long term viability and market fit. I've also had the opportunity to dogfood the product in a few production scenarios, which has lead to some areas to advance a lot faster than others, more on that later.

Let's get the buzzword out of the way first

Unless you've been living under a rock, you know generative transformers and language models are the thing right now. As with most of my peers, I'm not of the opinion this stuff is going to replace software engineers, copywriters, artists or any other profession. There's a lot of power behind GPTs which isn't just generating mediocre blog posts. (as I'm writing this, copilot is giving me the most mid suggestions and mundane sentances)

Storyden, so far, does not have any form of content generation aside from a single summarisation prompt, which honestly isn't very good. It'll probably stay like that as my target audience and existing early users simply aren't interested. I've had the opportunity to chat to a lot of people in various industries, primarily people who hold writing as a core part of their strategy (whether its thought leadership, community building, newsletters, content marketing, etc.) this year and a common sentiment is that their writing must come from them, it's very personal and that personal touch matters.

Where I think language models can shine is surprisingly not so much in the spotlight: recommendation algorithms and (very) fuzzy search.

The Semdex

In classic fashion, I invented a term in the codebase, semantic + index = semdex. Silly, I know. The Semdex is essentially a big graph database, but there are no edges connecting nodes. Instead, use vector embeddings much like RAG search. I have some strong opinions on search, but more on that in the next section.

Throwing everything into a vector database and not worrying too much about building complex edge relationships has been quite a nice mental model for me. It's also very fast, even with a few thousand items (though, further benchmarking with larger datasets is needed.)

What this unlocks is an almost democratisation of recommendation algorithms. One weekend I dumped a ton of vertical videos from TikTok into the Semdex, wired up watch time, likes and comments and as I scrolled through the feed, it gradually became more and more tailored to my "interests". I would have never imagined I could build a "recommendation algorithm" when I studied machine learning in university, it all went over my head and seemed so much like a black box with an awfully slow test-train feedback loop. I've started to think of LLMs as a sort of higher level abstraction on top of ML fundamentals (well, it sort of is I guess, but I'm no expert!)

Of course you wouldn't really want to launch a endless scroll vertical video app built on a single Go server, there's a ton more to consider like not feeding previously viewed videos, content moderation, performance, etc. TikTok itself put out a great paper which is obviously a lot more sophisticated but it does share some DNA.

And this had me thinking a lot about social platforms in general, particularly over-recommendation. Why recommend only things you like, what about recommending things you may not like or agree with. Which are all things you can do if you own the data and the algorithm. And yes, pluggable algorithms are something I've toyed with.

Which is really what Storyden is all about, get your community off Reddit and stop feeding them free training data. Self host your data, your embedding engine, own it all.

Forum?

So the landing page says "A forum for the modern world" and so far I've just talked about LLM nonsense like every other VC backed tech product over the last year (Storyden is not VC backed, for the record...) am I straying from the original path?

Well, a little. I've gone back and forth on the forum idea quite a bit, but I keep seeing people on various platforms say things along the lines of "what happened to all the old internet forums, why is everything just reddit now?" so I think there's still a place for a product like this.

What I'm trying to balance is innovating a little on the timeless idea while keeping the DNA of what made the forums I grew up on so fun.

A common indie hacker trope is that you're just building to solve your own problems and somewhere along the way, it becomes a viable business endeavour. But a pitfall is you're building for your echo chamber, your age group, your demographic. You are the average of the 5 people you associate with most and all that. I've framed this project as something for the future, so I can only borrow so much from the past before it alienates the next era of internet users. If a WordPress of the 2030s is to exist, what attributes should it borrow from the social media platforms most of the youth are using today? On top of that, what are the most useful features that are actually valuable to people, and what's just marketing fluff. (something something AI powered blockchain NFTs)

Social Primitives

The last 15 years has seen a small assortment of ideas that permiate almost all "social" products. The likes, the shares, the threads, etc. Most of this stuff is not technically challenging at all, you can clone Twitter in a weekend and if you get past the cold-start problem by hitting the right niche with the right messaging, you can build a fairly active and successful space, posts.cv did this and it's a wonderful breath of fresh air compared to what Twitter has evolved into. Substack is another example that carved out a niche that became a fairly large successful platform rivalling WordPress and similar.

So with this, I believe it's important to pick the primitive building blocks that make sense because familiarity matters. Then innovate on top of that with "nice UX" (whatever that means today) and a light sprinkling of features that lead to popsicle moments.

It's not social at all, but I think Linear is a fantastic example of a beautiful product in a boring space that manages to be a joy to use. Outside of the impressive technical implementation (CRDTs and such) the experience of using Linear adds a layer of delight on top of what's normally quite a boring process (product and project management.)

These are my north stars for Storyden, a product that's a joy to use, that's familiar enough to not alienate, but innovative enough to be useful for the next era of internet culture.

Information directories and curation

I use TikTok, every day, it's my digital junk food and in moderation I think it's fine. TikTok has become a search engine, and what started as a dancing video app eventually competing with Google, the monopoly that totally isn't (😉) a monopoly was not on my 2024 bingo card.

Most of the value I derive from this app is rooted in curation. Primarily clothes and music. I've discovered artists I never would have with Spotify's obsession with playing the same songs. (which I think is that over-recommendation problem I mentioned earlier) and independent fashion brands that I would have never found on Instagram. Some creators I follow do both music and fashion all on the same account.

The problem is while TikTok is becoming a macro-level search engine for the next generation, it's actually not great at the micro level. If I want to find a video ZAGUA made about a particularly interesting brand 6 months ago, that's just not happening.

A lot of creators get around this by setting up a Notion database, like this research archive by QuickThoughts where he's painstakingly listed every uploaded video along with detailed research notes. And if I want to drop a comment or chat with other fans, I have to go back to TikTok, find the video then leave a comment which will be lost to the void because anything older than a day is essentially nonexistent on the platform.

So, a common indie hacker trope is that you're just building to solve your own problems? I suppose so. This area of Storyden is more on the experimental muse side of things. Figuring out the marketing messaging for this feature is a little tough, "social Notion"? "WordPress with spreadsheets"? It's also a feature that I haven't actually validated, as far as I know, nobody is asking for this. But I'm building it anyway because I feel like there's a success trajectory somewhere along the way. It's also just fun, for some reason.

The Backend x Frontend race

Due to how I'm using Storyden with a few existing "customers" (I use that term lightly, revenue is zero and probably will be for a long time) I'm often building bespoke frontends rather than using the reference implementation in the open source repository. The benefit here is the API-driven design is really proving itself, as I can just pull the OpenAPI specification, generate a client and build out a fairly nice React frontend in a weekend. The downside here is that the backend is way ahead of what the reference frontend exposes. Everything in this post is a feature implemented, tested and (somewhat) documented in the backend Golang codebase. The frontend, and thus the public "demo" at makeroom.club is a little behind.

There are a few early features in development that will most likely land before the end of the year. And if you're building a bespoke frontend implementation on top of the Storyden platform API, you can already start using them.

Events

A few early users have mentioned event organisation in-product, a sort of Luma alternative that's built in with all the normal things you'd expect from an events platform, like invites, RSVPs, ical integration. This one is still early and build started in the summer.

Roles

For an embarrassingly long time, there was a single boolean flag called admin. That was the role-based-access-control mechanism. Last month, I finally got around to replacing this with a proper role system with granular permissions. I've modelled roles after the Discord permission system, which I think is a good balance between flexibility and simplicity. Roles can hold permissions, or they can just be aesthetic and give a bit of colour to your username.

Authentication

Emails landed as an optional way to authenticate. If you've read any of the other blog posts about core values, you know that I consider email addresses to be optional. Privacy conscious hosts can omit the need for an email address for sign-up and opt for just dealing with handles. But for those who want to use Storyden as a more traditional forum, emails are now an option.

There's also an unfinished branch called saml... #enterprise

Web3 is something I put on the home page back when I designed that over 2 years ago. That claim, I am sad to say, still has not come to fruition. Mostly because I know absolutely nothing about Web3 technology. Fake it 'til you make it, right? I should probably remove that claim for now...

The future

After doing almost zero marketing (apart from these sporadic blog posts) the GitHub repository still has almost 100 stars, so that's neat. Not huge numbers but it's something of a signal that there's some interest. I will eventually do the usual Hacker News, Reddit, Product Hunt rounds, but in classic perfectionism mindset I am hesitant to try until a few more forum basics (which I keep putting off) are implemented.

As for business plans, there's none yet, Storyden will always remain open source and I am very aware of the recent license shenanigans with Redis, ElasticSearch and friends. This is mostly blocked by the frontend issue mentioned above, movement there will unlock usability of the more powerful features and make the product a more compelling offering. Also, multi-tenant hosted instances are hard. If you want to chat, offer advice or help in any way, shoot me an email barney at symbol hey dot com.

And that's it, 2024 in a nutshell so far. I'm cautiously excited about the next chapter of Storyden, and I hope you are too.

The view out of the window on this bleak winter morning in the French countryside.

Those good friends I know because of a multiplayer game we all played years ago. There were forums for asking questions and showing off what you'd made and a wiki for documenting the scripting APIs and other things like models, textures, skins, vehicles, etc.

I love Discord, it's what we use nowadays for this community and a few others, it's what we used to organise the first FOSDEM trip, our trip to Poland, Iceland, Switzerland and many other lands. Projects have been born there, jobs have been found, advice given and memories made. But it's not the be-all-end-all of online community experience.

Asynchronous still has its place

Discord, Slack, WhatsApp and others fit into a category of communication tools known as "synchronous". This means that, most of the time, you need to be online at the same time as the other members to communicate. There's message history but it's rare you can or even want to keep up with every single message.

One of the side effects of this is discussions, links shared and advice can get lost. Even with fairly modern search tools it's not always easy to find that one link someone shared a few months ago that you know you need now. What makes this worse for the data side is that conversations are often interspersed and there can easily be two or three discussions happening at once. People may find this easy to follow, especially if you've grown up with IRC, MSN groups or WhatsApp chats. But for a computer system it's very difficult to figure out what's related to what.

Amir: @Southclaws did you see my PR?
Southclaws: @Michael have you tried AsyncAPI yet?
Amir: LMAO
Amir: <twitter.com/...>
Michael: not yet, but it looks nice
Southclaws: @Amir yeah I replied on gh
Marcel: @Amir wanna game?
Southclaws: lmao nice
Southclaws: yeah I'm thinking of async api for storyden websockets

try and string this tiny snippet from Makeroom's Discord chat together into independent threads...

Searching this word-by-word may be easy but topic based semantic search becomes difficult. While a relatively new technology, it does a better job with fewer, larger pieces of text. Chats are difficult to index and difficult to search because you're often not quite sure what you're looking for. It's all a very fuzzy problem space but traditional fuzzy-match-based-search may not work as well.

Now, it's worth noting the old forums weren't much better. In fact, they were much worse because your search queries were often exact matches rather than somewhat fuzzy. I can search for "repos" and Discord is smart enough to turn that shorthand plural into a singular token ("repo") and show me results for both "repo" and "repos."

But I think what makes most of the difference is how content is written and organised. In a synchronous platform, members will write a high volume of very small messages, some of which are single words or even single characters. In an asynchronous such as GitHub issues, Discourse and traditional forums, members will (most of the time) write a lower volume of longer messages.

The interfaces of both of these are designed around this idea. Single line text box where media is treated as an "attachment" and formatting is minimal vs. larger text area, maybe with WYSIWYG formatting and richer content such as images and videos interspersed with text.

And it shows, Discourse has found a solid market in the customer support space. Discord added "Forum channels" which are effectively somewhere between chat and forums. GitHub issues are used for bug tracking but they also added "Discussions" which is just an oldschool forum. The need for this slightly longer form and lower volume format is clear.

Search is hard

I'm not all-in on semantic search either. I do find it aggrevating when I'm trying to find what I know to be an exact word match in some website search and it's trying to Be Clever™ by using some kind of LLM based semantic search. This often doesn't help

Semantic has its place but you need to give users options. Not having options really ruins user experiences and it gives off this aura of "We know better" pretentiousness. It's one of the huge issues I personally have with Apple products!

So when is semantic search useful? When you're not quite sure what you're looking for but you have a rough idea. Language models are amazing in this problem space and it's one reason I think the latest wave of LLM hype is well earned compared to the days of natural language processing I spent way too many caffeine induced nights trying to get right in uni!

It also gets better the larger the dataset is! So...

Knowledge aggregation is a team sport

In a previous article about link aggregators and social bookmarking we discussed how useful and natural collecting a big pile of URLs is to most folks on the internet. And multiplying that by a group of people can have awesome effects.

A combination of chat apps, link aggregating and building a directory of resources around which a community interest grows. Clubs, mentorship, support, teams, gaming can all benefit from this approach.

Storyden's architecture is centered around organising information. It's like a little baby version of "organising the world's information and making it universally accessible and useful", you could say it's... your own personal Google! how about, "organising your community's information and making it searchable and useful"? If it wasn't such an obvious rip, I'd use it on the landing page!

So if any of that resonates with you, why not give Storyden a try? I'd love to hear your feedback and input as we develop entirely in the open! Community style.

Thanks for reading! Maybe see you next FOSDEM 👀? (yes, at the time of writing this is a 404 but I'm sure it'll appear at some point in the year! my SEO will not like that but I'll 100% forget to come back and add a link...)

I won't go into the details of what it actually is. You can learn about that in this fantastic blog post by Neal Fennimore. There are also some more technical articles that go into the details such as the W3 spec and a web.dev article.

How and why Storyden uses Passkeys

Storyden supports Passkeys as a fundamental authentication method. This means that you can use a Passkey to register and sign in to a Storyden site. This is a great way to keep your account secure and to make sure that you don't have to remember a password for every site you use.

Email + Password is not the default any more

Storyden's authentication model does not simply have an "email" and "password" column in its data model. Storyden is a platform for the next era of the web, so it would be foolish to fall into old ways, especially for authentication. Passwords can be enabled, but they are not assumed to be the default. You can operate a Storyden instance and completely disable passwords if you want.

Similarly, email is not considered a default either. The world is changing and people are much more conscious of privacy, security and technical monopolies on data. You may not want to sprinkle your email address all over the net. While there have been efforts by Apple, Mozilla, and others to create 'fake' email addresses that forward to your real one, if you don't need someone's email, then why even require it? This is why Storyden operates on a username-first model, email is optional for transactional or newsletter purposes, but it's not a default.

As an operator of a Storyden community, you have the choice to use email + password as the login method for your members, but you also have the choice to allow full anonymity with a username + passkey combination.

The benefits of Passkeys

Passkeys are great in certain circumstances. They're not a silver bullet, but with growing support on devices, browsers and operating systems, they're becoming more and more viable as a default authentication method.

Privacy

The privacy implications are great, for users and administrators alike. By eliminating the need for passwords, it mitigates the risks associated with traditional authentication methods, such as phishing, brute force attacks, and password reuse. Which isn't just great for users, but also for operators and administrators because it reduces the responsibilities and risks associated with storing and managing passwords.

Because it utilizes public key cryptography to provide a secure and (almost) seamless way for users to access their accounts. This not only safeguards sensitive user data but also reduces the likelihood of unauthorized access to accounts - especially admin accounts!

User-Friendly Experience

In addition to bolstering security, WebAuth offers a user-friendly experience - assuming you're on a compatible dev ice. With no passwords to remember, users can enjoy a hassle-free login process. This not only streamlines access to Storyden but also eliminates the need for password resets and the associated frustrations.

It's not all perfect though, I'll get into why that is in the next section.

The downsides of Passkeys

Passkeys are great, but they're not perfect. There are some downsides to using them, and it's important to be aware of them before you decide to use them as a default authentication method.

Dealing with multiple devices

All services on which I've recently enabled a Passkey have treated them as a form of 2FA rather than your primary login method. This isn't just because of support, but also difficulties with being locked out of your account. The spec does not define a way to recover accounts or synchronise keys. This is left up to vendors such as Apple, Microsoft and Google.

So, if you're locked in to enjoying the Apple ecosystem on all your devices, you're pretty much covered as iCloud's keychain will synchronise an end to end encrypted backup of your keys between your devices. This means I can sign up to a Storyden instance on my Macbook, then log in to that same account on my iPhone without having to do anything. It's pretty great.

Outside of the (walled) garden of eden though, it gets a bit tricky. Windows Hello supports keys, but the device sync is not clear if you have an Android or iPhone, you'll need to do some extra work to get that set up. Not everyone will know that's even a requirement, which introduces a risk of having your key only on one device without knowing how to transfer it. If you lose or factory-reset that device, you're kinda screwed.

Password managers to the rescue?

1Password and other password managers offer a pretty nice experience for this, but it's far from a widely adopted, and if you're already using a password manager, the benefits aren't immediately clear as a user.

I'm a tech nerd so I'm clued in on this stuff but that's a minority, not many folks I know outside of tech use password managers, so Passkeys could risk being locked out.

Domain changes require careful planning

Passkeys are tightly coupled to the domain name of the service. Partly to piggyback on the security of HTTPS and related domain verification, but the downside of this is that changing domains will not be so simple.

As an administrator of a platform, you may want to change domains (or need to) and currently, this process is not well defined. You need to do a bunch of work to prepare users for this change, and then those users also need to action that change on their devices. It's no secret that people rarely read product updates so communicating this is a challenge.

How Storyden treats Passkeys

Passkeys are great, but not a silver bullet. Storyden also doesn't want to enforce a password because ultimately, that's up to operators to decide. So, Storyden treats each authentication method equally and recommends that users set up at least two methods of authentication. These can be anything:

• a Passkey + a Web3 wallet
• a password + a Google login
• a Phone number and a Passkey

In conclusion

Operators can enable whichever authentication methods they want, depending on their community's values and goals. If you want to go fully decentralised, you can use Passkeys and a Web3 wallet. If you don't mind using centralised services, an OAuth2 provider such as Google and Passkeys are fine, and if you want to support traditional email + password, you can do that too.

Get started with Storyden today and build a secure and privacy friendly community ready for the next era of the social web.

Starting in the middle

At the core, Storyden's behaviour is defined as an OpenAPI specification. This specification is hand-written, optimised for readability because it's intended to be read.

I opted to write the specification and generate the code because I really value static, declarative documents from which the boring bits can be mass-produced. I don't really enjoy writing func(w http.ResponseWriter, r *http.Request) functions by hand, dealing with decoding the JSON and encoding the responses and errors. OpenAPI allows me to work with functions that look like this:

AccountUpdate(ctx context.Context, request openapi.AccountUpdateRequestObject) (openapi.AccountUpdateResponseObject, error) {
  // access `request.Name`
  // respond with an `Account` struct
  // handle errors by returning (nil, err)
}

It also allows me to generate client code for both Golang (for end-to-end tests, my favourite flavour!) and TypeScript. The frontend for calling the above example looks like this:

const updatedAccount = await accountUpdate({ name: "Southclaws" });
// updatedAccount: { name: "Southclaws", ... }

Which eliminates a metric ton of work for me and other contributors!

But it's more than just a time saver, it's documentation and, most importantly, a contract! A contractual interface that's agreed upon by developers before diving into implementation details behind the interface.

Now I don't take the spec part that seriously, it's a useful layer to write some details about things that may not be obvious just from the operation name and parameters. But there's no formal MAY, SHOULD, MUST lingo in there, it's just a useful source of truth from which everything else is built on.

Speaking of APIs...

Also, this makes Storyden API-driven. You can bin the stock frontend and build your own if you want! You can also build other services in whatever language you want that call these APIs to automate certain tasks where WebAssembly plugins and integrations aren't quite enough.

Content-type driven handlers

Another neat thing you can do with OpenAPI is define HTML form friendly handlers. Most JSON APIs accept application/json from a fetch request. But if we want to support JS-less frontends that want to use HTML forms in all of their natural beauty, it's as simple as:

AccountUpdate:
  content:
    application/json:
      schema: { $ref: "#/components/schemas/AccountMutableProps" }
    application/x-www-form-urlencoded:
      schema: { $ref: "#/components/schemas/AccountMutableProps" }

This requestBody schema permits two content types that use the exact same underlying schema. This re-use means certain endpoints ✳︎ can trivially be set up to support non-JS clients as long as their HTML form field IDs match the fields documented in the schema.

HTML forms are important because some folks disable JavaScript for good reasons: privacy concerns, bandwidth constraints and device processing power.

export const useAccountGet = <
  TError =
    | UnauthorisedResponse
    | NotFoundResponse
    | InternalServerErrorResponse,
>(options?: {
  swr?: SWRConfiguration<Awaited<ReturnType<typeof accountGet>>, TError> & {
    swrKey?: Key;
    enabled?: boolean;
  };
}) => {
  const { swr: swrOptions } = options ?? {};

  const isEnabled = swrOptions?.enabled !== false;
  const swrKey =
    swrOptions?.swrKey ?? (() => (isEnabled ? getAccountGetKey() : null));
  const swrFn = () => accountGet();

  const query = useSwr<Awaited<ReturnType<typeof swrFn>>, TError>(
    swrKey,
    swrFn,
    swrOptions
  );

  return {
    swrKey,
    ...query,
  };
};

/**
 * Update the information for the currently authenticated account.
 */
export const accountUpdate = (accountUpdateBody: AccountUpdateBody) => {
  return fetcher<AccountUpdateOKResponse>({
    url: `/accounts`,
    method: "patch",
    headers: { "Content-Type": "application/json" },
    data: accountUpdateBody,
  });
};

export async function FeedScreen(props: Props) {
  const data = await server<ThreadListOKResponse>({
    url: `/threads`,
    params: {
      categories: [props.category],
    } as ThreadListParams,
  });

  return <Client category={props.category} threads={data.threads} />;
}

"use client";

export function Client(props: { category: string; threads: ThreadList }) {
  const { data, error } = useThreadList(
    {
      categories: [props.category],
    },
    {
      swr: {
        fallbackData: props.threads && { threads: props.threads },
      },
    }
  );

  if (!data) return <Unready {...error} />;

  return <MixedPostList posts={data?.threads} />;
}