# Bricks as a social network: spaces, followers and the Fediverse

## Bricks Technical Documentation

*How an organisation becomes a space that people follow from Bricks and from Mastodon, how it publishes to its followers or only to some of its roles, what a person reveals by following, and the workflow nodes that decide all of it.*

---

## 1. What it is

Every organisation on Bricks can be a **space**: something people follow, that publishes posts and receives replies. People follow it from **BricksID**, from a "follow us" button in the organisation's own application, or from **Mastodon** and any other server of the [Fediverse](https://www.w3.org/TR/activitypub/), since Bricks speaks **ActivityPub**, the open protocol those servers share.

Spaces talk to each other over the same protocol, so one organisation never reads another's data. A space holds only what was delivered to it, in its own database.

The protocol, the signatures and the privacy rules are platform code. The **social rules are yours**: who may follow, what following grants (a role, a newsletter, nothing), how replies are moderated and what gets published are workflows of your organisation, built with Studio AI like any other.

```mermaid
flowchart LR
  P["A person in BricksID"] -->|follows| S["Your space"]
  M["Someone on Mastodon"] -->|follows| S
  O["Another Bricks space"] <-->|follows, replies| S
  S -->|"public or followers-only posts"| M
  S -->|"posts to roles<br/>(never leave Bricks)"| P
```

## 2. Nothing is published until someone chooses to

- **A space is off by default.** An organisation admin turns it on in **Settings › Fediverse**. While it is off, other servers cannot find it, its inbox refuses everything and the publishing node refuses to send. Turning it on publishes nothing: only your workflows publish.
- **Sending outside Bricks needs a signed data flow.** Reaching followers on other servers needs the space's Fediverse data flow, declared in Settings › Fediverse and signed by a person under Integrations › Data flows, like every outbound flow ([Data flows](/technical/data-flows)). Without it, posts still reach Bricks people and other Bricks spaces, and nothing leaves.
- **A person is invisible from outside until they turn a public profile on**, in BricksID › Social network. Their profile then shows their handle, their name only if they chose to show it, and the featured apps they chose one by one. A person does not post in their own name: posts come from spaces.

Following a space and turning a public profile on need the person to be covered by the BricksID fee. Withdrawing never does: unfollowing, turning the profile off, hiding the name, removing items from the feed.

## 3. What a person reveals by following

Following is consent, recorded as a BricksID **mandate** the person gives and can withdraw. The person sees it with their other mandates in BricksID.

| Who learns it | Given by | What they learn | Withdrawn by |
|---|---|---|---|
| The organisation whose space is followed | Following it, from BricksID or from the organisation's app | The person's BricksID user id and name | Unfollowing, or revoking the mandate |
| The Fediverse | Turning the public profile on | The handle, the name if chosen, the featured apps chosen | Turning the profile off |

What this means for your workflows:

- The inbox trigger gives you `actorUserId` and `actorName` **only while the person's follow mandate is live**. Without it, your workflow cannot tell which BricksID sent an activity, so it cannot give that person a role.
- If the person suspends the mandate, your space stops learning who they are until they resume it.
- Closing a BricksID account ends every follow and revokes every mandate.

**Never published, by anyone:** who holds a role, who follows a space, whom a space follows, and how many of each. Your followers' collection is empty to the outside world. A space for political, religious or union discussion must not reveal its members' opinions (GDPR article 9).

## 4. Who a post reaches

Every post is addressed to an audience, and the publishing node **refuses**, never narrows, a post that breaks these rules, whoever wrote the workflow:

| Audience | Reaches | Leaves Bricks? |
|---|---|---|
| **Public** | Everyone, and your followers everywhere | Yes, with the Fediverse data flow |
| **Followers** | Your followers, in Bricks and on other servers | Yes, with the Fediverse data flow |
| **Roles** of your space | The people holding those roles now | **Never** |

- A post addressed to roles never leaves Bricks. Roles are held only by BricksID accounts, so its readers are Bricks people by construction. Mixing roles with the public, the followers or an outside account is refused.
- A reply or a share is never addressed wider than what it answers or shares.
- No direct messages: a post addressed only to named accounts is refused. Use [private messages](/technical/messages) for that.

People in Bricks see posts in their feed in BricksID › Social network straight away. Something sent from outside Bricks (possible only to a person with a public profile) waits there until the person chooses to show it.

## 5. Addresses

A space's handle is `@<organisation slug>@<Bricks host>`, the form Mastodon users type in their search box. A person's handle is the one they chose in BricksID. Behind the handle, every address carries the organisation's or the person's id, never the slug, so renaming the organisation does not lose its followers.

A space appears on other servers as a group that approves its followers itself (`manuallyApprovesFollowers`): a Mastodon user sees "follow request" until your workflow accepts.

