Real Life Stack

A modular toolkit for local connection

Local communities need digital tools that foster real-world encounters instead of replacing them. Real Life Stack is a modular toolkit that lets communities deploy their own apps for local networking and adapt them to their needs.

Tools that enable communities to organize in a decentralized way – self-determined and rooted in real-world encounters.

---

The Problem

Local initiatives are becoming key actors in tackling social and ecological challenges. Yet:

• Established platforms are optimized for attention and reach, not for local collaboration
• Small initiatives lack the resources to build their own systems
• Missing infrastructure forces communities onto platforms that control their data

The Solution

Real Life Stack provides a shared technical foundation:

• Modular UI toolkit – map, calendar, groups, profiles, feed as reusable components
• White-label app – ready to use, customizable without programming skills
• Backend-agnostic – connector architecture for REST, local-first, P2P, or E2EE
• Trust-based identity – a Web of Trust built through real-world encounters

---

Architecture

┌──────────────────────────────────────────────────────────┐
│                           UI                             │
│   ┌──────────────────────────────────────────────────┐   │
│   │                   App Shell                      │   │
│   └──────────────────────────────────────────────────┘   │
│   ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────┐   │
│   │ Kanban │ │Calendar│ │  Map   │ │  Feed  │ │ ...  │   │
│   └────────┘ └────────┘ └────────┘ └────────┘ └──────┘   │
├──────────────────────────────────────────────────────────┤
│                      Hooks (thin)                        │
├──────────────────────────────────────────────────────────┤
│                     DataInterface                        │
├──────────────────────────────────────────────────────────┤
│                      Connectors                          │
│    ┌────────┐ ┌───────────┐ ┌────────────────────────┐   │
│    │  Mock  │ │ GraphQL   │ │   WoT (CRDT+E2EE)      │   │
│    └────────┘ └───────────┘ └────────────────────────┘   │
└──────────────────────────────────────────────────────────┘

App Shell

The App Shell is the global frame: it hosts navigation, the current space, and the surfaces that all modules share.

Space Modules

Space Modules (Kanban, Calendar, Map, Feed, ...) are surfaces that can be enabled per space. Each group chooses which Space Modules it uses. Space Modules do not only check the item type but also which data fields are present (status → Kanban, start/end → Calendar, position → Map).

Hooks

The hooks are a thin layer between UI and connector — they translate observables into React state and mutations into promises.

DataInterface

The DataInterface defines the read-only core contract: reading items and observing them reactively. Additional abilities such as writing, groups, identity, or relations are detected via capability interfaces (ItemWriter, GroupManager, Authenticatable, ...). UI surfaces only know these interfaces, never the backend.

Connectors

Each connector implements the DataInterface and only the capabilities its data source supports. The MockConnector (in-memory) is used for development, the LocalConnector for local IndexedDB persistence with cross-tab sync, the GraphQL connector for classic servers, and the WoT connector (Yjs/CRDT + E2EE) for decentralized, encrypted collaboration.

---

Neighbouring Repositories

The organisation-wide picture, the seams between the repositories and the term register live in the meta repository: real-life-org/meta. The stack ends at the connector; what a backend provides below it is declared through capabilities, see Connectors.

Real Life Stack does not own the social or game semantics. It makes them displayable and usable as a backend-agnostic UI and connector layer. The social meaning comes from the Real Life Network Protocol, the optional game semantics from the Real Life Game. Details: docs/concepts/rlnp-game-integration.md.

---

Specification

The normative core of the repository lives in docs/spec/ — it is the single source of truth. When spec and implementation conflict, the spec wins. The core documents 00–10 cover architecture, app composition, the DataInterface, capabilities, items/relations/groups/spaces, confirmations and trust, schema composition, tags, relation records, the mirror bridge, and the activity log.

Machine-readable vocabularies (JSON-LD contexts + JSON Schemas) live in docs/spec/schemas/: base, place, event, task, person, relation, project, and resource.

Space Modules

Binding Space Module specs live in docs/spec/modules/. Their shared building blocks (ItemPreview, FilterBar, CreateFab, ModulePanel, …) are defined in shared-components.md and implemented in the reference app. The older folder docs/modules/ contains early brainstorming and serves as inspiration only.

