# SolidHaus — Technology Research Summary

**Date:** 2026-02-26

---

## 1. Solid Ecosystem (2026 Status)

### Libraries

| Library | Description | Status |
|---------|-------------|--------|
| `@inrupt/solid-client` | CRUD operations on Solid Pods | Stable v2.x |
| `@inrupt/solid-client-authn-browser` | Browser-based Solid authentication | Stable v2.x |
| `@inrupt/vocab-common-rdf` | Common RDF vocabulary constants | Stable |
| `rdflib.js` | Full RDF library (parsing, serialization, stores) | Stable, heavier |

### Solid Servers

- **Community Solid Server (CSS)**: Recommended for self-hosting. Written in TypeScript/Node.js, highly modular, active development.
- NSS (Node Solid Server): Older, being deprecated in favor of CSS.

### Key Findings

- Inrupt SDK is well-documented and suitable for read/write operations
- Solid Notifications (live updates) is still maturing — not suitable as primary sync mechanism
- For multi-user, use CRDT layer (Automerge) for real-time sync, Solid for long-term RDF archive

---

## 2. CRDT Libraries Comparison

| Library | Language | Data Types | Status | Notes |
|---------|----------|-----------|--------|-------|
| **Automerge** | Rust+JS | JSON documents, counters, text | Production | Best for structured data like inventory items |
| **Yjs** | JS | Map, Array, Text, XML | Production | Best for rich text, very performant |
| **Loro** | Rust+JS | Rich text, List, Map, Tree, Counter | Newer | Very promising, integrated tree CRDT |
| **SyncedStore** | JS | Yjs wrapper, plain JS objects | Beta | Easy integration with Svelte/Vue |

### Recommendation: Automerge

Automerge is the best fit for SolidHaus because:
- JSON document model maps naturally to inventory items
- `automerge-repo` provides ready-made sync infrastructure (WebSocket, IndexedDB storage)
- Conflict resolution is automatic and deterministic
- Offline-first by design — changes merge when reconnected
- Well-maintained, production-ready

### automerge-repo

The `automerge-repo` package provides:
- Document management (create, find, change, delete)
- Network adapters: WebSocket, BroadcastChannel, MessageChannel
- Storage adapters: IndexedDB, filesystem
- Sync protocol handling

```typescript
import { Repo } from '@automerge/automerge-repo';
import { IndexedDBStorageAdapter } from '@automerge/automerge-repo-storage-indexeddb';
import { BrowserWebSocketClientAdapter } from '@automerge/automerge-repo-network-websocket';

const repo = new Repo({
  storage: new IndexedDBStorageAdapter(),
  network: [new BrowserWebSocketClientAdapter('wss://sync.toph.so')],
});
```

---

## 3. Barcode Scanning Options

### Native (Capacitor)

| Plugin | Backend | Formats | Notes |
|--------|---------|---------|-------|
| **@capacitor-mlkit/barcode-scanning** | Google ML Kit | All 1D/2D formats | Recommended. Fast, reliable. Android + iOS. |
| **@capacitor/barcode-scanner** | OutSystems libs | All 1D/2D formats | Official Capacitor plugin. Also uses ML Kit/Vision. |

Both support: QR Code, DataMatrix, Code 128, Code 39, EAN-13, UPC-A, Aztec, PDF417, and more.

### Web

| Library | Size | Speed | Formats | Notes |
|---------|------|-------|---------|-------|
| **Barcode Detection API** | 0 | Very fast | QR, Code128, DataMatrix, EAN, UPC | Chrome Android/Desktop only. No Safari. |
| **html5-qrcode** | ~150KB | Good | QR, Code128, others | Standalone, no framework dependency |
| **@nicbright/web-barcode-reader** | ~200KB | Good | Many | Another ZXing wrapper |

### Recommendation

**Primary**: `@capacitor-mlkit/barcode-scanning` — covers Android and iOS natively.
**Web fallback**: Barcode Detection API (Chrome) → html5-qrcode (ZXing WASM) for other browsers.

Platform matrix:

```
Capacitor (Android) → ML Kit native     ✅ All formats
Capacitor (iOS)     → ML Kit native     ✅ All formats
Web (Chrome)        → Barcode Det. API  ✅ All formats
Web (Safari)        → html5-qrcode      ✅ QR + common formats
Web (Firefox)       → html5-qrcode      ✅ QR + common formats
```

---

## 4. SvelteKit + Capacitor (Mobile Strategy)

