Emissary’s templates determine much more than the way a particular site looks. Templates can define their own data schemas, workflow rules, and other site behaviors. Each one is a self-contained unit that can be loaded from your server’s filesystem or downloaded from a networked Git repository. This lets system administrators set the ground-rules for how their servers are to be used, while still giving website owners control over their individual domains.

The Emissary distribution includes a number of default templates to get started, although system administrators can use the Setup Console to remove these and add a set of custom templates instead.

Creating and Distributing Templates

Each Template is just a collection of files in a directory that Emissary knows to scan. This can be a directory in the local filesystem, or a remote Git repository that is registered in the server configuration. Emissary will recognize a directory as a template if it contains a template.json (or template.hjson) definition file (as opposed to a theme.json file or a widget.json file).

Template File Format

Example JSON

Here is an example template.json file that includes some of these options:

<span><span>{
</span></span><span><span>	<span>"templateId"</span>: <span>"photo"</span>,
</span></span><span><span>	<span>"socialRole"</span>:<span>"Image"</span>,
</span></span><span><span>	<span>"model"</span>:<span>"stream"</span>,
</span></span><span><span>	<span>"containedBy"</span>: [<span>"photo-album"</span>],
</span></span><span><span>	<span>"label"</span>: <span>"Photograph"</span>,
</span></span><span><span>	<span>"icon"</span>: <span>"picture"</span>,
</span></span><span><span>	<span>"schema"</span>: {
</span></span><span><span>		<span>"type"</span>: <span>"object"</span>,
</span></span><span><span>		<span>"properties"</span>: {
</span></span><span><span>			<span>"document"</span>: {<span>"type"</span>:<span>"object"</span>, <span>"properties"</span>: {
</span></span><span><span>				<span>"label"</span>: {<span>"type"</span>: <span>"string"</span>},
</span></span><span><span>				<span>"imageUrl"</span>: {<span>"type"</span>: <span>"string"</span>}
</span></span><span><span>			}}
</span></span><span><span>		}
</span></span><span><span>	},
</span></span><span><span>	<span>"states"</span>: {
</span></span><span><span>		<span>"default"</span>: {
</span></span><span><span>			<span>"label"</span>: <span>"Default State"</span>,
</span></span><span><span>			<span>"description"</span>: <span>"Photos only have one state"</span>
</span></span><span><span>		}
</span></span><span><span>	},
</span></span><span><span>	<span>"accessRoles"</span>: {
</span></span><span><span>		<span>"editor"</span>: {
</span></span><span><span>			<span>"label"</span>: <span>"Editor"</span>,
</span></span><span><span>			<span>"description"</span>: <span>"Can make changes to this item."</span>
</span></span><span><span>		},
</span></span><span><span>		<span>"readonly"</span>: {
</span></span><span><span>			<span>"label"</span>: <span>"Read Only Access"</span>,
</span></span><span><span>			<span>"description"</span>: <span>"Can view this photo, but cannot make changes"</span>
</span></span><span><span>		}
</span></span><span><span>	},
</span></span><span><span>	<span>"actions"</span>: {
</span></span><span><span>		<span>"view"</span>: {
</span></span><span><span>			<span>"step"</span>: <span>"view-html"</span>,
</span></span><span><span>		},
</span></span><span><span>		<span>"edit"</span>: {
</span></span><span><span>			<span>"roles"</span>: [<span>"editor"</span>],
</span></span><span><span>			<span>"steps"</span>:[{
</span></span><span><span>				<span>"step"</span>:<span>"as-modal"</span>,
</span></span><span><span>				<span>"steps"</span>: [{
</span></span><span><span>					<span>"step"</span>:<span>"edit"</span>,
</span></span><span><span>					<span>"form"</span>: {
</span></span><span><span>						<span>"type"</span>:<span>"layout-vertical"</span>,
</span></span><span><span>						<span>"label"</span>:<span>"Edit Folder"</span>,
</span></span><span><span>						<span>"children"</span>: [
</span></span><span><span>							{<span>"type"</span>:<span>"text"</span>, <span>"label"</span>:<span>"Label"</span>, <span>"path"</span>:<span>"document.label"</span>},
</span></span><span><span>							{<span>"type"</span>:<span>"textarea"</span>, <span>"label"</span>:<span>"Summary"</span>, <span>"path"</span>:<span>"document.summary"</span>},
</span></span><span><span>							{<span>"type"</span>:<span>"select"</span>, <span>"label"</span>:<span>"Format"</span>, <span>"path"</span>:<span>"data.format"</span>},
</span></span><span><span>							{<span>"type"</span>:<span>"select"</span>, <span>"label"</span>:<span>"Show Images"</span>, <span>"path"</span>:<span>"data.showImages"</span>}
</span></span><span><span>						]
</span></span><span><span>					}
</span></span><span><span>				}, 
</span></span><span><span>			{<span>"step"</span>:<span>"save"</span>, <span>"comment"</span>:<span>"Updated Folder"</span>}
</span></span><span><span>			]}]
</span></span><span><span>		},
</span></span><span><span>		<span>"delete"</span>: {
</span></span><span><span>			<span>"roles"</span>: [<span>"author"</span>],
</span></span><span><span>			<span>"steps"</span>: [
</span></span><span><span>				{<span>"step"</span>:<span>"delete"</span>, <span>"title"</span>: <span>"Delete this Photograph?"</span>},
</span></span><span><span>				{<span>"step"</span>: <span>"forward-to"</span>, <span>"url"</span>:<span>"/{{.ParentID}}"</span>}
</span></span><span><span>			]
</span></span><span><span>		}
</span></span><span><span>	}
</span></span><span><span>}
</span></span>

