# seym45/traccar architecture

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

- Interactive diagram: https://gitdiagram.com/seym45/traccar
- Repository: https://github.com/seym45/traccar

## Overview

##### Project Type and Purpose
- This is a Java-based, backend-only, monolithic GPS tracking server (Traccar).
- It listens for device connections over various protocols (TCP/UDP/HTTP/MQTT), decodes incoming GPS messages, processes them (geofencing, events, notifications), stores data in an SQL database, and exposes a REST API (plus WebSocket) for clients (e.g., web app, mobile apps).

##### File-Structure Highlights & Architectural Indicators
- Top-level:
- src/main/java/org/traccar – the entire Java codebase, organized by function (protocols, API, storage, handler, session, schedule, etc.).
- schema/ – Liquibase changelogs for database migrations.
- setup/ – scripts for packaging, installation, init (systemd, Windows service).
- templates/ – Velocity templates for notifications and reports.
- tools/ – Python/ shell utilities for docs/tests.
- Presence of BaseProtocol, PipelineBuilder, ServerManager → custom network server (likely built on Netty).
- org.traccar.api → REST layer built on Jersey (servlets, resources, filters).
- org.traccar.storage → abstraction over JDBC/Hibernate storage and in-memory for testing.
- org.traccar.session → in-memory session management and cache modules.
- org.traccar.schedule → scheduled tasks (inactivity checks, report generation).
- org.traccar.forward & broadcast → external integrations (Kafka, AMQP, Redis, HTTP).

##### Key README Insights
- Open-source GPS tracking backend with REST API
- Supports any SQL database, real-time tracking, reports, geofencing, notifications via email/SMS

a. External Entities (Clients & Devices)
- GPS Devices (variety of protocols)
- Administrative Clients (Web App, Mobile Apps using REST/API/WebSocket)

b. Network Listeners
- TCP/UDP Server (TrackerServer)
- HTTP Server (API endpoints & webhooks)
- MQTT Server (optional if configured)

c. Protocol Processing Layer
- Frame Decoders (CharacterDelimiterFrameDecoder, Protocol-specific decoders)
- Protocol Handlers → BaseProtocolDecoder, BaseDataHandler
- PipelineBuilder (assembles Netty pipeline)

d. Core Services
- Session Manager (DeviceSession, ConnectionManager, CacheManager)
- Event Loop & GlobalTimer (scheduling of periodic tasks)
- Schedule Manager (TaskDeviceInactivityCheck, TaskReports, etc.)
- Geocoder & Geolocation Providers
- Geofence Service & Handlers
- Notification Service (MailManager, SmsManager, NotificatorManager)
- Forwarding Service (EventForwarderKafka/Amqp/Mqtt, PositionForwarderJson/Url, etc.)
- Broadcast Service (Redis, Multicast)

e. Persistence Layer
- DatabaseModule → DatabaseStorage (JDBC/Hibernate)
- Liquibase (schema changelogs in schema/)
- In-memory storage (for testing)

f. API Layer
- Jersey REST Resources (org.traccar.api.resource)
- Filters & Security (CorsResponseFilter, SecurityRequestFilter)
- Asynchronous WebSocket/SocketServlet for real-time updates

g. External Integrations
- SQL Database (PostgreSQL/MySQL/… )
- Redis (optional caching/broadcast)
- SMTP / SMS Gateways
- Kafka / AMQP Brokers

##### Relationships & Data Flows
1. Device → Network Listener (TCP/UDP/HTTP/MQTT)
2. Listener → PipelineBuilder → Frame Decoders → Protocol Decoder → DataHandler → Core Services
3. Core Services → Persistence (store Position, Event, etc.)
4. Core Services → Notifications & Forwarding → External Services
5. API Clients → HTTP REST → API Layer → Core Services / Storage
6. API Clients → WebSocket → Session Manager → Broadcast Service → Client

