# Styrene Taxonomy

A living document defining the terms, concepts, and relationships in the Styrene provisioning system. Names are expected to evolve as the system matures - this document tracks both current terminology and the underlying concepts they represent.

---

## Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                         PROFILE                                 │
│            "What are we deploying as a unit?"                   │
│                                                                 │
│    Composed of one or more ROLES, verified against              │
│    specific HARDWARE combinations                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                          ROLES                                  │
│              "What function does this serve?"                   │
│                                                                 │
│    Abstract capabilities that can be satisfied by               │
│    different HARDWARE through specific ACTIVITIES               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        HARDWARE                                 │
│              "What physical device is this?"                    │
│                                                                 │
│    Concrete devices with known TRAITS, provisioned              │
│    through specific ACTIVITIES                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        ACTIVITIES                               │
│              "How do we provision this?"                        │
│                                                                 │
│    The actual provisioning workflow: write image,               │
│    flash firmware, inject config, etc.                          │
└─────────────────────────────────────────────────────────────────┘
```

---

## Term Definitions

### Profile

**Current name**: Profile  
**Concept**: A deployable unit that may consist of one or more physical devices working together.

**Description**: Profiles represent the "what" of a deployment - the logical function being deployed, independent of specific hardware. A profile declares what roles are needed; the operator then selects hardware to fulfill those roles.

**Examples**:
| ID | Label | Description |
|----|-------|-------------|
| `edge-router` | Edge Router | Mesh-connected router providing IP routing and mesh bridging |
| `node` | Node | Basic mesh participant |
| `workstation` | Workstation | Self-contained node with local display and input |

**Evolution notes**: 
- Labels will change as naming conventions mature
- IDs should remain stable once in use
- New profiles can be added without disrupting existing ones

---

### Role

**Current name**: Role  
**Concept**: A functional capability that a device provides within a deployment.

**Description**: Roles are the building blocks of profiles. Each role represents a discrete function (mesh routing, compute node, LoRa gateway, etc.) that can be fulfilled by various hardware through a specific provisioning activity.

**Examples**:
| ID | Label | Description | Provisions Via |
|----|-------|-------------|----------------|
| `styrene-node` | Styrene Node | NixOS + Reticulum + Bond + mesh | NixOS |
| `mesh-router` | Mesh Router | 802.11s mesh + IP routing | OpenWRT |
| `lora-transceiver` | LoRa Transceiver | Long-range radio link | RNode firmware |

**Evolution notes**:
- Roles may split as we discover distinct sub-functions
- Roles may merge if distinctions prove unnecessary
- The `provisions` field links to an Activity type

---

### Hardware

**Current name**: Hardware  
**Concept**: A specific physical device model that we know how to provision.

**Description**: Hardware entries describe concrete device models - their architecture, boot requirements, and traits. Hardware is mapped to roles through verified combinations in profiles.

**Examples**:
| ID | Label | Arch | Boot | Activity |
|----|-------|------|------|----------|
| `rpi4` | Raspberry Pi 4 | aarch64 | uboot | nixos-direct |
| `rpi-zero2w` | Raspberry Pi Zero 2 W | aarch64 | uboot | nixos-direct |
| `t100ta` | ASUS T100TA | x86_64 | uefi32 | nixos-installer |
| `q502l` | ASUS Q502L | x86_64 | uefi64 | nixos-installer |
| `gl-opal` | GL.iNet Opal | mips | - | openwrt-flash |
| `rnode-t3s3` | LilyGO T3S3 RNode | - | - | rnode-flash |

**Evolution notes**:
- New hardware added as tested and verified
- Hardware may gain/lose traits as we learn more
- Labels are display names, IDs are stable references

---

### Trait

**Current name**: Trait  
**Concept**: A characteristic of hardware that affects what roles it can fulfill or how it's provisioned.

**Description**: Traits are boolean or categorical properties of hardware. Some traits are requirements (a workstation needs `has_display`), others are constraints (a device with `low_memory` needs swap configured).

**Examples**:
| Trait | Description |
|-------|-------------|
| `has_display` | Device has integrated display |
| `has_input` | Device has keyboard/trackpad/touchscreen |
| `low_memory` | Less than 1GB RAM, needs swap |
| `low_power` | Suitable for battery/solar operation |
| `gpio` | Has general-purpose I/O pins |
| `wifi` | Has wireless networking |
| `ethernet` | Has wired networking |
| `usb_powered` | Can be powered via USB |
| `uefi32` | Requires 32-bit UEFI bootloader (Bay Trail quirk) |

**Evolution notes**:
- Traits will expand as we encounter new hardware variations
- Some traits may become roles if they represent deployable function
- Trait names should be descriptive and stable

---

### Activity

**Current name**: Activity  
**Concept**: A provisioning workflow that transforms blank media/device into a configured, deployable state.

**Description**: Activities are the "how" of provisioning. Each activity type has its own workflow, tooling, required inputs, and success criteria. Hardware maps to activities; the TUI orchestrates them.

**Examples**:
| ID | Label | Description | Maturity |
|----|-------|-------------|----------|
| `nixos-direct` | NixOS Direct | Write NixOS image directly to SD card | Done |
| `nixos-installer` | NixOS Installer | Create bootable USB installer for x86 | Done |
| `openwrt-flash` | OpenWRT Flash | Flash OpenWRT firmware to router | Planned |
| `rnode-flash` | RNode Flash | Flash RNode firmware via rnodeconf | Planned |
| `nixos-anywhere` | nixos-anywhere | Remote NixOS installation via SSH | Future |

**Evolution notes**:
- Activities progress through maturity: Planned → In Progress → Done
- New activities added as we support new device types
- Each activity may have sub-variations (e.g., attended vs unattended)

---

### Verified Configuration

**Current name**: Verified  
**Concept**: A specific combination of hardware that has been tested for a given profile.

**Description**: Not all hardware combinations are tested. Verified configurations are the combinations we've actually deployed and confirmed working. This is the "supported" matrix.

**Example for `edge-router` profile**:
```yaml
verified:
  - hardware: [rpi4, gl-opal]
    status: tested
    notes: "Primary reference configuration"
  - hardware: [rpi-zero2w, gl-opal]
    status: untested
    notes: "Should work, needs verification"