Actions and Steps

Every Template defines a series of actions that can be performed on the Streams that use that Template. These actions might be as simple as “Create”, “View”, “Update”, and “Delete” – or they might define a sophisticated publishing and approval workflow that spans a number of individual users and roles.

There are three actions defined in the example template.json file above: “view”, “edit”, and “delete”. These actions can be as simple as setting some initial data, or loading an HTML template to display to the user, or they can define a complex behavior like the edit action.

Each action is composed from a library of interchangeable Steps that provide pre-built functionality to your template design. Steps each have their own rules and parameters. Some are very simple and only do one thing. Others can contain a large number of options – including other steps – to facilitate complex branching and workflow rules. All steps are pre-compiled when the template is loaded in order to maximize server performance.

HTML Content

In the action list above, the “view” action displays an actual web page. This HTML content is packaged into the template as a Standard Go Template. Like Themes and Widgets, These content templates are stored as separate files in the template directory, that must all be named with the *.html suffix.

State Machines

Every stream in Emissary is also a mini state machine. Each template can define the various states that its streams support. For example, the built-in article templates include “published” and “unpublished” states, while the built-in comment templates use “visible”, “hidden”, and “awaiting-moderation”. Here’s an example snippet from the built-in Article template:

<span><span>{
</span></span><span><span>    <span>"states"</span>:{
</span></span><span><span>        <span>"unpublished"</span>: {
</span></span><span><span>            <span>"label"</span>:<span>"Unpublished"</span>,
</span></span><span><span>            <span>"description"</span>:<span>"Visible only to Authors and Owners"</span>
</span></span><span><span>        },
</span></span><span><span>        <span>"published"</span>: {
</span></span><span><span>            <span>"label"</span>:<span>"Published"</span>,
</span></span><span><span>            <span>"description"</span>:<span>"Visible to all people with permissions"</span>
</span></span><span><span>        }
</span></span><span><span>    } <span>...</span>
</span></span><span><span>}
</span></span>

Extending / Inheriting Templates

Many templates share are so closely related, or share a lot of features in common. In this case, you can put common features in a base template that is “extended” by others.

As an example, the default package includes an “article” template that defines most of the workflow for creating and publishing articles. Two other templates – “article-editorjs” and “article-markdown” – extend this base template with specific functionality required for each of these different data types.

