Loading
Network error

Defining the domain

Started by linc in Agorakit : Users & developers December 13, 2025 10:43 PM

Agorakit has 2 levels of taxonomy today, Instances (the software installation) and Groups (a set of users).

Instances have:
  • Users (email-based identity)
  • Tags (global identifier)
  • Reactions (individual action)

Groups have:

  • Members (subset of Users)
  • Discussions
  • Files
  • Calendar Events
  • Maps

Users have 2 levels of taxonomy in their respective contexts: They can be an Admin of an Instance and/or a Group. This is tightly coupled to software permissions as an all-or-nothing switch in that context.

On to this we eventually want to layer complexities (like user badges, access controls, content formats, voting, moderation queues, & automation rules) that enable groups to self-govern with appropriate context. But, we want to limit conceptual complexity for folks approaching the software for the first time. To do this, it's important to consider how to create a simple facade that belies the potential complexity underneath so that it is discovered as it is needed rather than overwhelming at the outset. (Longer explanation: lenticular design)

An example of this is in traditional forums is using a "category" to not only have semantic value as a "topic" but also "taxonomy" (parent/child), "access" (permissions), and even "formatting" (markup & style). This sort of baggage or "semantic overload" can create flexibility without significantly increasing conceptual complexity. If you do this too much, it becomes hard to achieve your goals due to restriction. Too little, and you end up with "configuration bloat" with a million settings. Multiple forum solutions have also attempted something similar with plugins. Both of these examples have limitations which have been extensively explored and (imho) shouldn't be repeated, but they're instructive.

What I'm thinking about is: what other "primitives" will we need to accomplish our goals? And how to we use lenticular design to hide complexity in the right places?

My first draft:

  1. Add "Rules" — An instance-level way of defining things like access & automation.
  2. Add "Sets" — A way of grouping tags, reactions, or rules as being related or interdependent.
  3. Add "Forms" — A group-level way of adding hypermedia controls & validated input.
  4. Use "Attach" as a verb for semantically peering / linking two items (ex: "Attach a File to a Discussion", "Attach a Poll to a Calendar Event").

Here's a few examples:

  • A poll is a Form with Rules attached.
  • A badge is a Set of Tags attached to Users based on Rules.
  • A report/flag is a Discussion with a Tag with Rules attached, generated by a Form attached to Discussions.

Then when we approach filtering & sorting, it would be based on requesting a primitive class (e.g. discussions) filtered and/or sorted by attribute (date created) and/or attached primitive (e.g. a tag), done directly over hypermedia.

I have to stop there for the day and this idea is only 60% baked, but I thought I should start writing it "out loud" for feedback before I get too far.

December 13, 2025 10:46 PM

Implicit in all this is that I'm attempting to avoid adding more hierarchy and minimize its effect. I'm not anchored to the idea of avoiding things like parent/child relationships between groups or sets, but I'd rather start without it and see if we can get by.

December 13, 2025 10:48 PM

This is top of mind as I explore how to import a forum into Agorakit for the first time and wrestle with how something like a "poll" gets imported, if at all.

December 13, 2025 10:52 PM

Relatedly, I'm very interested in the idea of how you could export/import a set of tags, reactions, & rules between installations. "Want to set up your Agorakit to work just like mine for X mission? Import this [playbook] (XML file?) and it'll automatically configure it for you." Separating the "how it works" from the applications state and what groups exist feels like a valuable area to explore.

December 14, 2025 3:19 PM

You'll notice I'm not starting with a database schema for these things.

It's entirely possible that by modeling things this way, we'll end up creating some annoying schemas or denormalizations.

I'm purposefully prioritizing communication clarity over implementation. I think one of the biggest pitfalls a software project call fall into is a developer short-handing their thoughts directly into a relational database schema and inadvertently pouring implementation concrete before the idea was even full cooked.

It's not that you shouldn't have that thought at the back of your mind and use it to steer away from really bad implementation outcomes, but anchoring to it as top priority is just as bad.

December 14, 2025 7:11 PM

(bit of a tangent about Tags adding value by becoming load-bearing)

"How would I split a group?" is a question I was thinking about as I considered a migration, because you may end up with a structure that doesn't make sense as 1 big group. In my mind, the most elegant answer to that question is "by tag". Because not only is that a generically useful way to let a group divide itself if it got too big organically, but during an import you could see lots of topic areas getting dumped into 1 group and wanting to split them.

In Vanilla, we allowed you to individually select discussions to "move" to a new category. On one hand, checking a box for a mass-move action feels efficient, but it's also a cumbersome level of granularity to worry about when you think about how it feels to actually do that. Like, I gotta search for this term (or multiple terms), page through a bunch of discussions to find the ones I care about, and individually select them RIGHT NOW, and then move them all, and then it's "done" and that they were part of this batch is forgotten.

But, if you let Tags have "baggage" from Rules, you could say "If a discussion gets tagged X, Y, or Z, move it to this group". Now you're not doing a "throwaway" action to select it, you're adding semantic value of a Tag that persists with a discussion but for now the only outcome is that it moves. Curation & discoverability like this is a huge issue in long-running communities (imo), so any time there's an elegant way to nudge it back towards enriching data with information like this permanently it feels like a (small) win.

December 14, 2025 10:46 PM

Lot of great stuff here! quick things that came to mind : 

I think I already read about lenticular design quite some time ago, and I fully agree to keep things simple at least on the surface. At least I tried to do this since the beginning. But there is much more to it if we want to better model the way people interact.

The limited hierarchy Agorakit provides came from my experience that people have a hard time handling trees and even when they do, everyone has a different way of organizing things. Do you put this meeting minutes in department/meetings/2025 or in 2025/department/meetings or was it meetings/2025/department? Things like that :-)

I love tagging but most people don't use it that much. Maybe it's a feature that would benefit from lenticular design (more help, unfoldable explanations, suggested tags with auto tagging, additional ui for tag management...) 

Also, my initial idea of groups was : a virtual representation of existing groups of real people who sometimes gather irl.

This makes it easy to understand. Your group (school parents, game players, activists,...) can also be online, you can discuss, share files, plan events. 

Adding to this : "your group has rules" would be easy to grasp.

"Your group has it's vocabulary (also as a way to organize)" is probably also easy to understand.

I think it's always nice when it mimics real life.

Maybe I went sometimes too fast to the route : one kind of things = one table, at least it's easy to understand. Time will tell if it holds :)

14:22

I think the IRL metaphor is a good one to hold onto for what the core items / primitives should be. I don't want to displace those things, but rather allow the Web to enrich it a bit.

I have no issue with core items being 1:1 with tables as they exist today; I'm mostly just trying to say as we get into complex things, it would be helpful to differentiate between new core items that should continue to do that and "second tier" things that are really just remixes of core items. Sort of like Minecraft recipes I suppose.

I agree many people are quite bad with folder structures and also tag unreliably. I am thinking about pushing 'tags' less as a thing each user needs to apply to their posts (like topics), than as a management tool we use more behind the scenes when we need to group or identify specific items from among many.

You've read everything in this discussion