# suryakiran46/lantern architecture

> Architecture diagram of the GitHub repository suryakiran46/lantern, 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/lantern
- Repository: https://github.com/suryakiran46/lantern

## Overview

1. **What this repo is**
   - `lantern` is a Python 3.8+ command-line application for **LAN device discovery** using **mDNS / Multicast DNS**.
   - The architecture is centered on a single local machine advertising itself and discovering peers on the same subnet; there is no central server or cloud backend.

2. **Primary user interface**
   - `lantern/cli.py` is the interactive entrypoint exposed by the package.
   - It provides the `lantern>` shell and dispatches user commands like start, scan, rename, stopscan, and exit.
   - This is the main orchestration layer that ties together discovery, broadcasting, and configuration.

3. **mDNS advertisement path**
   - `lantern/server.py` appears to handle broadcasting the local machine as an mDNS service.
   - This is the “presence publishing” side of the system: it registers the device name and metadata so other LAN clients can discover it.
   - The README indicates the service identity is derived from the user’s display name plus local host/IP details.

4. **mDNS discovery path**
   - `lantern/client.py` and `lantern/mdns.py` likely implement the discovery side: querying the LAN for lantern services and parsing the results.
   - Discovery is event-driven and local-network scoped, with devices appearing and disappearing as mDNS announcements change.
   - This is the core data flow for seeing peers in real time.

5. **Live scan subsystem**
   - `lantern/scan.py` and `lantern/scan_cli.py` suggest a dedicated scan workflow separated from the general shell.
   - This subsystem likely manages the periodic/live refresh loop, maintains the currently visible device list, and handles stop/start behavior.
   - For architecture diagrams, treat this as the “live monitoring” layer sitting on top of mDNS discovery.

6. **State and configuration**
   - The README says the tool persists the display name in a local `config.json` in the current directory.
   - That makes configuration purely local and file-based, with no remote account or database.
   - The persistent state is small: mostly identity/labeling data used when advertising over mDNS.

7. **Networking boundaries**
   - The key boundary is between **local CLI/process state** and **LAN multicast discovery state**.
   - Lantern does not rely on a backend service; all visibility comes from multicast traffic and local device announcements.
   - Any discovered device record is transient network state, not stored as long-term application data.

8. **Likely responsibilities of `connection.py`**
   - `lantern/connection.py` likely contains shared connection or peer-record abstractions used by both server and client flows.
   - In an architecture diagram, place it as a supporting domain module that models discovered endpoints, service metadata, or communication state.
   - It is not the main entrypoint, but a shared internal boundary for networking-related data structures.

9. **Package and tooling layer**
   - `pyproject.toml` defines packaging and CLI installation so `lantern` becomes an executable command after `pip install -e .`.
   - `lantern/__init__.py` marks the package boundary; `lantern` is organized as a small, single-purpose Python package rather than a multi-service system.

10. **End-to-end data flow**
   - User enters a command in the CLI.
   - The CLI starts or stops mDNS broadcasting, or triggers a scan.
   - The mDNS layer publishes the local device or queries the LAN for peers.
   - Results are formatted into a live device list and displayed back in the terminal.
   - Configuration changes, such as renaming, are written locally and then used to restart advertising.

11. **Main architectural constraint**
   - The system is only useful when other lantern instances are present on the same LAN and mDNS is allowed on the network.
   - That means the primary dependency is the network environment itself, not external infrastructure.
   - For diagrams, emphasize “peer discovery over multicast on the local subnet” as the central runtime dependency.

12. **Good diagram boundaries**
   - **User/Terminal boundary:** `lantern/cli.py`
   - **Broadcasting boundary:** `server.py` + `mdns.py`
   - **Discovery boundary:** `client.py` + `scan.py`
   - **Persistence boundary:** local `config.json`
   - **Support/domain boundary:** `connection.py`