Here’s how extensions work: If a template defines an action itself, then that is the action that is used. Otherwise, Emissary searches through the list of extensions in the order in which they are defined to find that action name. To extend other templates, add an “extends” key into your template.json file with an array of template names as its value.

For example: if a template declares this: "extends": ["A", "B", "C"] then Emissary will first search template “A” for the required actions, then “B”, then “C”.

This inheritance structure can also cascade upwards, so that template “D” could extend “E”, which itself extends “F”.

This extension mechanism also makes it simple for Templates to inherit from multiple bases. In this case, if there multiple extensions, then the first template listed (and all of it’s ancestors in order) is searched first, then the second (with all of its ancestors), and so on.

This article is a follow-up to an older post of mine, Towards a Greater Federated Architecture, and also a response from the wonderfully-thought out piece by Ben Werdmuller, If I Started Fresh. The goal here is to take the lessons learned from a variety of systems to propose the Fediverse platform I have always wanted to build: Postmodern.

No code has been written as of yet, but I am learning to program, from the bottom up, backend to frontend. I have some background in game design, Web development, and API clients, but I'm working on the more elusive foundational stuff. This is the only way I can possibly develop the confidence needed to build this thing.

The Fediverse, Social Web, Peopleverse, whatever you want to call it, has evolved considerably since it originally started back in 2008. During my entire time on the network, I've longed to design a platform of my own. I've learned a lot of lessons from amazing projects along the way: Hubzilla, Bonfire, Emissary, and ActivityPods have all done some really interesting things beyond what Mastodon offers to the network. I also think there's some really valuable ideas in both Nostr and Bluesky that are worth closer examination.

Before I dive into my technical brain-droppings of the past decade, let's establish a few core concepts.

Guiding Principles

1. It needs to be fun

On the surface, this might sound superfluous. What does it mean for a platform to be fun? This boils down to a few key areas that Fediverse platforms struggle with:

• Ease of use - Good UX design is hard to execute well. As time goes on, I'm convinced that people want to use something without having to think too hard about conventions or side effects. They shouldn't have to dig under countless menus to find where the decentralization is.
• Discovery - For the time being, the act of finding new, cool things to interact with or peruse is pretty bad. There's some promising work happening with Fediverse Discovery Providers. Regardless, discovery needs to also extend beyond simply finding stuff, and include a laser focus on finding people. Onboarding still kind of sucks, and there's a number of issues with trying to find your friends and connect with them.
• Resiliency - One of the shakiest aspects of the Fediverse involves just how fragile instances can be. If an instance permanently goes down, and you didn't already have some alias set up to migrate your followers, you're dead in the water. Having to rebuild your social graph from scratch is the opposite of fun.
• Control - This can mean a lot of different things: control over your timeline, control over how your space on the web looks, control over your connections, control over your data. A big missed opportunity in the space is that we'll say things like "you own your own data", but it's not exactly true. Your data mostly exists as a series of tables in a database, which can be serialized into a JSON export that you mostly can't use with anything.

It might seem like this is a catch-all, where you can throw any old thing into the guiding principle. Maybe it is. What I know is this: if the experience is bad for users, if they're getting harassed and seeing drama every day, if they don't really have much control over the platform, if they can't find their friends or cool things that interest them, then your platform is the opposite of fun.

2. Users should have maximum agency

Building on top of Principle #1, individual users should have total agency of how their experience is shaped online. This can be categorized in four ways:

1. Visual / Conventional - the user decides what interfaces, themes, apps, and clients they will leverage to access the network. Custom designs and behaviors empower users to make their online space truly their own.
2. Data Sovereignty - the user has strict controls over their data: what apps and services can use it, the extent to which different pieces are exposed to the Web, and the ability to seamlessly port the sum of that data from one place to another.
3. Filtering and Connectivity - users should always be given the opportunity to decide what they see on their feeds, and what other people can see from them. This could take the form of filtering out keywords, blocking users and domains, leveraging a third-party labeling service, or being able to connect to individual accounts that may otherwise be banned instance-wide for everyone else.

