KALNET System Architecture
Level 1: Physical Network
Copy
┌─────────────────────────────────────────────────────────────────────────┐
│ KALNET Home Network │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Your ArchLinux Machine (192.168.1.100 - example) │ │
│ │ └─ Hyperoptic Broadband (WAN) │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ Docker Bridge Network: "kalnet" │ │ │
│ │ │ │ │ │
│ │ │ ┌────────────────┐ ┌────────────────┐ ┌──────────────┐ │ │ │
│ │ │ │ Jellyfin │ │ n8n │ │ Samba │ │ │ │
│ │ │ │ :8096 (web) │ │ :5678 (web) │ │ :139/445 (sb)│ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ │ Media service │ │ Automation │ │ File share │ │ │ │
│ │ │ └────────┬───────┘ └────────┬───────┘ └──────┬───────┘ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ ┌────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ KALNET Discovery Service (Go) │ │ │ │
│ │ │ │ :8080 - Service registry & health checker │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ Every 30s: │ │ │ │
│ │ │ │ ✓ Checks jellyfin:8096 │ │ │ │
│ │ │ │ ✓ Checks n8n:5678 │ │ │ │
│ │ │ │ ✓ Checks samba:139 │ │ │ │
│ │ │ │ ✓ Returns status to clients │ │ │ │
│ │ │ └────────────────────────────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ ┌────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ NAS Storage (Shared volumes) │ │ │ │
│ │ │ │ - nas-storage (media files, backups) │ │ │ │
│ │ │ │ - jellyfin-* (config, cache) │ │ │ │
│ │ │ │ - n8n-data (workflows, secrets) │ │ │ │
│ │ │ └────────────────────────────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────┬──────────────────┬──────────────────────────┐ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ Living Room Bedroom Kitchen Hallway │
│ (Smart TV) (Laptop) (Tablet) (Speaker) │
│ Ethernet WiFi WiFi WiFi │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Level 2: Data Flow - Media Streaming
Copy
Device (Living Room TV)
│
│ GET http://192.168.1.100:8096/Items
│
▼
Jellyfin (Port 8096)
│
│ Reads library from disk
│ (mounted from nas-storage volume)
│
▼
NAS Storage Volume
│
│ Returns: media_file.mkv, metadata
│
▼
Device displays video
Level 3: Data Flow - File Access (Samba)
Copy
Device (Bedroom Laptop)
│
│ \\192.168.1.100\storage
│ (SMB Protocol, Port 445)
│
▼
Samba Service (Container)
│
│ Authenticates (guest access configured)
│ Maps /share/storage to nas-storage volume
│
▼
NAS Storage Volume
│
│ Returns directory listing
│ Device can read/write files
│
▼
Device's file manager shows folder contents
Level 4: Data Flow - Service Discovery
Copy
Device Client
│
│ GET http://192.168.1.100:8080/discover
│
▼
KALNET Discovery Service
│
├─ Checks /service/jellyfin
│ └─ HTTP GET http://jellyfin:8096/web/ (within Docker network)
│ └─ Status: "up" or "down"
│
├─ Checks /service/n8n
│ └─ HTTP GET http://n8n:5678/ (within Docker network)
│ └─ Status: "up" or "down"
│
├─ Checks /service/samba
│ └─ TCP connect to samba:139 (within Docker network)
│ └─ Status: "up" or "down"
│
└─ Aggregates all statuses
│
▼
Returns JSON:
{
"services": [
{"name": "jellyfin", "status": "up", "url": "..."},
{"name": "n8n", "status": "up", "url": "..."},
{"name": "samba", "status": "up", "url": "..."}
]
}
Level 5: Container Network (Internal)
Copy
┌─────────────────────────────────────────────────────────────┐
│ Docker Bridge: "kalnet" │
│ │
│ Jellyfin n8n Samba Discovery │
│ ──────── ─── ───── ───────── │
│ 172.20.0.2 172.20.0.3 172.20.0.4 172.20.0.5 │
│ :8096 :5678 :139/445 :8080 │
│ │
│ All containers can reach each other by hostname: │
│ - jellyfin:8096 │
│ - n8n:5678 │
│ - samba:139/445 │
│ - kalnet-discovery:8080 │
│ │
└─────────────────────────────────────────────────────────────┘
Level 6: Volume Architecture
Copy
Host Machine (ArchLinux)
│
├─ Docker Volumes:
│
│ ├─ nas-storage (shared by all services)
│ │ ├─ Jellyfin reads media from here
│ │ ├─ Samba shares this via SMB
│ │ └─ n8n can read/write files here
│ │
│ ├─ jellyfin-config
│ │ └─ Persists Jellyfin settings between restarts
│ │
│ ├─ jellyfin-cache
│ │ └─ Image/video transcoding cache
│ │
│ └─ n8n-data
│ ├─ Workflow definitions
│ ├─ Credentials (encrypted)
│ └─ Execution history
│
└─ Mapped on host at:
/var/lib/docker/volumes/kalnet_nas-storage/_data/
/var/lib/docker/volumes/kalnet_jellyfin-config/_data/
... etc
Level 7: Service Dependencies
Copy
startup sequence
(all can start in parallel, but delays are automatic)
Time 0: start samba, jellyfin, n8n
├─ Samba ready: ~2s
├─ Jellyfin ready: ~10s
└─ n8n ready: ~15s
Time 3: start kalnet-discovery
└─ Waits for depends_on: [jellyfin, n8n, samba]
└─ Ready: ~5s
Time 20: All services operational
Health checks begin every 30s
Level 8: Request Path Examples
Example 1: Watch a video on Living Room TV
Copy
1. TV User clicks "Watch Sims"
2. TV sends: GET http://192.168.1.100:8096/Items/123/Download
3. ArchLinux machine receives on :8096 (docker port mapping)
4. Docker routes to jellyfin container (172.20.0.2:8096)
5. Jellyfin reads from nas-storage volume
6. Jellyfin returns video stream to TV
7. TV plays video
Example 2: Backup files from Bedroom Laptop
Copy
1. Laptop user opens file manager
2. Laptop connects: smb://192.168.1.100/storage
3. ArchLinux machine receives on :445 (SMB port)
4. Docker routes to samba container (172.20.0.4:445)
5. Samba authenticates (guest=allowed)
6. Samba maps to nas-storage volume
7. Laptop sees folder contents
8. Laptop can drag files in/out
Example 3: Living Room discovers all services
Copy
1. Living Room device sends: GET http://192.168.1.100:8080/discover
2. ArchLinux receives on :8080
3. Docker routes to kalnet-discovery (172.20.0.5:8080)
4. Discovery service checks each service:
- curl http://jellyfin:8096/web/ ✓ up
- curl http://n8n:5678/ ✓ up
- telnet samba:139 ✓ up
5. Returns JSON with all statuses
6. Device renders service selector UI
Failure Scenarios
If Jellyfin crashes
Copy
Discovery Service detects:
- Ping to jellyfin:8096 fails
- Marks status as "down"
- Devices can see it's offline
- User can still access n8n, Samba
- Docker auto-restart (unless-stopped policy)
- ~10s later, service is back up
If Docker network fails
Copy
All containers lose connectivity to each other
- Discovery cannot reach services
- Marks all as "down"
- Host machine still functional (processes running)
- Restart docker daemon: systemctl restart docker
- Containers auto-start with policy: restart: unless-stopped
If NAS storage volume fills up
Copy
- Jellyfin cannot transcode new files
- Samba can still read existing files
- n8n cannot save execution logs
- Add storage: Stop services, expand volume, restart
Performance Notes
Copy
Concurrent access limits (Docker bridge network):
- Jellyfin: ~10-20 concurrent streams (depends on CPU/bandwidth)
- Samba: Unlimited (kernel limit ~50 per user typically)
- n8n: 1 concurrent workflow execution (by default)
- Discovery: ~100 concurrent requests (Go http.ListenAndServe)
Network bandwidth:
- 1080p Jellyfin stream ≈ 5 Mbps
- Samba file copy: Limited by network (gigabit = ~100 MB/s)
- Discovery API: ~1KB response → negligible bandwidth
CPU usage (idle):
- Jellyfin: ~5-10%
- Samba: <1%
- n8n: ~2-5%
- Discovery: <1%
Monitoring Checklist
Copy
Every 30 seconds (Discovery Service):
✓ Jellyfin responding?
✓ n8n responding?
✓ Samba responding?
If any is "down":
→ Check logs: docker-compose logs [service]
→ Restart: docker-compose restart [service]
→ Verify ports: ss -tlnp | grep [port]
This architecture allows:
- Isolation: Each service in own container
- Resilience: One service failure doesn’t affect others
- Discoverability: Devices know what services are available
- Scaling: Easy to add more services on same network
- Persistence: Volumes survive container restarts