Styrene Organic Documentation

Summary: The molecular metaphor mapping Styrene components to polymer chemistry. Defines atoms (protocol components), polymers (reference architectures), and current implementation status.

Research compilation for Styrene project documentation, naming conventions, and deployment strategy.

1. The Styrene Metaphor: Molecular Architecture

1.1 Core Concept

Styrene (C8H8) serves as the conceptual foundation for the project’s naming and architecture. The molecule—a benzene ring (C6H4) bonded to a vinyl group (C2H4)—maps directly to the distributed network stack:

• Individual atoms represent core protocol components
• The molecule represents a complete styrene node
• Polymers represent network topologies and reference architectures

1.2 Component Breakdown: The Atoms

Carbon Atoms (6) — Core Network Components

Hydrogen Atoms (8) — Ecosystem Applications

2. Polymer Reference Architectures

Each polymer maps chemical properties to network topology characteristics.

2.1 Polystyrene (PS) — Hub-and-Spoke

Chemistry: Rigid, transparent, brittle; linear chain polymer

Network Topology:

        [Hub]
       /  |  \
    Dev1 Dev2 Dev3

Properties:

• Centralized authority (Hub is SPOF)
• All traffic visible to Hub
• Low latency, predictable paths
• Scales linearly, throughput degrades

Use Case: Small fleets (<50 devices) with reliable LAN connectivity

2.2 Expanded Polystyrene (EPS) — Distributed Mesh

Chemistry: Foamed structure; lightweight, fills space efficiently, good insulation

Network Topology:

[PropNode1]        [PropNode2]
    |  \  /|          |  \  / |
    | Dev1 |          |  Dev3  |
    |Dev2  |          |  Dev4  |
    └──────┘          └────────┘
      Island1           Island2
        |                  |
        └──────────────────┘
        (LoRa/Backup link)

Properties:

• No single authority point
• Self-healing topology
• Offline-capable islands
• Eventually-consistent data

Use Case: Medium-to-large fleets (50-5K devices) with intermittent connectivity

2.3 ABS (Acrylonitrile Butadiene Styrene) — Multi-Transport

Chemistry: Ternary copolymer; combines hardness, flexibility, and rigidity

Component Mapping:

• Acrylonitrile (hardness) → LoRa interfaces (reliable, long-range, sparse bandwidth)
• Butadiene (flexibility) → WiFi mesh (fast, flexible, range-limited)
• Styrene (rigidity) → Wired Ethernet (stable, predictable)

Network Topology:

[Wired Hub]────[WiFi Mesh Router]────[Fleet Device 1]
                      |
                  [LoRa GW]
                      |
            [Fleet Device 2 (LoRa only)]

Properties:

• Multi-modal transport (simultaneous WiFi + LoRa + Ethernet)
• Automatic failover between transports
• WiFi for bandwidth, LoRa for reach

Use Case: Mixed deployments with heterogeneous hardware

2.4 SAN (Styrene-Acrylonitrile) — Governance Overlay

Chemistry: Binary copolymer; harder, temperature-resistant, chemical-resistant

Network Topology:

[Hub Identity Registry]
       |
       v
[Operator Workstation]---[LXMF with Ed25519]---> [Device]
       |                                           |
       +--- Request signed with operator key       |
       +--- Device verifies sender before exec ----+

Properties:

• All actions cryptographically signed
• Role-based access control
• Audit trail via message source hashes
• Non-repudiation guarantees

Use Case: Security-sensitive fleets, regulated environments, multi-operator teams

2.5 PMMA/Styrene Blend — Transparent Hybrid

Chemistry: Blend of PMMA (clarity/hardness) with polystyrene; combines visibility with extensibility

Network Topology:

[TUI Dashboard (Imperial CRT theme)]
    |
    +---> NomadNet pages (Hub content)
    |
    +---> LXMF status requests (real-time device data)
    |
    +---> Fleet inventory (local YAML)

Properties:

• Multi-source visibility
• Debuggable at multiple layers
• Styled with Imperial CRT aesthetic

Use Case: Operator-managed fleets where visibility/debuggability is critical

2.6 Closed-Cell Foam — Air-Gapped Operations

Chemistry: Insulating foam; operates without external connection

Network Topology:

[Air-Gapped Island 1]
  Dev1, Dev2, Dev3
  (standalone, provisioned)
       |
       | LoRa bridge (optional)
       |
[Air-Gapped Island 2]
  Dev4, Dev5, Dev6

