UmbrelApps/Docs/Referenties/Architectuur-huidig.md

# De huidige opzet: hoe het vandaag in elkaar zit

Naslag. Wat er ís, zodat een latere sessie het niet hoeft te reconstrueren. Wat er mis mee is en wat eraan
gebeurt staat in de plannen.

**Let op het onderscheid dat dit document maakt**, want het is op 19-08-2026 het belangrijkste feit over
deze app: er is verschil tussen wat er in de repo staat en wat er op de Umbrel draait. Dat verschil is
groot, en het per ongeluk gelijkstellen leidt tot conclusies die niet kloppen.

| | In de repo | Draait op de Umbrel |
|-|-|-|
| Versie | 0.0.3 | 2.0.1, en die app wordt gedeïnstalleerd |
| App-id | `whatsnext-electrum-gate` | `electrumtls-electrum-tls` |
| TLS-poort | 50022 | 50002 |
| Containers | `server` plus `agent` | alleen `server` |
| Certificaat | door de agent gekozen uit de gevonden mappen | vast pad naar `sync.kamenier-hamer.nl` |
| Dashboard | leest `status.json` | verzonnen waarden, hardgecodeerd domein |

Alles in de kolom "in de repo" is **ongetest buiten de unittests**. De vorige versie draait en een wallet
verbindt er over TLS mee; dat is bewezen. De nieuwe niet.

## 1. Wat het doet

Een Electrum-server spreekt onversleuteld TCP. Een wallet buiten het netwerk wil TLS. Deze app zet daar
nginx met de `stream`-module tussen: die accepteert TLS, termineert het, en praat plat door naar de
Electrum-server die de gebruiker in umbrelOS gekozen heeft.

```
Electrum-wallet  ──TLS 50022──▶  nginx stream  ──plat──▶  Electrs, Fulcrum of ElectrumX
                                      ▲
                                 cert.conf, geschreven door de agent
```

Het certificaat komt van een reverse proxy die op dezelfde Umbrel al Let's Encrypt-certificaten beheert.
Deze app leest die mappen alleen; hij vraagt zelf niets aan en vernieuwt niets.

## 2. De twee containers

**`server`** (`nginx:alpine`) doet twee dingen. In het `http`-blok serveert hij het dashboard op poort 80,
achter de `app_proxy` van umbrelOS, plus `status.json` en een doorstuur naar de API van de agent. In het
`stream`-blok termineert hij TLS op 50022. Zijn `command` schrijft bij het starten het `log_format` voor de
sessielog weg, wacht tot de agent een certificaat gekozen heeft, en draait daarna een lus die nginx
herlaadt zodra de agent daarom vraagt.

**`agent`** (`python:3-alpine`) draait `agent.py` en doet elke minuut een ronde: de certificaatmappen
scannen, de keuze toepassen, de Electrum-server bevragen voor blokhoogte en reactietijd, de sessielog van
nginx uitlezen, en `status.json` schrijven. Daarnaast luistert hij op poort 8000 voor de certificaatkeuze
van het dashboard.

**Waarom de agent nginx niet zelf herlaadt.** Dat zou de Docker-socket vragen, en die is er bewust uit
gehaald: hij geeft root-toegang tot de host. In plaats daarvan schrijft de agent `cert.conf` plus een
vlagbestand, en herlaadt de nginx-container zichzelf. Een reload verbreekt bestaande wallet-verbindingen
niet; een containerherstart wel.

## 3. De gedeelde map

Beide containers hebben `${APP_DATA_DIR}/runtime` gemount op `/var/lib/gate`. Dat is het enige raakvlak
tussen de twee, en het is met opzet een map met bestanden en geen protocol.

| Bestand | Wie schrijft | Waarvoor |
|-|-|-|
| `status.json` | agent | alles wat het dashboard toont |
| `cert.conf` | agent | de `ssl_certificate`-regels die nginx includeert |
| `reload` | agent | vraagt nginx om een herlading; wordt `reload.done` |
| `stream-log.conf` | nginx | het `log_format`, hier omdat een dollarteken niet in een template kan |
| `stream.log` | nginx | een regel per afgesloten sessie, zonder client-adres |
| `config/selected-cert` | agent | de keuze van de gebruiker, overleeft een herstart |

## 4. Wat er nog hardgecodeerd is

Sinds 19-08-2026 bijna niets meer in de app zelf. De domeinnaam en het certificaatpad zijn uit
`docker-compose.yml` en `nginx.conf.template` verdwenen: de agent bepaalt ze.

Wat er nog staat, en waar:

- **de mounts van de certificaatbronnen** in `docker-compose.yml`, want een pad instellen naar iets wat
  niet gemount is levert een map op die de container niet ziet. Nginx Proxy Manager staat er
  uitgecommentarieerd bij, omdat het pad niet geverifieerd is;
- **de poortnummers** 50022 en 3850;
- **de vertaaltabel van backend-IP naar naam** in de agent, met `unknown` als terugval;
- **de repo-URL's** in `umbrel-app.yml`. Die horen daar; ze wijzen naar de repo.

Het plan **Configuratie** haalt de eerste twee naar een configuratiebestand.

## 5. Hoe het geïnstalleerd wordt

Als community app store: de gebruiker plakt de repo-URL in umbrelOS en installeert de app. umbreld kloont
anoniem met isomorphic-git, dus de repo moet publiek en SHA-1 zijn. Bij installatie wordt de hele app-map
gekopieerd; **bij een update alleen een whitelist**, en dat stuurt het hele ontwerp. Zie
[Umbrel-appstore-spec.md](Umbrel-appstore-spec.md).

## 6. Wat er goed aan is, en dat is het onthouden waard

- **geen Docker-socket**, dus geen root-toegang tot de host;
- **geen eigen image**, dus geen bouwstap, geen registry en geen multi-arch-gedoe. Beide containers
  draaien op een officiële image met configuratie uit een template;
- **niets wordt bij het starten geïnstalleerd.** De vorige opzet deed `apk add stunnel` bij élke start;
- **de app vraagt geen certificaten aan.** ACME blijft bij de reverse proxy, en dat is de reden dat deze
  app zo klein kan blijven;
- **een certificaatvernieuwing is een reload**, dus wallet-verbindingen blijven staan.