Traccar Architecture

Traccar runs as a Java application with two main network interfaces: Netty handles GPS device protocols, and an embedded Jetty server serves the web application and API. Both use the same storage and application services.

Server Components

Main uses Google Guice to assemble the application from configuration and starts the protocol listeners, web server, scheduler, and broadcast service. ServerManager loads enabled protocols with configured ports. Each protocol class defines its transport handlers, decoder, and supported commands.

The scheduler handles work that does not depend on an incoming position, including scheduled reports, device inactivity checks, and session timeouts. The configuration reference describes the available options.

Device Connections and Netty

For each network channel, BasePipelineFactory builds a Netty pipeline with transport and protocol-specific handlers, followed by shared processing and connection management. TCP and UDP are supported; some protocols use HTTP or other framing on top of their transport.

Typical protocol handlers include:

• Frame decoder: separates a TCP byte stream into complete messages. Datagram and HTTP protocols use their own message boundaries.
• String decoder and encoder: convert between text and network buffers for text-based protocols.
• Protocol decoder: identifies the device session and converts a message into one or more common Position objects. It can also handle login messages, acknowledgements, and other messages that do not produce a position.
• Protocol encoder: converts supported Command objects into device-specific messages for outgoing traffic.

Shared network handlers provide logging, timeouts, optional forwarding of raw traffic, and connection cleanup. ConnectionManager tracks device sessions and status; MainEventHandler handles network errors and disconnections.

Position Processing

Decoded positions enter ProcessingHandler. It optionally buffers out-of-order data and queues processing separately for each device, so one position finishes before the next position for that device is processed.

The main processing sequence is:

1. Normalize and enrich: apply computed attributes, time and coordinate handling, optional network geolocation and map matching, and distance calculations.
2. Filter and complete: discard positions that match configured filters, then process geofences, addresses, speed limits, motion, drivers, copied attributes, and engine hours. Optional handlers depend on configuration and available services.
3. Forward and store: optionally forward position data to another system, then pass it to DatabaseHandler. PositionBatchWriter supports immediate inserts or configured batch writes; processing resumes when the storage operation completes.
4. Generate events: event handlers examine the processed position for alarms, motion changes, geofence crossings, speeding, and other conditions.
5. Publish the latest position: PostProcessHandler updates the device's current position in storage and the cache, then notifies live clients through ConnectionManager. Older historical positions do not replace a newer current position.

These position and event handlers are coordinated by ProcessingHandler; they are not individual Netty pipeline stages. Filtered positions skip the remaining processing and event generation. Optional external services, such as reverse geocoding, are called by the relevant handlers.

Commands

API requests pass commands to CommandsManager. For an active session that supports live commands, the command travels through the protocol's outbound handlers to the device. Commands can also be stored in a queue for later delivery, sent through a configured command sender, or sent over SMS when supported and configured.

Command support and delivery behavior depend on the protocol. Commands do not pass backwards through position enrichment, filtering, or storage handlers.

Events and Notifications

Device-reported alarms and server-derived conditions both produce Event objects. Position event handlers are one source; connection status changes, scheduled inactivity checks, and queued-command handling can also generate events.

NotificationManager stores events, optionally forwards them to another system, and matches them to notification rules and users with device access. Event age, calendars, and other rule conditions determine whether a notification is sent. Saving an event does not mean that every user receives it.

Delivery is implemented by Notificator classes. Configurable channels include web notifications over WebSocket, email, SMS, Firebase and Traccar push notifications, Telegram, WhatsApp, and Pushover. A command notificator can also trigger a device command. Enabled channels are controlled by notificator.types and their provider settings.

Storage and Cache

Application services use the Storage abstraction. The SQL implementation, DatabaseStorage, uses JDBC with a HikariCP connection pool. Supported databases include H2, PostgreSQL, MySQL, MariaDB, and Microsoft SQL Server. Liquibase creates and upgrades the schema using XML changelogs.

Positions, events, users, devices, permissions, and queued commands share this storage layer. CacheManager keeps active device data, recent positions, and related objects in memory for processing and notification lookups. API changes invalidate the relevant cached objects and permissions, so use the API instead of editing database records directly.

For multi-instance deployments, the optional BroadcastService uses Redis or multicast to exchange device and position updates, user event notifications, command signals, and cache invalidations. It complements shared database storage; it does not replace it. A single instance does not require a broadcast backend.

Web Server and API

Embedded Jetty serves the static web application and the following interfaces:

• REST API (/api/*): implemented with Jersey and Jakarta REST. Resources handle management operations, history and reports, commands, and other application functions. JSON serialization uses Jackson.
• WebSocket (/api/socket): sends initial latest positions and subsequent device status, position, and web notification updates. Clients can also request live protocol logs.
• Optional MCP endpoint (/api/mcp): enabled with web.mcp.enable for integrations using the Model Context Protocol.

REST resources enforce authentication and permissions. WebSocket connections authenticate with a session or token, and ConnectionManager delivers updates according to user device access. See the API documentation for authentication and endpoint details.

Web Application

The web application lives in the separate traccar-web repository, included as a submodule in the server repository. It uses React, Material UI, Redux Toolkit, React Router, and MapLibre GL for maps. Vite builds the static files served by Jetty.

The web app uses REST requests to load and manage data, and WebSocket messages for live updates. Map tiles and other map resources come from the configured map providers.