Of course, this isn't to say that admins and moderators don't have a suitable place in community-building and curation. It's just that solely relying on them tends to result in communities where users have minimal input on policy, and admins have absolute authority. To me, this is a major barrier towards world-wide adoption of the Social Web, which is a goal for some of us in this massive, sprawling movement.

3. The platform must move the Fediverse forward

There's some absolutely amazing developments happening in the space. Most notably, the Fediverse Enhancement Proposals project has helped many different platforms standardize on undocumented behavior. It's the closest thing we have right now for improving ActivityPub implementations, in lieu of a formal update to the protocol spec.

FEPs are the reason why groups mostly just work across a variety of systems now, and related efforts such as the Threadiverse Working Group allows NodeBB, Discourse, Lemmy, PieFed, and Mbin to federate together with minimal issues. It's not perfect, but the project is bearing a lot of fruit.

The problem is that some of the biggest projects in the space, such as Mastodon, have historically been pretty indifferent to these efforts. Often, they choose to forgo established agreed-upon FEPs to do their own thing, forcing everyone else to bend over backwards and support their unique way of doing things. At the end of the day, FEPs still aren't advancements in the ActivityPub protocol itself.

We need more Fediverse platforms to champion these collaborative efforts, both to help influence further development of the protocol as well as putting pressure on larger projects to work with the community.

4.) The experience must be unique

This might come across as wildly conceited, but I don't want to build yet another clone of a service that already exists. I mean no disrespect towards the people doing that, but I think we've barely managed to scratch the surface of what can be built. There's a certain appeal in imitating existing familiar designs and paradigms, and iterating on them to be better.

What I want to do is develop new concepts that aren't quite like anything else. Sure, there may be a passing resemblance to half a dozen different things, but I want to develop something bold. I'm tired of describing the Fediverse as "the alternative" and want so badly to instead describe it as "the future", but we have to take much bigger risks to get there.

Implementation Details

Here are some of the pipe-dream ideas I've been refining over the years. There are probably a lot of aspects that still need key considerations, some of which is still above my ability to program! I'm currently going to school for Computer Science, and practicing to make my coding skills more capable of tackling these big ideas.

Composable Interfaces

This is probably the biggest idea behind Postmodern, the platform I hope to one day abuild. What are Composable Interfaces? To keep it simple: composable interfaces are a way to construct a custom frontend with whatever data is available.

Composable interfaces are not necessarily new; prior art exists in the following Fediverse projects:

• Hubzilla - You can write pages, a custom theme, and widgets using an elaborate template system. You have to write it yourself by hand, there's not really a way to preview these changes, and some of the more high-level customization has to be done by making calls to pieces of code that aren't super well-documented.
• Bonfire - Customization is largely accomplished through modules, which can be bundled together into a sort of unique software distribution. So, you can choose to add a group forum module, a wiki module, and a video module, and Bonfire will snap those pieces together for you. Super interesting, kind of complicated, still yet to be battle-tested for communities.
• Emissary- Really wild template system built on HTMX and HyperScript. Emissary is really different from other projects because it allows developers to dictate data schemas and actions from within the view template. A lot of contemporary developers might balk at this, because it kind of violates the MVC design pattern. However, Emissary is crazy flexible, and makes it possible for a developer to add support for custom Activity types and actions with a single template.
• Dokieli - a full-blown decentralized client-side editing tool. It implements ActivityPub, Linked Data, and a swath of other technologies related to Solid. It's extremely powerful, but the interface looks like it has a significant learning curve. It's hard even for me, a Fediverse nerd with 15 years of experience, to fully grok.

Looking at these concepts, I think Emissary and Dokieli come the closest to what I want to build. The ability to build a custom UI with unique capabilities just by dictating what the template is doing is awfully compelling.

