Skip to content

Tracker System Documentation

Welcome to the Tracker System documentation. This system consists of a REST API and an Admin Panel, allowing you to manage clients, brands, production runs, trackers, and locations.

Overview

The Tracker System is built with:

  • Backend API: FastAPI with PostgreSQL (PostGIS and TimescaleDB extensions)
  • Admin Panel: React with TypeScript and Tailwind CSS
  • User Frontend: React with TypeScript for end-user interfaces
  • Background Services: TaskiQ-based microservices for data processing
  • External Services: Dedicated fetcher services for Apple FindMy integration

Together, they provide a comprehensive solution for managing all aspects of the tracker system, with efficient storage and querying of geospatial and time-series data.

For a detailed overview of the system architecture, see the System Architecture documentation.

Features

API Features

  • Authentication: JWT-based authentication with role-based access control
  • Client Management: CRUD operations for clients, brands, and production runs
  • Tracker Management: CRUD operations for trackers and their status history
  • Location Tracking: Geospatial queries and location history tracking
  • PostgreSQL with PostGIS: Spatial database for location data
  • TimescaleDB: Time-series database for efficient storage and querying of time-series data

Admin Panel Features

  • User-friendly Interface: Modern, responsive UI for managing the system
  • Dashboard: Overview of system statistics and key metrics
  • User Management: Create, read, update, and delete users with role-based access
  • Client & Brand Management: Manage clients and their associated brands
  • Production Run Management: Create and monitor production runs
  • Tracker Management: Track and manage devices across production runs
  • Location Management: Manage delivery and storage locations with interactive maps
  • Dark Mode: Toggle between light and dark themes for better visibility

Quick Start

Docker-First Development

The recommended way to work on this project is with the development services in compose.yml. They mount the source tree into the containers, so code changes are picked up automatically and the apps reload without rebuilding the whole environment.

docker compose up -d

This starts the API, admin panel, frontend, database, cache, and worker services defined in compose.yml.

The long-running app containers are configured for live reload, so after the stack is up you usually just edit code and refresh the browser.

When You Need Python Locally

Use a local virtual environment only for tooling that is easier outside Docker, such as ad hoc scripts or one-off package inspection. It is not the primary development path for the application itself.

API Documentation

Once the API is running, you can access the OpenAPI documentation at:

Project Structure

app/
├── api/                  # API endpoints
│   ├── deps.py           # Dependencies for API routes
│   └── routes/           # API route handlers
├── core/                 # Core functionality
│   ├── config.py         # Configuration settings
│   ├── database.py       # Database connection
│   └── security.py       # Authentication and security
├── crud/                 # Database operations
├── models/               # SQLAlchemy models
├── schemas/              # Pydantic schemas
└── main.py               # Application entry point