Properties:

• Devices pre-provisioned with full config
• No mandatory Hub connection
• Synchronizes when connectivity exists
• Zero external attack surface

Use Case: Remote sites, air-gapped security zones, resilience-first deployments

3. Architecture Selection Matrix

4. Current Implementation Status

4.1 Deployed Hub

Service: Styrene Community Hub at rns.styrene.io:4242

• Components: rnsd (transport) + lxmd (propagation) + nomadnet (pages) + styrened (RPC relay)
• Status: Operational

4.2 Styrened Repository

Note: The TUI is now a subpackage (styrened.tui), installed via pipx install styrene. The standalone styrene-tui repo is archived.

Structure:

src/styrened/
├── Core (daemon.py, cli.py)
├── Models - Config, mesh devices, RNS state, wire protocol
├── Services - Lifecycle, Reticulum, LXMF, RPC, Conversation, Config
├── Protocols - Chat, Styrene, base, registry
├── RPC - Server, client, messages, errors
├── IPC - Unix socket control server
├── Terminal - Session support (PTY over RNS Link)
└── TUI (styrened.tui) - Textual operator interface (subpackage)

Dependencies: RNS, LXMF, Python 3.11+

4.3 Feature Status

4.4 Roadmap

Next (Scale):

• SQLite message persistence (encrypted)
• Prometheus metrics export
• Multi-hub peering
• Identity revocation
• Configuration hot-reload

Future (Ecosystem):

• LXST relay support (when stable)
• LXMFy bot plugins
• Automation hooks
• Audit logging

5. Documentation Serving Strategy

5.1 Three-Tier Deployment

Tier 1: Conventional Web (Internet)

• Target: New users discovering Styrene
• Artifact: Astro static site (styrene.io + styrene.dev)
• Deployment: Argo Workflows → GHCR → ArgoCD
• Purpose: Discovery, SEO-friendly docs

Tier 2: Styrene Hub via NomadNet (Mesh)

• Target: Users on Styrene-provisioned networks
• Artifact: Micron .mu files
• Deployment: Hub node at ~/.nomadnet/pages/
• Purpose: On-network documentation, device discovery

Tier 3: LXMF-Only (Offline)

• Target: Users without local Hub
• Artifact: Pages distributed via LXMF store-forward
• Purpose: Documentation access without Hub

5.2 Build System

Current:

• Primary: Astro site at site/ — builds homepage + docs from docs/src/ and research/
• Secondary: docs/scripts/build.py generates NomadNet micron, mdbook, graph targets
• Wikilinks ([[target]]) resolved per build target via remark plugin or build.py
• Single source of truth in docs/src/*.md and research/*.md

5.3 NomadNet Page Hierarchy

~/.nomadnet/pages/
├── index.mu            # Hub welcome page
├── fleet.mu            # Live device listing (dynamic)
├── quick-start.mu      # Fleet ops primer
├── commands.mu         # RPC command reference
├── troubleshooting.mu  # Common issues
├── concepts/           # Reference material
│   ├── reticulum.mu
│   ├── lxmf.mu
│   └── mesh.mu
└── hardware/           # Device-specific guides
    ├── rpi4.mu
    ├── rpi-zero2w.mu
    └── x86-generic.mu

5.4 User Journey

Phase 1: Discovery (Internet)
  Visit styrene.io → Read overview → pipx install styrene

Phase 2: Provisioning (Local)
  Run styrene → Generate identity → Provision devices

Phase 3: On-Network (Mesh)
  styrened connects to Hub → Fleet dashboard → Manage mesh

6. Naming Convention Summary

6.1 The Naming Hierarchy

The full naming system follows the chemistry of styrene from etymology through polymerization:

Styrax (tree) → Storax (resin) → Styrene (molecule) → Polystyrene (material)
   ↓                                    ↓                      ↓
Etymology                          The project            Fleet topologies

Key distinction: Styrix is the opinionated, purpose-built NixOS configuration for edge devices. On other platforms (macOS, Windows, Linux distros, mobile), you simply install Styrene — polymerization is possible anywhere a Python runtime exists.

6.2 Polymer Reference Architectures

7. Open Threads

1. Hub/NomadNet Integration: Micron pages not yet tested on actual Hub instance
2. Dynamic Hub Pages: Requires Hub RPC endpoint for live device listing
3. Message Persistence: SQLite storage planned for Hub durability

Research compiled: 2026-02-01