## 6. The workflow nodes

| Node | What it does |
|---|---|
| `trigger-activitypub-inbox` | Starts a workflow when an activity reaches your space: a follow, an unfollow, a reply, an edit, a deletion, a like, a share, a post from a space you follow. Filter with `types`, e.g. `["Follow"]` or `["create", "update", "delete"]` |
| `data-activitypub-build` | Turns a row into an activity: a post (a short Note, or an Article when titled or longer than 500 characters, with categories as hashtags and media as attachments), its edit or deletion, or a follow, an accept, a reject, a like, a share or an undo |
| `action-activitypub-deliver` | Signs and sends it. Bricks recipients get it at once; outside servers are queued and retried. Enforces the audience rules above |
| `action-activitypub-fetch` | Reads a post or a profile from another server, signed, under the Fediverse data flow |
| `data-activitypub-parse` | Checks and normalises an incoming activity. Remote HTML comes back reduced to paragraphs, line breaks and links; everything not understood is listed in `notUnderstood` |

The trigger's output: `inboundId`, `branch`, `type`, `activityId`, `actor`, `actorDomain`, `local`, `actorUserId`, `actorName`, `actorTenantId`, `objectId`, `isReply`, `toThisSpace`, `follow`, `activity`, `raw`.

None of these nodes writes your tables. What your space keeps (replies awaiting moderation, followers who got a role) goes in tables your organisation declared, through the usual data nodes. The content other servers send is never copied into your workflow's run history.

### Accepting followers

The minimal workflow: accept every follow request, and give the person a role when they are a Bricks person who agreed to be known.

```mermaid
flowchart LR
  T["trigger-activitypub-inbox<br/>types: Follow"] --> R["action-assign-tenant-role<br/>(only when actorUserId is set)"]
  R --> B["data-activitypub-build<br/>Accept"]
  B --> D["action-activitypub-deliver"]
```

```json
{
  "id": "accept",
  "type": "data-activitypub-build",
  "data": {
    "activityType": "Accept",
    "target": "{{ $node.trigger.follow }}",
    "actors": ["{{ $node.trigger.actor }}"]
  }
}
```

### Publishing a post

```json
{
  "id": "post",
  "type": "data-activitypub-build",
  "data": {
    "activityType": "Create",
    "rowId": "{{ $node.article.id }}",
    "title": "{{ $node.article.title }}",
    "text": "{{ $node.article.body }}",
    "language": "fr",
    "hashtags": "{{ $node.article.categories }}",
    "public": true
  }
}
```

Deliver it with `action-activitypub-deliver` (`"activity": "{{ $node.post.activity }}"`). The object's address comes from `rowId`, so building an `Update` or a `Delete` with the same `rowId` edits or removes the same post on every server. For members only, replace `"public": true` with `"roles": ["member"]`: the post stays inside Bricks.

You rarely write this by hand. Ask Studio AI: "publish each new article to our followers", "let members of the club follow us and give them the follower role".

## 7. A "follow us" button in your application

Applications built on Bricks call `followUs()` from the app SDK. It opens the BricksID follow window over your app, like a sign-in. The window tells the person that following shares their BricksID and name with your organisation, and they follow by their own click.

```ts
import { followUs } from '$lib/bricks';

const result = await followUs();
// { ok: true, state: 'accepted' | 'pending' }
// { ok: false, reason: 'declined' | 'closed' | 'popup_blocked' | 'unavailable' | 'error' }
```

The space followed is always your application's own organisation; the app cannot name another one. `pending` means your follow workflow has not accepted yet; `unavailable` means the space is off. The answer never says whether the person has paid the BricksID fee, and your app never writes a follow or a mandate itself.

## 8. Protection against abuse

Before anything is stored or any workflow runs, an incoming activity must:

1. be addressed to a space or person that is on the Fediverse;
2. come from a server that is not on the platform's blocklist;
3. stay within the rate limits, per recipient and per sending server;
4. carry a valid HTTP signature, checked against the key its own server publishes.

Then it is stored once, whatever the number of recipients, and the sender gets its answer within 5 seconds. No visitor's IP address or user agent is read or stored. Outgoing deliveries are capped per space and retried with growing delays, so a busy space never slows another down.

Signing keys are created per space and per person. A published public key is never deleted, so a post signed today still verifies years later.

## 9. Today's limits

- A person follows Bricks spaces only, not accounts on other servers, and posts only through spaces.
- A space follows an outside account only through a workflow, not from a screen.
- Followers-only posts are delivered to followers' servers but cannot be fetched again from Bricks; public posts can.
- No direct messages and no polls.
- Federation is tested end to end against one other implementation (GoToSocial); a second is planned.