Space Module	Status	Description
Feed	Draft v0.1 + implemented	Activity stream across all Space Modules: what is happening in the community?
Kanban / Tasks	Draft v0.2 + implemented	Organize tasks and workflows within a space
Calendar	Draft v0.1 + implemented	Plan events, coordinate dates, manage invitations
Map	Draft v0.2 + implemented	Visualize local places, resources, and activities on a map
Marketplace	planned	Make offers, needs, resources, and possible matches visible
Quests	planned	Show quest overview, quest log, quest runs, evidence, and completion status
Campaign View	planned	Display adventures, campaigns, and world state as a game view

---

Who Is It For?

• Neighborhood networks and urban gardening groups
• Repair cafés, food-sharing initiatives, community-supported agriculture
• Youth groups and free learning spaces
• Sharing and swapping communities
• Organizations that support local groups

---

Demos

Demo	Description
Landing Page	Project overview and entry point
Reference App	Implementation with all modules
UI Prototype	Experimental UI concepts and components
Storybook	Component documentation
Web of Trust	Demo for decentralized identity, verification, attestations, and sync

---

Web of Trust

Web of Trust is the protocol and reference layer for decentralized identity, contacts, verifications, attestations, and encrypted sync. Real Life Stack can use these abilities via the WoT connector while staying backend-agnostic.

• Decentralized identities – experiments with did:key and Ed25519
• Web of Trust – QR-code-based verification, JWS signatures
• Local-first – Yjs as the default CRDT, Automerge as an alternative CRDT option
• Modular architecture – AppShell pattern for different apps

Landing page → | Demo → | GitHub →

---

Developer Documentation

How to propose a concept, contribute code and run the checks: CONTRIBUTING.md.

Monorepo Structure

real-life-stack/
├── packages/
│   ├── data-interface/    # @real-life/data-interface - TypeScript types + capabilities
│   ├── mock-connector/    # @real-life/mock-connector - in-memory implementation
│   ├── local-connector/   # @real-life/local-connector - IndexedDB + cross-tab sync
│   ├── supabase-connector/ # @real-life/supabase-connector - Supabase backend
│   ├── wot-connector/     # @real-life/wot-connector - WoT/Yjs/E2EE
│   └── toolkit/           # @real-life/toolkit - UI components + hooks
├── apps/
│   ├── landing/           # landing page
│   ├── reference/         # reference app (React 19)
│   ├── network/           # network app (relation records, network graph)
│   └── prototype/         # UI prototype (experimental)
└── docs/                  # documentation
    ├── spec/              # normative spec (00–10, modules, schemas)
    ├── modules/           # early module brainstorming, inspiration only
    ├── concepts/          # concept documents
    ├── archive/           # historical, no longer normative documents
    └── funding/           # funding application

Quick Start

# Install dependencies
pnpm install

# Start the reference app
pnpm dev:reference

# Start the landing page
pnpm dev:site

# Build the toolkit
pnpm build:toolkit

DataInterface & Connectors

UI surfaces work against the DataInterface and optional capability interfaces — TypeScript contracts that abstract data, reactivity, write access, groups, and identity. Connectors implement these interfaces for different backends.

@real-life/data-interface

Pure TypeScript types and shared helpers (no external runtime dependencies):

import type { DataInterface, Item, Group, User, Observable } from "@real-life/data-interface"

@real-life/mock-connector

In-memory implementation with demo data for development without a backend:

import { MockConnector } from "@real-life/mock-connector"

const connector = new MockConnector()
await connector.init()

const tasks = await connector.getItems({ type: "task" })  // 12 demo tasks
const groups = await connector.getGroups()                  // 4 demo groups

// Observe reactively
const obs = connector.observe({ type: "task" })
obs.subscribe((tasks) => { /* live updates */ })

Spec entry point: docs/spec/README.md. Architecture details: docs/spec/00-architecture.md

@real-life/toolkit

The toolkit package exports reusable UI components:

import { Button, Card, Avatar, Tabs } from '@real-life/toolkit'

View Storybook →

# Start Storybook locally
pnpm storybook

# Build Storybook
pnpm build:storybook

Tech Stack

• TypeScript + React 19
• Tailwind CSS v4
• Radix UI Primitives
• CVA (class-variance-authority)
• Vite

---

Together we shape the future – locally connected, globally minded.