Spitballing an introductory article on Holochain's architecture --- feedback requested!

Hello all! As part of our work to publish a series on core concepts you need to understand in order to build Holochain apps, I’ve been playing around with a metaphor that the core devs invented back in May: the ‘Holonut’. Does this work well for explaining Holochain? Is it easy to understand? Does it introduce new understanding and/or confirm stuff you already understood? Does the humour add or just detract?


2: Application architecture

Applications built with Holochain are highly modular in both functionality and architecture. This makes it easy to share code and compose smaller pieces together into larger wholes. Each Holochain application (called hApp) has its own set of rules, private network, and distributed database.

Agent-centric integrity: inside, outside, and in between

Before we talk about the tech stack, let’s talk about donuts. That’s a good way to start, isn’t it?

This is Holochain. It’s ring-shaped. Thanks to the magic of gluten, it has enough integrity to hold itself together. It separates the universe into two empty spaces: the hole and the space beyond.

On top of Holochain is your application. Each application has a different flavor.

Let’s put you inside the hole. You have agency — the power to receive information from your world and act upon it. Together, your copy of the Holochain runtime and your application mediate between you and Holochain land.

On the outside of the ring is a shared space. In it are other people, also using the same application. Holochain mediates interactions with them too, shuttling information across space with the help of a computer network.

Holochain creates a ‘double membrane’ for each participant, bridging between their world and the digital space they share. It guarantees the integrity of data passing through it on both the inside and the outside. This lets people safely do the things that are important to them, without having to depend on a central authority.


I like the graphics and the humour.
I am not sure though, if the metaphor makes it easier for me to understand Holochain. The hole inside still feels a bit intangible, since it kind of leaves the metaphoric language of dough and icing behind.

PS: Damn you, Paul. Now I crave for a doughnut! :face_with_raised_eyebrow:

1 Like

Yeah agree with this Paul, we see the doughnuts as DHTs and the double headed arrows as bridges. The membrane aspect makes the bridges very effective firewalls.

Being inside the :doughnut: is also true, although haven’t fully appreciated this since RedGrid is a part IoT play so doesn’t need humans to work

1 Like

How it would look like if the metaphor was with Earth (my world) and the different layers of atmosphere (Holochain/applications) and my connection with others planets/stars (other agents). :

There is no gluten joke in this though… But ozone could be the gluten :slight_smile:

What the metaphor of Holochain would look like in this context of Earth/Atmosphere/Planets ?
Is it working ?

Not sure that it is creating clarity for me, especially since hanging out a bit with doughnut economics, the inside feels a lot like a collective space to me.

I did a sketch around trying to explore Shiro and Holochain in a perspective of Holochain

It facinated me to think about how pulling the doughnuts through time makes tubes (naturally makes me think of hyphae). Not sure it is helpful, but funny to see doughnuts getting to be center of such prominent conversations :smile:


@pauldaoust the stuff in green in the section after the doughnuts, in the linked version, was really helpful for me. I had not gotten around to figuring out where to get that kind of quick overview of the architecture.

One further question after the last diagram: Then one agent (user) can have more than one conductor stack for different apps that they are part of? I assume so, but that would be a good addition.


@jakob.winter thank you; that’s just the sort of feedback I was hoping to get. Apologies for triggering your calorie-gathering instinct :wink:

@mikeg oh interesting; never thought of DHT-as-donut! It’s, like, fractal donuts. Along with what @ViktorZaunders is saying about extruding the donut through time to get a tube, it feels like we’ve stumbled across some sort of ‘sacred geometry’ principle :joy: I know the donut shows up in Bill Mollison’s general core model too (check out the upper right corner). Mostly kidding, but still, interesting!

@Alexis the earth is a very interesting metaphor — the annoying thing about the ‘Holonut’ is that topologically it doesn’t really separate the inside from the outside cuz you could just jump over the dough bit. Whereas the atmosphere really does separate the earth from the universe in a meaningful way. Thoughts on that:

  • Magnetosphere and atmosphere are definitely a membrane that blocks meteors and gamma rays and allows ‘valid’ things (like sunlight) through. Not sure about the reverse though — does the atmosphere mediate things going out as well?
  • Multiple planets in one solar system is a good metaphor for the DHT, and interstellar rockets travelling between solar systems could be a good metaphor for bridging between DHTs.

@ViktorZaunders could you describe more about what’s going on in your own donut? How would you describe the spaces inside and outside?

@lynnfoster glad the green boxes diagrams help! It is true that one agent could have more than one conductor stack for different apps, but it’s an ‘unspecified’ scenario. It wouldn’t cause problems (as long as you set separate gossip ports for each conductor), but because one conductor can host DNA instances for many agents (similar to vhosts in Apache or Nginx) it’s not terribly necessary either.

I agree, hadn’t looked in the linked document since I thought it would all be copied over. Those illustrations are real nice @pauldaoust

Sure, with a caveat though that they aren’t so much a worked through thing as a late night exploration that I was just doing one night.

I started going into it in the thread here, but I got so into it all that I properly documented it and didn’t want to hijack the whole thread, so here is a link to the thinking that went into the sketch. :wink:

Basically it is trying to explore, why build Shiro? through a modified version of doughnut economics and listing a bunch of flows we would be interested in working with.


@ViktorZaunders ahh, thanks for that, and for introducing me to doughnut economics. (I’d heard about it before but never looked into it.) Makes sense now, and I like how you expand the idea of “respecting external constraints” to “enriching external systems”.


My pleasure, also if you want a short and great introduction straight from Kate Raworth (along with an also great presentation of why we have broken economics from Joe Brewer), I very much recommend this large nugget of insight:


I’d highly recommend Raworth’s book in Doughnut Economics too. In fact, I just finished it after coming across it elsewhere. Great to see such a convergence of ideas and values!

1 Like

haha, don’t worry, we’ll work in the golden ratio and Fibonacci sequence soon :wink:

And some spirals and mandalas for good measure :wink:

Humm… not a fan of the doughnut metaphor to rep Holochain — let’s try the opposite of artificial and go w something natural, shall we?Holochain is based on living systems and a doughnut does nothing but introduce more acid into the human gut and invite cancer! It’s hardly gonna inspire a designer like me to build a h’app. Maybe we could borrow a page from either Richard Saul Wurman, the father of information architecture or from Christoper Alexander, an eco architect whose book on PATTERNS inspires millions—to find a solution to this problem. We need to take this “finding the architecture metaphor thing” through a process in order to arrive at the deep structural beauty of Holochain, of that I am sure…