### Why SvelteKit + Capacitor

- **SvelteKit** provides file-based routing, SSR/SPA flexibility, excellent DX
- **Capacitor** wraps the SvelteKit SPA in native WebViews with full native API access
- Together: single codebase → web, Android, iOS
- Well-documented integration path (official SvelteKit docs, Capacitor docs)

### Setup Pattern

```
SvelteKit (adapter-static, SPA mode)
  → Vite build → /build/
    → Capacitor sync → Android/iOS native projects
      → Native APIs: Camera, Barcode Scanner, Haptics, Deep Links
```

Key config: `ssr = false`, `prerender = false`, `fallback: 'index.html'`

### Native Features Used

| Feature | Capacitor Plugin |
|---------|-----------------|
| Barcode scanning | @capacitor-mlkit/barcode-scanning |
| Camera (photos) | @capacitor/camera |
| Haptics | @capacitor/haptics |
| Deep links | @capacitor/app (App.addListener) |
| File system | @capacitor/filesystem |
| Status bar | @capacitor/status-bar |

### Alternatives Considered

| Option | Verdict |
|--------|---------|
| **NativeScript + Svelte** | Stuck on Svelte 4, not maintained for Svelte 5 |
| **Lynx (ByteDance)** | No Svelte support yet; only works with one framework currently |
| **Tauri 2 Mobile** | Supports SvelteKit, but more bleeding-edge than Capacitor for mobile |
| **PWA only** | Works on Android, limited on iOS (no custom URI schemes, limited deep links) |

### Desktop: Tauri 2 (Future)

Tauri 2 has official SvelteKit support and can build for Windows, Linux, macOS. Can share the same SvelteKit SPA codebase. Good option for a desktop companion app later.

---

## 5. URI Scheme & Deep Linking

### QR Code Content

Use HTTPS URLs as QR content: `https://haus.toph.so/{id}`

This works universally:
- Native app installed → App Links/Universal Links intercept → opens app
- PWA installed (Android) → Chrome intercepts → opens PWA
- Nothing installed → browser → landing page

### Custom Scheme (`haus://`)

Register `haus://` in Capacitor native app for direct launches. Works when native app is installed, but custom schemes have no fallback.

### Deep Link Handling in Capacitor

```typescript
import { App } from '@capacitor/app';

App.addListener('appUrlOpen', (event) => {
  const itemId = parseItemId(event.url);
  if (itemId) {
    goto(`/items/${itemId}`);
  }
});
```

### PWA Limitation

PWAs cannot register custom URI schemes. They can only handle HTTPS URLs within their scope on Android. iOS doesn't support PWA deep linking at all (as of early 2026). This is why Capacitor native is recommended.

---

## 6. NextGraph — CRDT-Native RDF (Future)

NextGraph is a research project that merges CRDT, RDF, and Solid concepts:

- **CRDT + RDF**: RDF graphs as CRDTs (OR-set / SU-set)
- **Integrated engines**: Embeds Automerge and Yjs
- **Triple store**: Uses Oxigraph internally
- **Solid-compatible**: Can expose data as Solid Pods
- **Features**: E2EE, P2P sync, SPARQL queries, offline-first

### Status (2026)

- Alpha stage, funded by NLnet/NGI (EU)
- Not production-ready
- Most promising option for a unified CRDT+RDF+Solid stack

### When to Adopt

If NextGraph reaches beta/stable:
- Could replace Automerge + Solid Pod with a single layer
- RDF would be natively CRDT-enabled (no separate sync + export)
- Monitor progress: https://nextgraph.org/

---

## 7. Additional Notes

1. **Svelte 5 runes** (`$state`, `$derived`, `$effect`) provide built-in reactive state management. No external state library needed — the reactive system is part of the language.

2. **Capacitor Haptics**: Use `Haptics.impact({ style: ImpactStyle.Medium })` on successful barcode scan for tactile feedback.

3. **IndexedDB via `idb`**: The `idb` library provides a clean Promise-based wrapper. Works well for offline storage. Automerge can use `automerge-repo-storage-indexeddb` alongside for CRDT doc persistence.

4. **Label PDF generation**: `jsPDF` + `bwip-js` (canvas-based QR rendering) → downloadable A4 PDF. Works entirely client-side, no server needed for label sheet generation.

5. **EAN/UPC product barcodes**: The scanner can recognize existing product barcodes. Future feature: look up product info from Open Food Facts or similar open databases to pre-fill item details.