# olalie/tapmap architecture

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

- Interactive diagram: https://gitdiagram.com/olalie/tapmap
- Repository: https://github.com/olalie/tapmap

## Overview

TapMap is a local network-activity visualizer. Its principal workflow scans sockets, identifies applications, enriches public IPs with GeoIP data, and renders live connections on a map. Separate branches provide rolling-history insights, daily reports, significant-connection events and notifications, unmapped-service and open-port views, and GeoIP database management. The app coordinates these features; sampled source confirms some internal calls, while other relationships below are grounded in the README. Unsampled implementation details are not inferred beyond documented capabilities.

Main entry points: [`src/tapmap/app.py`](https://github.com/olalie/tapmap/blob/main/src/tapmap/app.py) (Dash application), [`src/tapmap/model/model.py`](https://github.com/olalie/tapmap/blob/main/src/tapmap/model/model.py) (Snapshot builder), [`src/tapmap/runtime.py`](https://github.com/olalie/tapmap/blob/main/src/tapmap/runtime.py) (Runtime context), [`src/tapmap/geodb/service.py`](https://github.com/olalie/tapmap/blob/main/src/tapmap/geodb/service.py) (GeoDB management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and orchestration"]
  node_app["Dash application<br/>[app.py]"]
  node_runtime_ctx["Runtime context<br/>[runtime.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_app_dirs["App directories<br/>[app_dirs.py]"]
end

subgraph group_collection["Connection enrichment"]
  node_model["Snapshot builder<br/>[model.py]"]
  node_netinfo["Socket discovery<br/>[netinfo.py]"]
  node_appinfo["Application identity<br/>[app_info.py]"]
  node_geoinfo["IP geolocation<br/>[geoinfo.py]"]
  node_service_entries["Service bookkeeping<br/>[service_entries.py]"]
end

subgraph group_experience["Map and exploration"]
  node_map["Live map<br/>[map_view.py]"]
  node_service_view["Service details"]
  node_modal["Network tools<br/>[modal_view.py]"]
  node_unmapped["Unmapped services<br/>[unmapped_view.py]"]
end

subgraph group_history["History and insights"]
  node_connection_state["Connection state"]
  node_insights["Insights analytics<br/>[insights.py]"]
  node_insights_state["Insights state<br/>[insights_state.py]"]
  node_daily_report["Daily report analytics<br/>[daily_report.py]"]
  node_history_store[("History persistence")]
  node_significance["Significant events<br/>[significance.py]"]
  node_significant_store[("Event persistence")]
end

subgraph group_operations["Tools and integrations"]
  node_geodb["GeoDB management<br/>[service.py]"]
  node_maxmind["MaxMind provider<br/>[maxmind.py]"]
  node_dbip["DB-IP provider<br/>[dbip.py]"]
  node_notifications["Notification dispatch<br/>[channel.py]"]
  node_desktop_notify["Desktop notifications<br/>[desktop.py]"]
  node_mqtt_notify["MQTT notifications<br/>[mqtt.py]"]
  node_tray["System tray<br/>[tray.py]"]
  node_autostart["Login autostart<br/>[autostart.py]"]
end

node_user(("Desktop user"))
node_mqtt_broker(("MQTT broker"))

node_user -->|"opens"| node_app
node_app -->|"configures"| node_runtime_ctx
node_runtime_ctx -->|"reads defaults"| node_config
node_runtime_ctx -->|"resolves paths"| node_app_dirs
node_app -->|"requests snapshots"| node_model
node_model -->|"scans sockets"| node_netinfo
node_model -->|"enriches apps"| node_appinfo
node_model -->|"looks up IPs"| node_geoinfo
node_app -->|"manages databases"| node_geodb
node_geodb -->|"downloads and validates"| node_maxmind
node_geodb -->|"downloads and validates"| node_dbip
node_app -->|"updates state"| node_connection_state
node_connection_state -.->|"merges applications"| node_service_entries
node_app -->|"renders map"| node_map
node_app -->|"prepares map details"| node_service_view
node_app -->|"renders tool screens"| node_modal
node_app -->|"shows unmapped services"| node_unmapped
node_app -->|"analyzes activity"| node_insights
node_app -.->|"maintains history"| node_insights_state
node_insights_state -.->|"persists history"| node_history_store
node_app -.->|"builds report"| node_daily_report
node_app -.->|"records new activity"| node_significance
node_significance -.->|"persists events"| node_significant_store
node_app -.->|"dispatches events"| node_notifications
node_notifications -.->|"sends desktop alerts"| node_desktop_notify
node_notifications -.->|"publishes MQTT"| node_mqtt_notify
node_mqtt_notify -.->|"publishes events"| node_mqtt_broker
node_app -.->|"controls lifecycle"| node_tray
node_app -.->|"configures login launch"| node_autostart

click node_app "https://github.com/olalie/tapmap/blob/main/src/tapmap/app.py"
click node_runtime_ctx "https://github.com/olalie/tapmap/blob/main/src/tapmap/runtime.py"
click node_config "https://github.com/olalie/tapmap/blob/main/src/tapmap/config.py"
click node_app_dirs "https://github.com/olalie/tapmap/blob/main/src/tapmap/app_dirs.py"
click node_model "https://github.com/olalie/tapmap/blob/main/src/tapmap/model/model.py"
click node_netinfo "https://github.com/olalie/tapmap/blob/main/src/tapmap/model/netinfo.py"
click node_appinfo "https://github.com/olalie/tapmap/blob/main/src/tapmap/model/appinfo/app_info.py"
click node_geoinfo "https://github.com/olalie/tapmap/blob/main/src/tapmap/model/geoinfo.py"
click node_geodb "https://github.com/olalie/tapmap/blob/main/src/tapmap/geodb/service.py"
click node_maxmind "https://github.com/olalie/tapmap/blob/main/src/tapmap/geodb/maxmind.py"
click node_dbip "https://github.com/olalie/tapmap/blob/main/src/tapmap/geodb/dbip.py"
click node_service_entries "https://github.com/olalie/tapmap/blob/main/src/tapmap/state/service_entries.py"
click node_map "https://github.com/olalie/tapmap/blob/main/src/tapmap/ui/map_view.py"
click node_service_view "https://github.com/olalie/tapmap/blob/main/src/tapmap/ui/service_point_view.py"
click node_modal "https://github.com/olalie/tapmap/blob/main/src/tapmap/ui/modal_view.py"
click node_unmapped "https://github.com/olalie/tapmap/blob/main/src/tapmap/ui/unmapped_view.py"
click node_connection_state "https://github.com/olalie/tapmap/blob/main/src/tapmap/state/connection_state.py"
click node_insights "https://github.com/olalie/tapmap/blob/main/src/tapmap/state/insights.py"
click node_insights_state "https://github.com/olalie/tapmap/blob/main/src/tapmap/state/insights_state.py"
click node_daily_report "https://github.com/olalie/tapmap/blob/main/src/tapmap/state/daily_report.py"
click node_history_store "https://github.com/olalie/tapmap/blob/main/src/tapmap/insights_persistence.py"
click node_significance "https://github.com/olalie/tapmap/blob/main/src/tapmap/state/significance.py"
click node_significant_store "https://github.com/olalie/tapmap/blob/main/src/tapmap/significant_connections_persistence.py"
click node_notifications "https://github.com/olalie/tapmap/blob/main/src/tapmap/notifications/channel.py"
click node_desktop_notify "https://github.com/olalie/tapmap/blob/main/src/tapmap/notifications/desktop.py"
click node_mqtt_notify "https://github.com/olalie/tapmap/blob/main/src/tapmap/notifications/mqtt.py"
click node_tray "https://github.com/olalie/tapmap/blob/main/src/tapmap/tray.py"
click node_autostart "https://github.com/olalie/tapmap/blob/main/src/tapmap/state/autostart.py"

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_app,node_runtime_ctx,node_config,node_app_dirs,node_user toneBlue
class node_model,node_netinfo,node_appinfo,node_geoinfo,node_service_entries toneAmber
class node_map,node_service_view,node_modal,node_unmapped toneMint
class node_connection_state,node_insights,node_insights_state,node_daily_report,node_history_store,node_significance,node_significant_store toneRose
class node_geodb,node_maxmind,node_dbip,node_notifications,node_desktop_notify,node_mqtt_notify,node_tray,node_autostart,node_mqtt_broker toneIndigo
```

## Components

### Runtime and orchestration

- [Dash application](https://github.com/olalie/tapmap/blob/main/src/tapmap/app.py): `src/tapmap/app.py`
- [Runtime context](https://github.com/olalie/tapmap/blob/main/src/tapmap/runtime.py): `src/tapmap/runtime.py`
- [Configuration](https://github.com/olalie/tapmap/blob/main/src/tapmap/config.py): `src/tapmap/config.py`
- [App directories](https://github.com/olalie/tapmap/blob/main/src/tapmap/app_dirs.py): `src/tapmap/app_dirs.py`

### Connection enrichment

- [Snapshot builder](https://github.com/olalie/tapmap/blob/main/src/tapmap/model/model.py): `src/tapmap/model/model.py`
- [Socket discovery](https://github.com/olalie/tapmap/blob/main/src/tapmap/model/netinfo.py): `src/tapmap/model/netinfo.py`
- [Application identity](https://github.com/olalie/tapmap/blob/main/src/tapmap/model/appinfo/app_info.py): `src/tapmap/model/appinfo/app_info.py`
- [IP geolocation](https://github.com/olalie/tapmap/blob/main/src/tapmap/model/geoinfo.py): `src/tapmap/model/geoinfo.py`
- [Service bookkeeping](https://github.com/olalie/tapmap/blob/main/src/tapmap/state/service_entries.py): `src/tapmap/state/service_entries.py`

### Map and exploration

- [Live map](https://github.com/olalie/tapmap/blob/main/src/tapmap/ui/map_view.py): `src/tapmap/ui/map_view.py`
- [Service details](https://github.com/olalie/tapmap/blob/main/src/tapmap/ui/service_point_view.py): `src/tapmap/ui/service_point_view.py`
- [Network tools](https://github.com/olalie/tapmap/blob/main/src/tapmap/ui/modal_view.py): `src/tapmap/ui/modal_view.py`
- [Unmapped services](https://github.com/olalie/tapmap/blob/main/src/tapmap/ui/unmapped_view.py): `src/tapmap/ui/unmapped_view.py`

### History and insights

- [Connection state](https://github.com/olalie/tapmap/blob/main/src/tapmap/state/connection_state.py): `src/tapmap/state/connection_state.py`
- [Insights analytics](https://github.com/olalie/tapmap/blob/main/src/tapmap/state/insights.py): `src/tapmap/state/insights.py`
- [Insights state](https://github.com/olalie/tapmap/blob/main/src/tapmap/state/insights_state.py): `src/tapmap/state/insights_state.py`
- [Daily report analytics](https://github.com/olalie/tapmap/blob/main/src/tapmap/state/daily_report.py): `src/tapmap/state/daily_report.py`
- [History persistence](https://github.com/olalie/tapmap/blob/main/src/tapmap/insights_persistence.py): `src/tapmap/insights_persistence.py`
- [Significant events](https://github.com/olalie/tapmap/blob/main/src/tapmap/state/significance.py): `src/tapmap/state/significance.py`
- [Event persistence](https://github.com/olalie/tapmap/blob/main/src/tapmap/significant_connections_persistence.py): `src/tapmap/significant_connections_persistence.py`

### Tools and integrations

- [GeoDB management](https://github.com/olalie/tapmap/blob/main/src/tapmap/geodb/service.py): `src/tapmap/geodb/service.py`
- [MaxMind provider](https://github.com/olalie/tapmap/blob/main/src/tapmap/geodb/maxmind.py): `src/tapmap/geodb/maxmind.py`
- [DB-IP provider](https://github.com/olalie/tapmap/blob/main/src/tapmap/geodb/dbip.py): `src/tapmap/geodb/dbip.py`
- [Notification dispatch](https://github.com/olalie/tapmap/blob/main/src/tapmap/notifications/channel.py): `src/tapmap/notifications/channel.py`
- [Desktop notifications](https://github.com/olalie/tapmap/blob/main/src/tapmap/notifications/desktop.py): `src/tapmap/notifications/desktop.py`
- [MQTT notifications](https://github.com/olalie/tapmap/blob/main/src/tapmap/notifications/mqtt.py): `src/tapmap/notifications/mqtt.py`
- [System tray](https://github.com/olalie/tapmap/blob/main/src/tapmap/tray.py): `src/tapmap/tray.py`
- [Login autostart](https://github.com/olalie/tapmap/blob/main/src/tapmap/state/autostart.py): `src/tapmap/state/autostart.py`

### Other components

- **Desktop user**
- **MQTT broker**

## Connections

- Desktop user → Dash application: opens (evidence: `README.md`)
- Dash application → Runtime context: configures (evidence: `src/tapmap/app.py`)
- Runtime context → Configuration: reads defaults (evidence: `src/tapmap/runtime.py`)
- Runtime context → App directories: resolves paths (evidence: `src/tapmap/runtime.py`)
- Dash application → Snapshot builder: requests snapshots (evidence: `src/tapmap/app.py`)
- Snapshot builder → Socket discovery: scans sockets (evidence: `src/tapmap/model/model.py`)
- Snapshot builder → Application identity: enriches apps (evidence: `src/tapmap/model/model.py`)
- Snapshot builder → IP geolocation: looks up IPs (evidence: `src/tapmap/model/model.py`)
- Dash application → GeoDB management: manages databases (evidence: `src/tapmap/app.py`)
- GeoDB management → MaxMind provider: downloads and validates (evidence: `src/tapmap/geodb/service.py`)
- GeoDB management → DB-IP provider: downloads and validates (evidence: `src/tapmap/geodb/service.py`)
- Dash application → Connection state: updates state (evidence: `src/tapmap/app.py`)
- Connection state → Service bookkeeping: merges applications
- Dash application → Live map: renders map (evidence: `README.md`)
- Dash application → Service details: prepares map details (evidence: `src/tapmap/ui/service_point_view.py`)
- Dash application → Network tools: renders tool screens (evidence: `src/tapmap/app.py`)
- Dash application → Unmapped services: shows unmapped services
- Dash application → Insights analytics: analyzes activity (evidence: `src/tapmap/app.py`)
- Dash application → Insights state: maintains history (evidence: `src/tapmap/app.py`)
- Insights state → History persistence: persists history (evidence: `src/tapmap/insights_persistence.py`)
- Dash application → Daily report analytics: builds report
- Dash application → Significant events: records new activity (evidence: `src/tapmap/app.py`)
- Significant events → Event persistence: persists events
- Dash application → Notification dispatch: dispatches events
- Notification dispatch → Desktop notifications: sends desktop alerts
- Notification dispatch → MQTT notifications: publishes MQTT
- MQTT notifications → MQTT broker: publishes events (evidence: `README.md`)
- Dash application → System tray: controls lifecycle (evidence: `README.md`)
- Dash application → Login autostart: configures login launch (evidence: `README.md`)