# manishcooks/packetjourney architecture

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

- Interactive diagram: https://gitdiagram.com/manishcooks/packetjourney
- Repository: https://github.com/manishcooks/packetjourney

## Overview

PacketJourney accepts a hostname in its React interface, runs a server-side traceroute, enriches discovered hops with geographic data, and streams hop details back over WebSockets. Once tracing finishes, the interface requests separate map and graph views, which render the cached route. The graph preserves both visualization branches and the HTTP/WebSocket routing layers. Relationships are shown where excerpts or the README support them; unsampled configuration and implementation details are not inferred.

Main entry points: [`backend/mainapp/consumers.py`](https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/consumers.py) (Traceroute Consumer), [`frontend/src/App.tsx`](https://github.com/manishcooks/packetjourney/blob/main/frontend/src/App.tsx) (Traceroute UI), [`backend/mainapp/views.py`](https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/views.py) (Visualization Views), [`frontend/src/main.tsx`](https://github.com/manishcooks/packetjourney/blob/main/frontend/src/main.tsx) (React Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app_entry["React Entry<br/>[main.tsx]"]
  node_app["Traceroute UI<br/>[App.tsx]"]
end

subgraph group_transport["Backend Routing"]
  node_asgi["ASGI Dispatcher<br/>[asgi.py]"]
  node_ws_routes["WebSocket Routes<br/>[routing.py]"]
  node_http_routes["HTTP Routes<br/>[urls.py]"]
end

subgraph group_trace["Traceroute Processing"]
  node_consumer["Traceroute Consumer<br/>[consumers.py]"]
  node_traceroute["Traceroute Process"]
  node_locations["IP Geolocation<br/>[locations.py]"]
  node_route_cache[("Route Cache")]
end

subgraph group_visuals["Route Visualizations"]
  node_views["Visualization Views<br/>[views.py]"]
  node_map["Map Renderer<br/>[map.py]"]
  node_graph["Graph Renderer<br/>[graph.py]"]
end

node_user(("User"))
node_ipapi{{"ipapi Service"}}

node_user -->|"opens app"| node_app_entry
node_app_entry -->|"renders"| node_app
node_app -->|"opens WebSocket"| node_asgi
node_asgi -->|"routes WebSockets"| node_ws_routes
node_ws_routes -->|"dispatches to"| node_consumer
node_app -->|"sends hostname"| node_consumer
node_consumer -->|"runs command"| node_traceroute
node_consumer -->|"looks up hops"| node_locations
node_locations -->|"requests location"| node_ipapi
node_consumer -->|"streams hop data"| node_app
node_consumer -->|"writes route"| node_route_cache
node_app -->|"requests views"| node_http_routes
node_http_routes -->|"dispatches to"| node_views
node_views -->|"reads route"| node_route_cache
node_views -->|"renders map"| node_map
node_views -->|"renders graph"| node_graph
node_views -->|"serves iframe views"| node_app

click node_app_entry "https://github.com/manishcooks/packetjourney/blob/main/frontend/src/main.tsx"
click node_app "https://github.com/manishcooks/packetjourney/blob/main/frontend/src/App.tsx"
click node_asgi "https://github.com/manishcooks/packetjourney/blob/main/backend/traceviz/asgi.py"
click node_ws_routes "https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/routing.py"
click node_http_routes "https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/urls.py"
click node_consumer "https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/consumers.py"
click node_locations "https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/locations.py"
click node_views "https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/views.py"
click node_map "https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/map.py"
click node_graph "https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/graph.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_entry,node_app,node_user toneBlue
class node_asgi,node_ws_routes,node_http_routes toneAmber
class node_consumer,node_traceroute,node_locations,node_route_cache,node_ipapi toneMint
class node_views,node_map,node_graph toneRose
```

## Components

### Frontend

- [React Entry](https://github.com/manishcooks/packetjourney/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Traceroute UI](https://github.com/manishcooks/packetjourney/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Backend Routing

- [ASGI Dispatcher](https://github.com/manishcooks/packetjourney/blob/main/backend/traceviz/asgi.py): `backend/traceviz/asgi.py`
- [WebSocket Routes](https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/routing.py): `backend/mainapp/routing.py`
- [HTTP Routes](https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/urls.py): `backend/mainapp/urls.py`

### Traceroute Processing

- [Traceroute Consumer](https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/consumers.py): `backend/mainapp/consumers.py`
- **Traceroute Process**
- [IP Geolocation](https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/locations.py): `backend/mainapp/locations.py`
- **Route Cache**

### Route Visualizations

- [Visualization Views](https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/views.py): `backend/mainapp/views.py`
- [Map Renderer](https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/map.py): `backend/mainapp/map.py`
- [Graph Renderer](https://github.com/manishcooks/packetjourney/blob/main/backend/mainapp/graph.py): `backend/mainapp/graph.py`

### Other components

- **User**
- **ipapi Service**

## Connections

- User → React Entry: opens app (evidence: `frontend/src/main.tsx`)
- React Entry → Traceroute UI: renders (evidence: `frontend/src/main.tsx`)
- Traceroute UI → ASGI Dispatcher: opens WebSocket (evidence: `frontend/src/App.tsx`)
- ASGI Dispatcher → WebSocket Routes: routes WebSockets (evidence: `backend/traceviz/asgi.py`)
- WebSocket Routes → Traceroute Consumer: dispatches to (evidence: `backend/mainapp/routing.py`)
- Traceroute UI → Traceroute Consumer: sends hostname (evidence: `frontend/src/App.tsx`)
- Traceroute Consumer → Traceroute Process: runs command (evidence: `backend/mainapp/consumers.py`)
- Traceroute Consumer → IP Geolocation: looks up hops (evidence: `backend/mainapp/consumers.py`)
- IP Geolocation → ipapi Service: requests location (evidence: `backend/mainapp/locations.py`)
- Traceroute Consumer → Traceroute UI: streams hop data (evidence: `backend/mainapp/consumers.py`)
- Traceroute Consumer → Route Cache: writes route (evidence: `backend/mainapp/consumers.py`)
- Traceroute UI → HTTP Routes: requests views (evidence: `frontend/src/App.tsx`)
- HTTP Routes → Visualization Views: dispatches to (evidence: `backend/mainapp/urls.py`)
- Visualization Views → Route Cache: reads route (evidence: `backend/mainapp/views.py`)
- Visualization Views → Map Renderer: renders map (evidence: `backend/mainapp/views.py`)
- Visualization Views → Graph Renderer: renders graph (evidence: `backend/mainapp/views.py`)
- Visualization Views → Traceroute UI: serves iframe views (evidence: `frontend/src/App.tsx`)
