# hamedsafikhani/zx303-gps architecture

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

- Interactive diagram: https://gitdiagram.com/hamedsafikhani/zx303-gps
- Repository: https://github.com/hamedsafikhani/zx303-gps

## Overview

zx303-GPS is a TCP server for ZX303 GPS trackers. Trackers connect and send protocol packets; the server interprets requests, returns device responses, records logs and location reports, and can retrieve queued messages for a device. The README also describes configuring the tracker by SMS and setting up geocoding. The source excerpt shows PostgreSQL writes and a Google Maps import, but does not establish geocoding call paths; those links are therefore omitted.

Main entry points: [`GPS.py`](https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py) (Client handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_network["TCP service"]
  node_server["TCP listener<br/>[GPS.py]"]
  node_accept["Connection acceptor<br/>[GPS.py]"]
  node_handler["Client handler<br/>[GPS.py]"]
end

subgraph group_protocol["Device protocol"]
  node_dispatch["Packet dispatch<br/>[GPS.py]"]
  node_responses["Response builders<br/>[GPS.py]"]
  node_gps["GPS positioning<br/>[GPS.py]"]
  node_lbs["LBS positioning<br/>[GPS.py]"]
end

subgraph group_data["Persistence"]
  node_db[("PostgreSQL")]
end

node_tracker(("GPS tracker"))
node_sms(("SMS configuration"))

node_server -->|"starts"| node_accept
node_tracker -->|"connects"| node_server
node_accept -->|"dispatches"| node_handler
node_handler -->|"passes packets"| node_dispatch
node_dispatch -->|"builds replies"| node_responses
node_dispatch -->|"routes GPS"| node_gps
node_dispatch -->|"routes LBS"| node_lbs
node_handler -->|"logs and queries"| node_db
node_gps -->|"writes positions"| node_db
node_lbs -->|"writes positions"| node_db
node_handler -->|"sends replies"| node_tracker
node_sms -.->|"configures"| node_tracker

click node_server "https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py"
click node_accept "https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py"
click node_handler "https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py"
click node_dispatch "https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py"
click node_responses "https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py"
click node_gps "https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py"
click node_lbs "https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.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_server,node_accept,node_handler toneBlue
class node_dispatch,node_responses,node_gps,node_lbs toneAmber
class node_db toneMint
class node_tracker,node_sms toneIndigo
```

## Components

### TCP service

- [TCP listener](https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py): `GPS.py`
- [Connection acceptor](https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py): `GPS.py`
- [Client handler](https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py): `GPS.py`

### Device protocol

- [Packet dispatch](https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py): `GPS.py`
- [Response builders](https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py): `GPS.py`
- [GPS positioning](https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py): `GPS.py`
- [LBS positioning](https://github.com/hamedsafikhani/zx303-gps/blob/master/GPS.py): `GPS.py`

### Persistence

- **PostgreSQL**

### Other components

- **GPS tracker**
- **SMS configuration**

## Connections

- TCP listener → Connection acceptor: starts
- GPS tracker → TCP listener: connects
- Connection acceptor → Client handler: dispatches
- Client handler → Packet dispatch: passes packets
- Packet dispatch → Response builders: builds replies
- Packet dispatch → GPS positioning: routes GPS
- Packet dispatch → LBS positioning: routes LBS
- Client handler → PostgreSQL: logs and queries
- GPS positioning → PostgreSQL: writes positions
- LBS positioning → PostgreSQL: writes positions
- Client handler → GPS tracker: sends replies
- SMS configuration → GPS tracker: configures