How suryakiran46/lanshare works
1. What this repository is
- lantern is a single Python package that provides a local-network device discovery CLI.
- There is no remote backend or cloud dependency; all behavior is on the LAN using mDNS/Multicast DNS.
- The architecture is centered on one interactive command-line entrypoint that controls background networking tasks.
2. Top-level structure
- lantern/cli.py is the main user-facing shell/command dispatcher.
- lantern/server.py and lantern/mdns.py handle announcing this machine on the network.
- lantern/scan.py and lantern/scan_cli.py handle discovering and presenting other lantern peers.
- lantern/client.py and lantern/connection.py likely encapsulate network/client-side interaction and shared connection logic.
- pyproject.toml defines packaging and the installed CLI command.
3. Primary runtime boundary
- The system runs as a local Python process started by the lantern command.
- The CLI is the control plane; network broadcasting and scanning are background or subcommand-driven activities.
- This separation matters for a diagram: user input flows into the CLI, and the CLI fans out into broadcast and discovery subsystems.
4. Device advertisement path
- When the user runs start, the app registers this device as an mDNS service.
- The advertised payload includes a display name plus system metadata such as hostname, OS, and version.
- The README indicates the service name follows the pattern of a LAN-local mDNS service instance and is visible to peers.
5. Device discovery path
- When the user runs scan, the app searches the LAN for other lantern-enabled devices.
- Discovery is also mDNS-based, so peers are found by listening for advertised services rather than by direct IP scanning.
- The scan output is live-updating, meaning the discovery subsystem maintains a changing in-memory view of active devices.
6. CLI command model
- The interactive shell supports start, scan, stopscan, rename, and exit.
- rename updates the persisted display name and restarts broadcasting so the new identity is re-announced on the LAN.
- stopscan stops the live discovery loop, which implies the scan subsystem is independently controllable from advertising.
7. Persistence and configuration boundary
- The README says the display name is saved in config.json in the current working directory.
- This is the only explicit persistence layer in the repo: local file-based state, not a database.
- On startup, the CLI likely reads this config to seed the name used by advertising and display.
8. Networking abstraction layers
- mdns.py is the low-level LAN service discovery/advertisement layer.
- server.py likely wraps service publication and lifecycle management for “this device” broadcasting.
- scan.py likely wraps service browsing and parsing of remote advertisements into a device list.
- client.py and connection.py suggest a shared abstraction for network operations and state handling, keeping transport details out of the CLI.
9. Data flow through the system
- User action → cli.py command parsing → broadcast or scan subsystem → mDNS on the LAN.
- For broadcasting, local metadata is gathered, stored/updated, and published outward.
- For scanning, remote mDNS announcements are ingested, normalized into device records, and shown to the user in the live list.
10. State model
- There are two kinds of state: persistent local config (config.json) and ephemeral runtime scan/broadcast state.
- Persistent state mainly affects identity; runtime state tracks currently visible peers and whether services are active.
- The live device list is a transient view that changes as peers appear or leave the LAN.
11. Operational boundaries
- The project is explicitly LAN-scoped: devices are only discoverable when running lantern and advertising via mDNS.
- Cross-platform support is intended, but the README notes active testing is focused on Linux.
- Python 3.8+ is the runtime baseline.
12. How to draw the architecture
- Place the CLI at the center as the orchestrator.
- Draw one outbound path from CLI to “advertise this host” via server.py / mdns.py.
- Draw one inbound path from LAN mDNS traffic to scan.py / scan_cli.py / client.py.
- Add a small local config store (config.json) feeding the CLI and broadcast identity.
- Keep the entire system inside a local-network boundary with no external services.
Main entry points: cli.py CLI shell · server.py Advertiser · scan.py Discovery engine · mdns.py mDNS core
Components 11
Local runtime
The interactive lantern process and its local state
- CLI shell · Main interactive entrypoint; parses commands and orchestrates actions
lantern/cli.py - Config file · Persisted display name and identity seed in config.json
- Scan UI · Interactive scan presentation and live updates
lantern/scan_cli.py - Device identity · Hostname, OS, version, and display name published to peers
- Pyproject · Packaging metadata and installed CLI entrypoint
pyproject.toml
LAN mDNS
Broadcast and discovery over the local network
- Advertiser · Lifecycle for advertising this machine as a LAN service
lantern/server.py - mDNS core · Low-level multicast DNS service registration and browsing
lantern/mdns.py - Discovery engine · Finds peers on the LAN and maintains the active device view
lantern/scan.py - Client ops · Shared client-side network interaction layer
lantern/client.py - Connection · Common connection/state handling used by network features
lantern/connection.py - Peer list · Transient live view of discovered lantern devices
Connections 14
- Pyproject → CLI shell: installs · Defines the lantern command entrypoint
- CLI shell → Config file: reads/writes · Loads and persists display name state
- Config file → Device identity: seeds · Provides the name used in published metadata
- CLI shell → Advertiser: start/stop · Controls broadcasting lifecycle
- CLI shell → Scan UI: scan commands · Routes scan and stopscan actions
- Advertiser → Device identity: publishes · Announces local metadata on the LAN
- Advertiser → mDNS core: registers · Uses mDNS to advertise the service
- Scan UI → Discovery engine: drives · Starts and stops live discovery
- Discovery engine → mDNS core: browses · Listens for LAN advertisements
- Discovery engine → Peer list: updates · Maintains the live discovered device view
- mDNS core → Client ops: uses · Shared network interaction layer
- Client ops → Connection: builds on · Connection logic underlies client operations
- Advertiser → Connection: shares · Broadcast lifecycle shares common connection handling
- Discovery engine → Connection: shares · Discovery also relies on shared connection handling