##### Architectural Patterns & Principles
- Layered Architecture: Network → Protocol → Core Services → Persistence → API
- Pipeline Pattern: Netty pipeline for frame decoding & handling
- Dependency Injection: Google Guice (MainModule, WebModule, DatabaseModule)
- Asynchronous & Event-Driven: Netty’s EventLoopGroup, async socket IO
- Plugin-style Protocol Support: dozens of protocol decoder implementations
- Scheduled Tasks: Quartz-like scheduling via ScheduleManager

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    subgraph "External Clients & Devices"
        direction TB
        GPS["GPS Devices"]:::external
        Admin["Admin Clients (Web/Mobile via REST/WebSocket)"]:::external
    end

    %% Network Listeners
    subgraph "Network Layer"
        direction TB
        Tracker["TrackerServer (TCP/UDP)"]:::network
        HTTP["HTTP Server (REST/Webhooks)"]:::network
        MQTT["MQTT Server"]:::network
    end

    %% Protocol Processing
    subgraph "Protocol Processing" 
        direction TB
        Pipeline["PipelineBuilder"]:::processing
        FrameBase["BaseFrameDecoder"]:::processing
        FrameChar["CharacterDelimiterFrameDecoder"]:::processing
        ProtoDec["Protocol Decoder & DataHandler"]:::processing
    end

    %% Core Services
    subgraph "Core Services"
        direction TB
        subgraph "Session Management"
            direction TB
            ConnMgr["ConnectionManager"]:::core
            Session["DeviceSession"]:::core
            Cache["CacheManager"]:::core
        end
        subgraph "Scheduling"
            direction TB
            Schedule["ScheduleManager"]:::core
            Inactivity["TaskDeviceInactivityCheck"]:::core
            Reports["TaskReports"]:::core
        end
        Geocode["Geocoder"]:::core
        Geoloc["GeolocationProvider"]:::core
        Geofence["GeofenceHandler"]:::core
        subgraph "Notification"
            direction TB
            NotifMgr["NotificatorManager"]:::core
            Mail["SmtpMailManager"]:::core
            Sms["SmsManager"]:::core
            NotMail["NotificatorMail"]:::core
            NotSms["NotificatorSms"]:::core
            NotTel["NotificatorTelegram"]:::core
        end
        subgraph "Forwarding"
            direction TB
            FwdKafka["EventForwarderKafka"]:::core
            FwdAmqp["EventForwarderAmqp"]:::core
            FwdMqtt["EventForwarderMqtt"]:::core
        end
        subgraph "Broadcast"
            direction TB
            Broadcast["BroadcastService"]:::core
            RedBc["RedisBroadcastService"]:::core
            MultiBc["MulticastBroadcastService"]:::core
        end
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        Storage["Storage (Storage & Modules)"]:::persistence
        DbStorage["DatabaseStorage (JDBC/Hibernate)"]:::persistence
        MemStorage["MemoryStorage"]:::persistence
        DbModule["DatabaseModule (Guice)"]:::persistence
        Liquibase["Liquibase Changelogs"]:::persistence
    end

    %% API Layer
    subgraph "API Services"
        direction TB
        Resources["Jersey REST Resources"]:::api
        CorsFilter["CorsResponseFilter"]:::api
        SecFilter["SecurityRequestFilter"]:::api
        WebSocket["AsyncSocketServlet (WebSocket)"]:::api
        WebServer["WebServer & Static Content"]:::api
        Console["ConsoleServlet / DefaultServlet"]:::api
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        DB["SQL Database"]:::external
        REDIS["Redis"]:::external
        SMTP["SMTP/SMS Gateways"]:::external
        BROKER["Kafka/AMQP Brokers"]:::external
    end

    %% Data Flows
    GPS --> Tracker
    GPS --> HTTP
    GPS --> MQTT

    Tracker --> Pipeline
    HTTP --> Pipeline
    MQTT --> Pipeline

    Pipeline --> FrameBase
    Pipeline --> FrameChar
    FrameBase --> ProtoDec
    FrameChar --> ProtoDec

    ProtoDec --> ConnMgr
    ConnMgr --> Session
    Session --> Cache

    ProtoDec --> Schedule
    Schedule --> Inactivity
    Schedule --> Reports

    ProtoDec --> Geocode
    ProtoDec --> Geoloc

    ProtoDec --> Geofence

    ProtoDec --> NotifMgr
    NotifMgr --> Mail
    NotifMgr --> Sms
    Mail --> NotMail
    Sms --> NotSms
    NotifMgr --> NotTel

    ProtoDec --> FwdKafka
    ProtoDec --> FwdAmqp
    ProtoDec --> FwdMqtt

    ProtoDec --> Broadcast
    Broadcast --> RedBc
    Broadcast --> MultiBc

    %% Persistence interactions
    ConnMgr --> DbStorage
    Schedule --> DbStorage
    Geofence --> DbStorage
    NotifMgr --> DbStorage
    FwdKafka --> DbStorage
    Broadcast --> DbStorage

    DbStorage --> Liquibase
    DbStorage --> DbModule
    DbModule --> Storage
    Storage --> MemStorage

    Storage --> DB
    RedBc --> REDIS
    FwdKafka --> BROKER
    FwdAmqp --> BROKER

    %% API Interactions
    Admin --> Resources
    Resources --> ProtoDec
    Resources --> DbStorage
    Admin --> WebSocket
    WebSocket --> Broadcast
    Admin --> WebServer
    WebServer --> Console

    CorsFilter --> Resources
    SecFilter --> Resources

    %% Click Events
    click Tracker "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/TrackerServer.java"
    click HTTP "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/BaseHttpProtocolDecoder.java"
    click MQTT "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/BaseMqttProtocolDecoder.java"
    click Pipeline "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/PipelineBuilder.java"
    click FrameBase "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/BaseFrameDecoder.java"
    click FrameChar "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/CharacterDelimiterFrameDecoder.java"
    click ConnMgr "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/session/ConnectionManager.java"
    click Session "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/session/DeviceSession.java"
    click Cache "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/session/cache/CacheManager.java"
    click Schedule "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/schedule/ScheduleManager.java"
    click Inactivity "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/schedule/TaskDeviceInactivityCheck.java"
    click Reports "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/schedule/TaskReports.java"
    click Geocode "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/geocoder/Geocoder.java"
    click Geoloc "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/geolocation/GeolocationProvider.java"
    click Geofence "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/handler/GeofenceHandler.java"
    click NotifMgr "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/notification/NotificatorManager.java"
    click Mail "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/mail/SmtpMailManager.java"
    click Sms "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/sms/SmsManager.java"
    click NotMail "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/notificators/NotificatorMail.java"
    click NotSms "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/notificators/NotificatorSms.java"
    click NotTel "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/notificators/NotificatorTelegram.java"
    click FwdKafka "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/forward/EventForwarderKafka.java"
    click FwdAmqp "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/forward/EventForwarderAmqp.java"
    click FwdMqtt "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/forward/EventForwarderMqtt.java"
    click Broadcast "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/broadcast/BroadcastService.java"
    click RedBc "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/broadcast/RedisBroadcastService.java"
    click MultiBc "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/broadcast/MulticastBroadcastService.java"
    click Storage "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/storage/Storage.java"
    click DbStorage "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/storage/DatabaseStorage.java"
    click MemStorage "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/storage/MemoryStorage.java"
    click DbModule "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/storage/DatabaseModule.java"
    click Liquibase "https://github.com/seym45/traccar/tree/master/schema/"
    click Resources "https://github.com/seym45/traccar/tree/master/src/main/java/org/traccar/api/resource/"
    click CorsFilter "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/api/CorsResponseFilter.java"
    click SecFilter "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/api/SecurityRequestFilter.java"
    click WebSocket "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/api/AsyncSocketServlet.java"
    click WebServer "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/web/WebServer.java"
    click Console "https://github.com/seym45/traccar/blob/master/src/main/java/org/traccar/web/ConsoleServlet.java"
    classDef network fill:#cfe2f3,stroke:#2a65a0,color:#0b2e7a
    classDef processing fill:#d9ead3,stroke:#3c763d,color:#274e13
    classDef core fill:#d0e0e3,stroke:#1b4f72,color:#0f2a44
    classDef persistence fill:#f9cb9c,stroke:#a65f03,color:#783f04
    classDef api fill:#d9d2e9,stroke:#4b0082,color:#28144e
    classDef external fill:#e7e6e6,stroke:#444444,color:#000000
```