Main entry points: [`lantern/cli.py`](https://github.com/suryakiran46/lantern/blob/main/lantern/cli.py) (CLI shell), [`lantern/client.py`](https://github.com/suryakiran46/lantern/blob/main/lantern/client.py) (Client), [`lantern/server.py`](https://github.com/suryakiran46/lantern/blob/main/lantern/server.py) (Server), [`lantern/__init__.py`](https://github.com/suryakiran46/lantern/blob/main/lantern/__init__.py) (Package)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Terminal UI"]
  node_lantern_cli["CLI shell<br/>interactive entrypoint<br/>[cli.py]"]
  node_lantern_scan_cli["Scan CLI<br/>scan frontend<br/>[scan_cli.py]"]
end

subgraph group_broadcast["Presence Publishing"]
  node_lantern_server["Server<br/>mDNS advertiser<br/>[server.py]"]
  node_lantern_mdns["mDNS layer<br/>multicast DNS<br/>[mdns.py]"]
end

subgraph group_discover["Peer Discovery"]
  node_lantern_client["Client<br/>peer discovery<br/>[client.py]"]
  node_lantern_scan["Live scan<br/>monitor loop<br/>[scan.py]"]
end

subgraph group_state["Local State"]
  node_lantern_connection["Connection<br/>peer model<br/>[connection.py]"]
  node_config_json["config.json<br/>local config"]
end

subgraph group_pkg["Packaging"]
  node_lantern_pkg["Package<br/>[__init__.py]"]
  node_pyproject["pyproject<br/>build config<br/>[pyproject.toml]"]
end

node_lantern_cli -->|"start/stop"| node_lantern_server
node_lantern_cli -->|"scan"| node_lantern_client
node_lantern_cli -->|"delegates"| node_lantern_scan_cli
node_lantern_cli -->|"rename/save"| node_config_json
node_lantern_scan_cli -->|"runs"| node_lantern_scan
node_lantern_scan -->|"refreshes"| node_lantern_client
node_lantern_server -->|"registers"| node_lantern_mdns
node_lantern_client -->|"queries"| node_lantern_mdns
node_lantern_mdns -->|"uses"| node_lantern_connection
node_lantern_client -->|"builds"| node_lantern_connection
node_lantern_server -->|"reads"| node_config_json
node_lantern_scan -->|"tracks"| node_lantern_connection
node_pyproject -->|"entrypoint"| node_lantern_cli
node_lantern_pkg -->|"contains"| node_lantern_cli
node_lantern_pkg -->|"contains"| node_lantern_server
node_lantern_pkg -->|"contains"| node_lantern_client

click node_lantern_cli "https://github.com/suryakiran46/lantern/blob/main/lantern/cli.py"
click node_lantern_scan_cli "https://github.com/suryakiran46/lantern/blob/main/lantern/scan_cli.py"
click node_lantern_server "https://github.com/suryakiran46/lantern/blob/main/lantern/server.py"
click node_lantern_mdns "https://github.com/suryakiran46/lantern/blob/main/lantern/mdns.py"
click node_lantern_client "https://github.com/suryakiran46/lantern/blob/main/lantern/client.py"
click node_lantern_scan "https://github.com/suryakiran46/lantern/blob/main/lantern/scan.py"
click node_lantern_connection "https://github.com/suryakiran46/lantern/blob/main/lantern/connection.py"
click node_lantern_pkg "https://github.com/suryakiran46/lantern/blob/main/lantern/__init__.py"
click node_pyproject "https://github.com/suryakiran46/lantern/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_lantern_cli,node_lantern_scan_cli toneBlue
class node_lantern_server,node_lantern_mdns toneAmber
class node_lantern_client,node_lantern_scan toneMint
class node_lantern_connection,node_config_json toneRose
class node_lantern_pkg,node_pyproject toneIndigo
```

## Components

### Terminal UI

Interactive command shell and scan frontend.

- [CLI shell](https://github.com/suryakiran46/lantern/blob/main/lantern/cli.py): interactive entrypoint · Main lantern> shell; dispatches user commands and orchestrates runtime actions. · `lantern/cli.py`
- [Scan CLI](https://github.com/suryakiran46/lantern/blob/main/lantern/scan_cli.py): scan frontend · Dedicated command-line path for live scanning and device listing. · `lantern/scan_cli.py`

### Presence Publishing

Local mDNS advertisement path for the current machine.

- [Server](https://github.com/suryakiran46/lantern/blob/main/lantern/server.py): mDNS advertiser · Publishes the local machine as a discoverable LAN service. · `lantern/server.py`
- [mDNS layer](https://github.com/suryakiran46/lantern/blob/main/lantern/mdns.py): multicast DNS · Shared mDNS helpers for registering and querying services on the subnet. · `lantern/mdns.py`

### Peer Discovery

LAN scanning and result collection over multicast DNS.

- [Client](https://github.com/suryakiran46/lantern/blob/main/lantern/client.py): peer discovery · Queries the LAN for lantern services and processes responses. · `lantern/client.py`
- [Live scan](https://github.com/suryakiran46/lantern/blob/main/lantern/scan.py): monitor loop · Maintains the live refresh loop and current visible device set. · `lantern/scan.py`

### Local State

Persistent identity and shared peer-record modeling.

- [Connection](https://github.com/suryakiran46/lantern/blob/main/lantern/connection.py): peer model · Shared connection or peer-record abstractions used by networking flows. · `lantern/connection.py`
- **config.json**: local config · Per-directory persisted display name and other small identity settings.

### Packaging

Package boundary and CLI installation metadata.

- [Package](https://github.com/suryakiran46/lantern/blob/main/lantern/__init__.py): package root · Python package boundary for the lantern application. · `lantern/__init__.py`
- [pyproject](https://github.com/suryakiran46/lantern/blob/main/pyproject.toml): build config · Packaging and entrypoint metadata for installing the lantern command. · `pyproject.toml`

## Connections

- CLI shell → Server: start/stop · Commands control local presence publishing.
- CLI shell → Client: scan · Commands trigger LAN peer discovery.
- CLI shell → Scan CLI: delegates · Interactive shell can hand off to the live scan workflow.
- CLI shell → config.json: rename/save · Updates local identity used for later advertising.
- Scan CLI → Live scan: runs · Scan frontend drives the live monitoring loop.
- Live scan → Client: refreshes · Live scan repeatedly uses discovery results.
- Server → mDNS layer: registers · Publishes the local device through mDNS.
- Client → mDNS layer: queries · Discovery reads multicast DNS announcements and responses.
- mDNS layer → Connection: uses · mDNS operations share peer/service data structures.
- Client → Connection: builds · Discovery results are normalized into peer records.
- Server → config.json: reads · Broadcast identity is derived from local saved settings.
- Live scan → Connection: tracks · Live device list is maintained as peer state.
- pyproject → CLI shell: entrypoint · Packaging exposes the interactive command.
- Package → CLI shell: contains · Package boundary includes the main shell module.
- Package → Server: contains · Package boundary includes the advertising runtime.
- Package → Client: contains · Package boundary includes the discovery runtime.