```

**Evolution notes**:
- Verified list grows as we test more combinations
- Status can be: `tested`, `untested`, `known-issues`, `deprecated`
- Notes capture tribal knowledge about specific combos

---

## Relationships

```
Profile ─────────────────────────────────────────────────────────┐
   │                                                             │
   │ requires                                                    │
   ▼                                                             │
 Role ◄──────────────────────────────────────────┐               │
   │                                             │               │
   │ provisions via                              │               │
   ▼                                             │               │
Activity                                         │               │
   ▲                                             │               │
   │ provisioned by                              │ verified      │
   │                                             │ against       │
Hardware ────────────────────────────────────────┘               │
   │         │                                                   │
   │ has     │ fulfills                                          │
   ▼         └───────────────────────────────────────────────────┘
 Trait
```

**Reading the diagram**:
- A **Profile** requires one or more **Roles**
- A **Role** is provisioned via an **Activity**
- **Hardware** is provisioned by an **Activity**
- **Hardware** has **Traits** that describe its capabilities
- **Hardware** fulfills **Roles** within a **Profile**
- **Profiles** are verified against specific **Hardware** combinations

---

## Naming Convention

### IDs (Stable)
- Lowercase, hyphenated: `edge-router`, `styrene-node`, `rpi-zero2w`
- Used in code, configs, and APIs
- Should not change once in production use
- If a rename is necessary, create alias/migration

### Labels (Fluid)
- Human-readable display names
- Can include spaces, capitals, special characters
- Free to change as naming matures
- Stored separately from IDs

### Versioning
When a concept changes significantly:
1. Create new ID for new concept
2. Deprecate old ID (don't delete)
3. Document migration path
4. Old ID can alias to new if appropriate

---

## Future Considerations

### Potential new terms

| Concept | Current Thinking | Notes |
|---------|------------------|-------|
| Fleet | Collection of deployed profiles | May need formal definition |
| Bond | Agent running on styrene-node | Part of role definition? |
| Hub | Central coordination point | Relates to profiles how? |
| Mesh | The network itself | Implicit or explicit entity? |

### Naming maturity stages

1. **Working name**: Used during development, expected to change
2. **Provisional name**: Stable enough for docs, may still change  
3. **Canonical name**: Finalized, only changes with major version

Current status: All names are **working names** until first production deployment.

---

## Changelog

| Date | Change |
|------|--------|
| 2025-01-20 | Initial taxonomy created |
| | Defined: Profile, Role, Hardware, Trait, Activity, Verified |
| | All terms at "working name" maturity |