My personal head-cannon differs in one specific way: take Dokieli, and marry its capabilities with that of Emissary. Focus on the page-building, widget-building, stream-building elements, and give people the power to delve into a vast pool of social data that they can edit client-side without having to touch any template code themselves.
Don't worry, this ugly thing is just a mockup. There's a lot to figure out.
Instead of taking inspiration from page-building tools like Gutenberg, Elementor, or Wix, my thoughts are to instead take inspiration from layer-based image editors. Each layer in the builder/inspector thing is a component, which can be altered, rearranged, and adjusted in a number of different ways. You can mix and match existing components, or compose your own from scratch by reaching into the pool of data that your account is aware of. It's not unlike the WordPress approach to Blocks in 2025...but, hopefully this approach can be more intuitive.
Again, this is just conceptual. A whole lot of things need refinement.
For this to be viable, a lot of work would need to be done to overcome any potential learning curve. The tools need to be accessible, with the page layout exactly matching what the user sees on the screen.The experience could really suck if it's not implemented carefully. After all, we have to follow the first guiding principle: it has to be fun. Fighting with an editing tool is not that.
I wanted to draw more widget ideas, but I need to finish writing this.
To accomplish this, the most straightforward approach would be to create a core set of widgets with data types and settings, bundled together for different experiences. I'm calling these bundles-of-things complications, which can be thought of as the snapping together of atomic units to make something greater. An experience that has a lot of complications put together would pretty much work as its own frontend made of stylized, curated pieces.

If this sounds way, way complicated: yeah, I know. For a social client frontend, this idea pushes a lot of boundaries. I have some ideas about how to get there (maybe use GraphQL for the builder?), but a lot of it is going to probably diverge from the standard Web application stack. I have a lot of homework to do.

Next-Gen Permissions System

I've written about this a bit before in my last article about moving the Fediverse forward, but we need to get our act together about permissions systems. Mastodon's offering is woefully lacking when it comes to granularity.
Sigh.
ActivityPub has these nifty things called Collections, which is really just a representation of a collection of objects. You can pretty much put any object in there, so in a roundabout way, you can create a scoped list of people you're connected with. Theoretically, you could use collections of people as privacy scopes, dictating who can see certain things, or certain versions of things.

Projects such as Bonfire have taken the logical next step, where it's possible to establish boundaries and barriers for different collections of people, under a variety of conditions. This can apply to everything from individual posts to group communities to whatever else you can come up with.

I think it's absolutely important that we build a system that not only accounts for message delivery and access, but capabilities as well. You the user should be the one that dictates whether people can see a post, boost it, reply to it, whatever. In a decentralized system, this is kind of hard to figure out, but not impossible.

I still hold the belief that Object Capabilities might be our best bet, and Christine Lemmer-Webber published a paper a few months ago detailing what oCap-enabled ActivityPub would look like.m

Data as Documents

Some people will disagree with me here, but I think a document database architecture might be the way to go for this whole thing. A traditional relational database might be too limiting for this kind of insane flexibility, especially when you consider how different platforms try to account for the complex data structures necessary for ActivityPub.

Pleroma, for example, historically used the jsonb data type in PostgreSQL to hold reams and reams of nested JSON data. At a small scale, it's not so bad, but ActivityPub data can grow exponentially when you're interacting with lots of people and content.

For some time now, I've been thinking a lot about Sir Tim Berners-Lee's Solid Project. When first approaching Solid, it seems super abstract and complicated. You get all these people talking about RDF, TripleStores, Quads, WebID, and a lot of other stuff. As someone that has a pretty firm grasp on Fediverse systems, Solid initially caused a vein to bulge in my temple. I went on to explain the semantics here.
A file manager, representing files in a Solid Pod
TL;DR: Solid is kind of a specification for data, data storage, and access. It allows users to store their data in pods, and that data is represented as different kinds of documents and metadata. There is no relational database. Instead, the data in your Solid pod is used as a database itself. If you wanted to migrate all of the posts you've ever made, Solid makes it super easy to pick all that stuff up and move it somewhere else.
An ActivityPods instance. All of these applications access the same pool of data.
ActivityPods manages to marry the two concepts, and does the heavy lifting to translate these documents and data into something ActivityPub implementations can understand, and vice versa. The real magic here is that ActivityPods makes the act of building ActivityPub apps relatively seamless and straightforward. Developers don't have to think about both ActivityPub and Solid. They just need to write an ActivityPub app.
Mastopod, an ActivityPub social app that uses Solid.
I still have some outstanding questions about whether ActivityPods can effectively scale up. The Solid community in general is pretty small, and ActivityPods is an even smaller subset of either Solid or ActivityPub communities. A large-scale community instance with over 100,000 users (who all individually have their own pods) doesn't feel that feasible to me.

