# suryakiran46/lanshare architecture

> Architecture diagram of the GitHub repository suryakiran46/lanshare, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suryakiran46/lanshare
- Repository: https://github.com/suryakiran46/lanshare

## Overview

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: [`lantern/cli.py`](https://github.com/suryakiran46/lanshare/blob/main/lantern/cli.py) (CLI shell), [`lantern/server.py`](https://github.com/suryakiran46/lanshare/blob/main/lantern/server.py) (Advertiser), [`lantern/scan.py`](https://github.com/suryakiran46/lanshare/blob/main/lantern/scan.py) (Discovery engine), [`lantern/mdns.py`](https://github.com/suryakiran46/lanshare/blob/main/lantern/mdns.py) (mDNS core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Local runtime"]
  node_cli["CLI shell<br/>command dispatcher<br/>[cli.py]"]
  node_config["Config file<br/>local state"]
  node_scancli["Scan UI<br/>scan command<br/>[scan_cli.py]"]
  node_identity["Device identity<br/>metadata"]
  node_packaging["Pyproject<br/>package config<br/>[pyproject.toml]"]
end

subgraph group_network["LAN mDNS"]
  node_server["Advertiser<br/>service publisher<br/>[server.py]"]
  node_mdns(("mDNS core<br/>lan transport<br/>[mdns.py]"))
  node_scan["Discovery engine<br/>service browser<br/>[scan.py]"]
  node_client["Client ops<br/>network client<br/>[client.py]"]
  node_conn["Connection<br/>shared transport<br/>[connection.py]"]
  node_peers[("Peer list<br/>runtime state")]
end

node_packaging -->|"installs"| node_cli
node_cli -->|"reads/writes"| node_config
node_config -->|"seeds"| node_identity
node_cli -->|"start/stop"| node_server
node_cli -->|"scan commands"| node_scancli
node_server -->|"publishes"| node_identity
node_server -->|"registers"| node_mdns
node_scancli -->|"drives"| node_scan
node_scan -->|"browses"| node_mdns
node_scan -->|"updates"| node_peers
node_mdns -->|"uses"| node_client
node_client -->|"builds on"| node_conn
node_server -.->|"shares"| node_conn
node_scan -.->|"shares"| node_conn

click node_cli "https://github.com/suryakiran46/lanshare/blob/main/lantern/cli.py"
click node_server "https://github.com/suryakiran46/lanshare/blob/main/lantern/server.py"
click node_mdns "https://github.com/suryakiran46/lanshare/blob/main/lantern/mdns.py"
click node_scancli "https://github.com/suryakiran46/lanshare/blob/main/lantern/scan_cli.py"
click node_scan "https://github.com/suryakiran46/lanshare/blob/main/lantern/scan.py"
click node_client "https://github.com/suryakiran46/lanshare/blob/main/lantern/client.py"
click node_conn "https://github.com/suryakiran46/lanshare/blob/main/lantern/connection.py"
click node_packaging "https://github.com/suryakiran46/lanshare/blob/main/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_scancli,node_identity,node_packaging toneBlue
class node_server,node_mdns,node_scan,node_client,node_conn,node_peers toneAmber
```

## Components

### Local runtime

The interactive lantern process and its local state

- [CLI shell](https://github.com/suryakiran46/lanshare/blob/main/lantern/cli.py): command dispatcher · Main interactive entrypoint; parses commands and orchestrates actions · `lantern/cli.py`
- **Config file**: local state · Persisted display name and identity seed in config.json
- [Scan UI](https://github.com/suryakiran46/lanshare/blob/main/lantern/scan_cli.py): scan command · Interactive scan presentation and live updates · `lantern/scan_cli.py`
- **Device identity**: metadata · Hostname, OS, version, and display name published to peers
- [Pyproject](https://github.com/suryakiran46/lanshare/blob/main/pyproject.toml): package config · Packaging metadata and installed CLI entrypoint · `pyproject.toml`

### LAN mDNS

Broadcast and discovery over the local network

- [Advertiser](https://github.com/suryakiran46/lanshare/blob/main/lantern/server.py): service publisher · Lifecycle for advertising this machine as a LAN service · `lantern/server.py`
- [mDNS core](https://github.com/suryakiran46/lanshare/blob/main/lantern/mdns.py): lan transport · Low-level multicast DNS service registration and browsing · `lantern/mdns.py`
- [Discovery engine](https://github.com/suryakiran46/lanshare/blob/main/lantern/scan.py): service browser · Finds peers on the LAN and maintains the active device view · `lantern/scan.py`
- [Client ops](https://github.com/suryakiran46/lanshare/blob/main/lantern/client.py): network client · Shared client-side network interaction layer · `lantern/client.py`
- [Connection](https://github.com/suryakiran46/lanshare/blob/main/lantern/connection.py): shared transport · Common connection/state handling used by network features · `lantern/connection.py`
- **Peer list**: runtime state · Transient live view of discovered lantern devices

## Connections

- 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
