​

KALNET System Architecture

​

Level 1: Physical Network

Figure 1 — KALNET Physical Network. The ArchLinux host runs all services inside a Docker bridge network. Jellyfin, n8n, and Samba share NAS storage volumes. The Discovery service health-checks every registered service every 30 seconds. LAN clients connect via Ethernet or WiFi.

Trace ID	Requirement	Rationale	Test Case
KALNET-NET-001	All services shall run within a Docker bridge network named “kalnet”	Provides hostname-based service discovery and network isolation	TC-KALNET-NET-001
KALNET-NET-002	The Discovery service shall health-check all registered services every 30 seconds	Enables clients to show real-time service availability	TC-KALNET-NET-002
KALNET-NET-003	NAS storage volumes shall be shared across Jellyfin, n8n, and Samba containers	Eliminates data duplication and enables cross-service file access	TC-KALNET-NET-003

​

Level 2: Data Flow - Media Streaming

Figure 2 — Media Streaming Data Flow. The TV requests media items from Jellyfin over HTTP. Jellyfin reads the library from the NAS storage Docker volume and streams the video back to the device.

​

Level 3: Data Flow - File Access (Samba)

Figure 3 — Samba File Access Data Flow. The laptop connects via SMB protocol. Samba authenticates the connection (guest mode), maps the request to the NAS storage volume, and returns the directory listing. The client can read and write files directly.

​

Level 4: Data Flow - Service Discovery

Figure 4 — Service Discovery Data Flow. A client queries the Discovery endpoint. The service probes each registered container over the Docker internal network (HTTP for Jellyfin and n8n, TCP for Samba) and aggregates statuses into a JSON response.

​

Level 5: Container Network (Internal)

Figure 5 — Docker Bridge Network. All containers share the kalnet bridge and resolve each other by hostname (e.g. jellyfin:8096). Each container receives a deterministic IP on the 172.20.0.0/16 subnet.

​

Level 6: Volume Architecture

Figure 6 — Volume Architecture. Four Docker volumes persist data across container restarts. nas-storage is the shared media volume consumed by Jellyfin, Samba, and n8n. Each service also has dedicated volumes for configuration and caches. Host paths map to /var/lib/docker/volumes/kalnet_*/.

​

Level 7: Service Dependencies

Figure 7 — Service Startup Sequence. Samba, Jellyfin, and n8n start in parallel at T=0. The Discovery service waits for all three (depends_on) before starting at ~T=15 s. Full operational readiness is reached at ~T=20 s, after which health checks begin every 30 seconds.

​

Level 8: Request Path Examples

​

Example 1: Watch a video on Living Room TV

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

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

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

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

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

- 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

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

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]

1. Isolation: Each service in own container
2. Resilience: One service failure doesn’t affect others
3. Discoverability: Devices know what services are available
4. Scaling: Easy to add more services on same network
5. Persistence: Volumes survive container restarts