Architecture

FreedomCore is three layers designed as one system. The layers cannot be separated without losing what makes the platform work.

The Three Layers

┌──────────────────────────────────────────┐
│        FreedomDesktop (Orchestrator)     │
│  TPA Panels · Data Bus · Collaboration   │
│  CSS/JS Injection · Recipes · Video      │
├──────────────────────────────────────────┤
│        FreedomCore (Trust)               │
│  Identity · Certificates · Groups        │
├──────────────────────────────────────────┤
│        FreedomMesh (Network)             │
│  Encrypted P2P · Lighthouse · Relay      │
└──────────────────────────────────────────┘

Desktop knows WHO (identity, trust level, group membership), WHAT (which TPA panels, which data fields, which actions), and orchestrates third-party apps via CSS/JS injection.

Core knows WHY (trust certificates, introduction chains, professional verification).

Mesh knows WHERE (geo identity, network path, latency) and HOW (encryption, peer discovery, relay).

Together they know everything needed to make a trust decision and bridge data across apps and peers. No other product combines all three.

Why One System

If the network and the app are separate products, you end up rebuilding Slack on top of Tailscale. Two things duct-taped together. The network doesn’t know about the app’s trust model. The app doesn’t know about the network’s encryption.

When they’re one system, the mesh only carries FreedomCore application traffic between FreedomCore endpoints. The Nebula firewall enforces this at the crypto layer. A compromised third-party app on the same device cannot piggyback on the mesh.

This is A2A: the application IS the security perimeter.

The Mesh (Nebula)

At the network layer, FreedomMesh uses Nebula — a peer-to-peer mesh VPN originally built by Slack.

• Peer-to-peer first. Traffic flows directly between devices whenever possible. 3ms latency on LAN, 65ms to a lighthouse across the continent.
• Encrypted. All traffic uses the Noise protocol (X25519 + ChaCha20). Lighthouses see connection metadata, never payload.
• Certificate-based. Access control is cryptographic. Groups are baked into certificates. You cannot join a group your certificate doesn’t list.

Lighthouses

Each group runs their own lighthouse — a small binary on a Raspberry Pi, a $5 VPS, or an old laptop.

The lighthouse serves three roles:

1. Discovery — helps peers find each other’s IP addresses
2. Relay — forwards traffic when direct P2P fails (~10-15% of connections)
3. Trust anchor — holds the certificate authority for the group

FreedomCore operates public lighthouses (Toronto, Sydney) for bootstrapping and guest access. But in production, every group runs their own. FreedomCore has zero visibility into group traffic.

The Dissolving Workspace

The architectural concept that ties everything together:

1. A professional creates a workspace (“123 Main St” real estate deal)
2. Participants are invited via link or QR code
3. Each participant gets a certificate scoped to that workspace
4. FreedomDesktop loads the same TPA panels for all participants — MLS, assessment, maps, documents
5. Data bridged between panels, shared across peers in real time
6. All traffic is peer-to-peer through the group’s lighthouse
7. When the deal closes, certificates expire, the workspace dissolves
8. Nothing persists on any server. Audit logs stay with the group leader.

This is not a network segment — it’s an application context. Participants see panels and data, not topology. The VPN tunnel is as invisible as TCP/IP is when you open a web browser.

Connection Architecture

PRIORITY 1: Direct P2P (UDP hole-punch)
  You ════════════════════════ Peer
           ~3ms LAN, ~65ms WAN

PRIORITY 2: Via Lighthouse (relay)
  You ──── Lighthouse ──── Peer
           ~100ms

PRIORITY 3: Browser Gateway (WebRTC)
  Browser ──── Lighthouse ──── Peer
           Zero install, guest access

Every connection attempts direct P2P first. Falls back to lighthouse relay. Browser guests connect via WebRTC — zero install, close the tab to leave.

Edge Security (Cloudflare)

First contact happens at Cloudflare’s edge, before any traffic reaches a lighthouse.

Visitor → Cloudflare Edge (300 locations)
       → Visitor scoring (geo, ASN, bot detection)
       → Turnstile challenge (if low score)
       → Astro SSR on Cloudflare Pages
       → Guest Pass API
       → Nebula Mesh (pre-vetted traffic only)

Cloudflare provides passive intelligence on every request: IP, country, city, ASN, IPv6 prefix, bot score, TLS fingerprint. This data feeds the geo identity system without requiring the user to do anything.

Technology

Layer	Technology	License
TPA Orchestrator	Go + Wails v3 (target)	MIT
Network	Nebula (Go)	MIT
Encryption	Noise protocol (X25519 + ChaCha20)	—
macOS mesh	Swift/SwiftUI + Network Extension	—
Website	Astro SSR on Cloudflare Pages	—
Edge security	Cloudflare D1, KV, Turnstile	—
Geo bridge	libnebulamesh.a (Go CGo)	MIT
Frontend	Vanilla HTML/CSS/JS (no framework)	—

Everything is built on proven, open-source foundations. The TPA orchestration layer and trust model on top are what make it new.