Still, I respect everything these guys are doing, and I think about building on top of ActivityPods pretty often.

Relay-Based Supportive Infra

Fediverse instances suffer somewhat from a fragile network. In fact, I would go as far as stating that tethering user accounts to Fediverse instances is an antipattern. We've mistakenly followed this trend for a long time, and put the sum of a user's entire social graph into one server. If that server goes down for good, you're toast.
A Nostr client's network settings, showing many different relays.
Nostr doesn't have this problem, because it doesn't have instances. Instead, user accounts are free-floating, peer-to-peer identities that dispatch posts to individual relays. Instead of individual instances where everybody logs on to post, everything is done through clients. Your identity is basically a public key, tied to a profile and some posts.

What I'm advocating for isn't necessarily the prioritization of one method over the other, but a hybrid approach that includes the best of both. What if Fediverse identities could be free-floating, separate things from instances, that persist even when an instance goes down?

Suppose that the Move activity in ActivityPub was just a method for detaching the identity from one instance, and attaching to another? Or, taking the approach that Hubzilla takes, suppose that you could mirror your identity to multiple instances by attaching your identity to multiple servers? You post in one place, it shows up somewhere else, too.

Another way that relays could be useful is in attacking the notorious Discovery Problem so prevalent in the Fediverse. As Nostr has continued to evolve, different relays have emerged that specialize in specific things:

• Caching
• Hosting Media
• Search
• Premium Long-Term Storage

Theoretically, it could also be possible for relays to take on the role of Fediverse Discovery Providers. These things could not only act as an index of content and people, but conduits that pull in news, book reviews, events, and maybe even a contact directory. Maybe your instance could just subscribe to relays, rather than trying to broker message dispatching and pulling in new content itself.

A Single-Identity Ecosystem

Finally, we get to what I consider to be the Achilles heel of today's Fediverse. As highlighted in previous sections, I think we do a terrible job of handling identity. In fact, we don't really do any job at all.
Sigh
Part of the problem here is that every Fediverse server in the network is a full-blown platform, rather than a client. The decision of the Mastodon project was to forgo the Client-To-Server part of the ActivityPub spec, instead opting for a bespoke API of its own. Mastodon's API grew so popular that many other Fediverse platforms adopted it, just to have access to a vast amount of compatible apps.

The primary side effect of every Fediverse server being a platform instead of a client is that every platform needs its own account to be used. This quickly leads to a nightmare scenario where it's possible to have 15 different accounts floating around that don't actually connect to each other in any meaningful way.
Reimagining various platforms as client frontends instead, using the same profile.
Granted, the Client-To-Server API has its fair share of complaints. It's under-documented, clients are expected to handle all logic on the client side, and seemingly nobody uses it anyway. However...it still exists, can be improved upon, and could be used in conjunction with ActivityPods.

I'm greatly interested in the prospect of building ActivityPods apps that work with Postmodern, where you're really just viewing different crafted experiences in specific clients.

In Conclusion

Congratulations on getting to the end of my big, weird rant about how I'd do things. Some of these ideas remain unproven, and may not actually be the solutions I end up going with. Still, much of this exists as the byproduct of lessons learned from observing different Fediverse platforms evolve over time. I hope to start by building small prototypes to test out various ideas.

Some of this (all of it?) might be super convoluted and complicated. The biggest thing I want to focus on, however, is the experience of building composable interfaces. I think this idea really has legs, and could potentially be a radically different approach to building for the Social Web.

If you have any insights, ideas, suggestions, or critiques, please feel free to reach out! This article was, believe it or not, something of a shortlist. There's a lot of things I didn't discuss (Bluesky-styled labelers, custom feeds, etc) that still belong in this vision somewhere. For now, these are simply the topics most resonant to me, that I wanted to pay special attention to.