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

Using Docker Compose

The easiest way to get started is to use Docker Compose:

docker compose up -d

This will start the API, PostgreSQL database with PostGIS and TimescaleDB extensions, and pgAdmin.

Local Development

For local development:

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

# Run the application
uvicorn app.main:app --reload

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