README.md

metadata

title: Cuatro Labs Tracker
emoji: 🏭
colorFrom: yellow
colorTo: green
sdk: docker
pinned: false
short_description: Supply Chain Management - Merchant & Employee Management

Tracker Microservice

Employee tracking and attendance management microservice for the Cuatro Labs platform.

Features

Attendance Management

• Employee check-in with GPS coordinates
• Location tracking consent validation
• Geofence detection support
• Duplicate check-in prevention
• Daily attendance records

Architecture

Technology Stack

• Framework: FastAPI 0.104.1
• Database:
  • MongoDB (employee data, location settings)
  • PostgreSQL (attendance records)
• Authentication: JWT-based
• Server: Uvicorn with async support

Project Structure

app/
├── core/
│   ├── config.py           # Configuration settings
│   ├── logging.py          # Logging setup
│   └── database.py         # SQLAlchemy base
├── dependencies/
│   └── auth.py             # JWT authentication
├── tracker/
│   └── attendance/
│       ├── models.py       # SQLAlchemy models
│       ├── schemas.py      # Pydantic schemas
│       ├── service.py      # Business logic
│       ├── router.py       # API endpoints
│       └── constants.py    # Constants
├── main.py                 # Application entry point
├── nosql.py                # MongoDB connection
└── postgres.py             # PostgreSQL connection pool

API Endpoints

Attendance Endpoints

Check-In

POST /api/v1/attendance/check-in

Mark the start of an employee's working day.

Request Body:

{
  "timestamp": 1708156800000,
  "latitude": 19.0760,
  "longitude": 72.8777,
  "location_id": "loc_mumbai_office_001"
}

Response:

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Check-in successful"
}

Rules:

• Can check-in only once per day
• Location coordinates are mandatory
• GPS tracking must be enabled (checked from MongoDB)
• Optional location_id if inside a geofence

Edge Cases:

• Duplicate check-in → 400 error
• GPS disabled → 400 error

Database Schema

PostgreSQL - trans.scm_attendance

CREATE TABLE trans.scm_attendance (
    id UUID PRIMARY KEY,
    merchant_id UUID NOT NULL,
    employee_id UUID NOT NULL,
    work_date DATE NOT NULL,
    check_in_time BIGINT,
    check_in_lat DOUBLE PRECISION,
    check_in_lon DOUBLE PRECISION,
    check_in_geofence_id UUID,
    check_out_time BIGINT,
    check_out_lat DOUBLE PRECISION,
    check_out_lon DOUBLE PRECISION,
    total_minutes INTEGER,
    created_at TIMESTAMP DEFAULT now(),
    updated_at TIMESTAMP DEFAULT now(),
    UNIQUE (employee_id, work_date)
);

CREATE INDEX idx_scm_attendance_work_date 
ON trans.scm_attendance (employee_id, work_date);

CREATE INDEX idx_scm_attendance_merchant 
ON trans.scm_attendance (merchant_id, work_date);

MongoDB - scm_employees

Location tracking consent is checked from:

scm_employees.location_settings.location_tracking_consent

Environment Configuration

Copy .env.example to .env and configure:

# Application
APP_NAME=Tracker Microservice
APP_VERSION=1.0.0
DEBUG=false
LOG_LEVEL=INFO
PORT=8003

# MongoDB
MONGODB_URI=mongodb+srv://username:password@cluster0.2shrc.mongodb.net/?retryWrites=true&w=majority
MONGODB_DB_NAME=cuatrolabs

# PostgreSQL
DB_HOST=localhost
DB_PORT=5432
DB_NAME=cuatrolabs
DB_USER=postgres
DB_PASSWORD=your-password
DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/cuatrolabs

# JWT
SECRET_KEY=your-secret-key-change-in-production
ALGORITHM=HS256
TOKEN_EXPIRATION_HOURS=8

Getting Started

Prerequisites

• Python 3.11+
• MongoDB (Atlas or local)
• PostgreSQL

Local Development

1. Create and activate virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Configure environment:

cp .env.example .env
# Edit .env with your configuration

4. Run the service:

uvicorn app.main:app --host 0.0.0.0 --port 8003 --reload

5. Access API documentation:

• Swagger UI: http://localhost:8003/docs
• ReDoc: http://localhost:8003/redoc

Docker Deployment

# Build the image
docker build -t tracker-microservice .

# Run the container
docker run -p 8003:8003 --env-file .env tracker-microservice

Testing

Manual Testing with curl

# Health check
curl http://localhost:8003/health

# Check-in (requires JWT token)
curl -X POST http://localhost:8003/api/v1/attendance/check-in \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": 1708156800000,
    "latitude": 19.0760,
    "longitude": 72.8777,
    "location_id": "loc_mumbai_office_001"
  }'

Error Handling

The service provides structured error responses:

400 Bad Request - Business logic errors

{
  "success": false,
  "error": "Already checked in today",
  "detail": "You have already checked in for today"
}

401 Unauthorized - Invalid or missing JWT token

{
  "success": false,
  "error": "Unauthorized",
  "detail": "Invalid or expired token"
}

422 Validation Error - Invalid request data

{
  "success": false,
  "error": "Validation Error",
  "errors": [
    {
      "field": "latitude",
      "message": "Latitude must be between -90 and 90",
      "type": "value_error"
    }
  ]
}

500 Internal Server Error - Unexpected errors

{
  "success": false,
  "error": "Internal Server Error",
  "detail": "An unexpected error occurred"
}

Logging

The service uses structured JSON logging with the following levels:

• DEBUG: Detailed diagnostic information
• INFO: General informational messages
• WARNING: Warning messages for recoverable issues
• ERROR: Error messages for failures
• CRITICAL: Critical errors requiring immediate attention

License

Part of the Cuatro Labs platform.