Worksync - Works Activity Tracker

Worksync is a comprehensive SaaS platform designed to streamline workforce management through GPS-based attendance tracking, AI-powered daily reports, expense management, and real-time admin monitoring. Built with modern technologies and enterprise-grade security, Worksync empowers teams to work more productively while giving managers full visibility into their operations.

Overview

Worksync is a Works Activity Tracker that solves the fundamental challenges of managing distributed and hybrid teams. The platform combines four core functionalities into a single, unified interface:

GPS Attendance - Employees can check in and out with GPS location verification, selfie photos, and automatic reverse geocoding to determine their exact work location.
AI-Powered Reports - Daily report generation powered by DeepSeek AI. Employees simply describe their activities, and the AI structures them into professional, well-formatted reports.
Expense Management - Track team expenses with receipt photo uploads and automatic categorization for transparent reimbursement workflows.
Admin Monitoring Dashboard - Real-time monitoring with interactive maps, charts, and AI-powered analytics that answer natural language questions about team performance.

Worksync is designed for Indonesian companies and teams, with full Bahasa Indonesia support and localization. The platform handles all the complexities of attendance tracking, expense reporting, and performance monitoring so teams can focus on what matters most: getting work done.

Tech Stack

Frontend

Technology	Purpose
Vite 5	Build tool and dev server for fast HMR
React 18	UI library for building component-based interfaces
TypeScript	Type-safe JavaScript for better developer experience
Tailwind CSS 3	Utility-first CSS framework for rapid UI development
shadcn/ui	Reusable component library built on Radix UI primitives
React Router v6	Client-side routing for single-page application navigation
Zustand	Lightweight state management for global application state
Axios	HTTP client for API communication with the backend
Recharts	Composable charting library for data visualization
MapLibre GL	Open-source map rendering for real-time employee location tracking
lucide-react	Beautiful, consistent icon set for UI elements

Backend

Technology	Purpose
FastAPI	High-performance Python web framework for building REST APIs
SQLAlchemy	ORM for database interaction and model management
Alembic	Database migration tool for schema version control
PostgreSQL 16	Primary database for production data storage
DeepSeek API	AI integration for report generation and analytics (model: deepseek-v4-flash)
Polar.sh	Subscription billing platform for managing SaaS payments
Cloudinary	Cloud-based media management for storing photos and documents
BigDataCloud API	Reverse geocoding service for converting GPS coordinates to addresses
Mapcn.dev	Map tile provider for MapLibre GL integration

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Client Browser                        │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              React SPA (Vite + TypeScript)             │  │
│  │  ┌─────────┐ ┌──────────┐ ┌────────┐ ┌────────────┐  │  │
│  │  │   Auth  │ │Attendance│ │Expenses│ │  Reports   │  │  │
│  │  │  Pages  │ │  Pages   │ │ Pages  │ │   Pages    │  │  │
│  │  └─────────┘ └──────────┘ └────────┘ └────────────┘  │  │
│  │  ┌─────────┐ ┌──────────┐ ┌────────┐ ┌────────────┐  │  │
│  │  │  Admin  │ │  Billing │ │   AI   │ │  Maps &    │  │  │
│  │  │Dashboard│ │  Portal  │ │Assistant│ │ Monitoring │  │  │
│  │  └─────────┘ └──────────┘ └────────┘ └────────────┘  │  │
│  └───────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP/REST (Axios)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   FastAPI Backend (Python)                    │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐  │
│  │  Auth &  │ │Attendance│ │ Expenses │ │  Reports &   │  │
│  │  Users   │ │  Module  │ │  Module  │ │  AI Module  │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐  │
│  │  Admin   │ │ Billing  │ │Uploads/  │ │  External    │  │
│  │  Module  │ │  Module  │ │  Storage │ │   APIs       │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │           SQLAlchemy ORM + Alembic Migrations          │  │
│  └───────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────┘
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│  PostgreSQL  │ │  Cloudinary  │ │  DeepSeek    │
│   Database   │ │   Storage    │ │    AI API    │
└──────────────┘ └──────────────┘ └──────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│  Polar.sh    │ │ BigDataCloud │ │  Mapcn.dev   │
│  Billing     │ │  Geocoding   │ │  Map Tiles   │
└──────────────┘ └──────────────┘ └──────────────┘

The architecture follows a modern JAMstack pattern with a decoupled frontend and backend communicating via RESTful APIs. The frontend is a single-page application that handles all UI rendering, while the backend provides a comprehensive REST API with JWT-based authentication, role-based access control, and integration with various third-party services.

Prerequisites

Before setting up Worksync locally, ensure you have the following installed:

Node.js 18+ - JavaScript runtime for the frontend
Python 3.11+ - Python interpreter for the backend
PostgreSQL 16+ - Relational database (or use Docker)
Docker & Docker Compose (optional but recommended for PostgreSQL)
Git - Version control
npm or yarn - Package manager for Node.js
pip - Package manager for Python

Local Setup

1. Clone Repository

git clone <repo-url>
cd worksync

2. Setup Environment Variables

Copy the example environment files to create your local configuration:

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

Edit both .env files with your actual credentials. Refer to the Environment Variables section below for detailed descriptions.

3. Setup PostgreSQL

Option A: Using Docker (Recommended)

docker compose up db -d

This starts a PostgreSQL 16 Alpine container with the default credentials defined in docker-compose.yml:

User: worksync
Password: worksync_secret
Database: worksync
Port: 5432

Your backend .env file should then have:

DATABASE_URL=postgresql://worksync:worksync_secret@localhost:5432/worksync

Option B: Using Local PostgreSQL

createdb worksync

Or via psql:

CREATE DATABASE worksync;
CREATE USER worksync WITH PASSWORD 'worksync_secret';
GRANT ALL PRIVILEGES ON DATABASE worksync TO worksync;

4. Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload

The backend will be available at http://localhost:8000 with automatic API documentation at http://localhost:8000/docs.

Key backend commands:

Run migrations: alembic upgrade head
Create new migration: alembic revision --autogenerate -m "description"
Rollback migration: alembic downgrade -1
Run tests: pytest
Lint code: ruff check .

5. Frontend Setup

cd frontend
npm install
npm run dev

The frontend development server will start at http://localhost:5173 with Hot Module Replacement enabled.

Key frontend commands:

Development: npm run dev
Production build: npm run build
Preview build: npm run preview
Lint: npm run lint

6. Access the Application

Frontend: http://localhost:5173
Backend: http://localhost:8000
API Docs (Swagger UI): http://localhost:8000/docs
API Docs (ReDoc): http://localhost:8000/redoc

Environment Variables

Backend

Variable	Description	How to Get
`DATABASE_URL`	PostgreSQL connection string (e.g., `postgresql://user:pass@host:5432/db`)	Generated from your database setup
`SECRET_KEY`	JWT signing secret - must be a cryptographically secure random string	Run `openssl rand -hex 32`
`ALGORITHM`	JWT hashing algorithm	Set to `HS256`
`ACCESS_TOKEN_EXPIRE_MINUTES`	JWT token expiration time in minutes	Set to `30` (or your preferred value)
`CLOUDINARY_CLOUD_NAME`	Cloudinary cloud name	Cloudinary Dashboard
`CLOUDINARY_API_KEY`	Cloudinary API key	Cloudinary Dashboard
`CLOUDINARY_API_SECRET`	Cloudinary API secret	Cloudinary Dashboard
`DEEPSEEK_API_KEY`	DeepSeek API key for AI features	DeepSeek Platform
`DEEPSEEK_MODEL`	DeepSeek model name	Set to `deepseek-v4-flash`
`POLAR_ACCESS_TOKEN`	Polar.sh organization access token	Polar.sh Settings
`POLAR_WEBHOOK_SECRET`	Polar.sh webhook signing secret	Polar.sh Settings
`POLAR_FREE_PRODUCT_ID`	Polar.sh Free plan product ID	Polar.sh Products
`POLAR_PRO_PRODUCT_ID`	Polar.sh Pro plan product ID	Polar.sh Products
`POLAR_ENTERPRISE_PRODUCT_ID`	Polar.sh Enterprise plan product ID	Polar.sh Products
`BIGDATACLOUD_API_KEY`	BigDataCloud API key for reverse geocoding	BigDataCloud API Dashboard
`CORS_ORIGINS`	Comma-separated list of allowed CORS origins	Set to `http://localhost:5173` for development

Frontend

Variable	Description
`VITE_API_BASE_URL`	Backend API base URL (e.g., `http://localhost:8000/api/v1`)
`VITE_BIGDATACLOUD_API_KEY`	BigDataCloud API key for client-side reverse geocoding
`VITE_MAPCN_KEY`	Mapcn.dev API key for map tile access

Setup Manual Steps

Generate JWT Secret Key

openssl rand -hex 32

Copy the output and set it as the SECRET_KEY in your backend .env file.

Setup Polar.sh

Polar.sh handles all subscription billing and payment processing for Worksync. Follow these steps to set it up:

Create Account: Sign up at https://polar.sh
Create Organization: Set up your organization from the Polar.sh dashboard
Create Products: Create 3 subscription products matching Worksync's pricing:
- Free ($0/month) - Basic plan with limited features
- Pro ($9/month) - Full features for growing teams
- Enterprise ($29/month) - Unlimited access for large organizations
Get Access Token: Navigate to Organization Settings > API & Webhooks, and generate a new access token
Configure Webhook: Set your webhook URL to https://your-domain.com/api/v1/billing/webhook
Note Credentials: Save the following from Polar.sh Settings:
- Organization Access Token → POLAR_ACCESS_TOKEN
- Webhook Secret → POLAR_WEBHOOK_SECRET
- Product IDs for each plan → POLAR_*_PRODUCT_ID

Setup Cloudinary

Cloudinary stores user-uploaded images including attendance selfies and expense receipts.

Create Account: Register at https://cloudinary.com
Get Credentials: Navigate to Dashboard to find:
- Cloud Name → CLOUDINARY_CLOUD_NAME
- API Key → CLOUDINARY_API_KEY
- API Secret → CLOUDINARY_API_SECRET
Configure Upload: Set up unsigned upload presets if needed for client-side uploads

Setup BigDataCloud

BigDataCloud provides reverse geocoding services that convert GPS coordinates into human-readable addresses.

Create Account: Register at https://www.bigdatacloud.com
Get API Key: Navigate to your dashboard and generate a new API key
Set Key: Add the key to both backend (BIGDATACLOUD_API_KEY) and frontend (VITE_BIGDATACLOUD_API_KEY) environment variables

Setup DeepSeek

DeepSeek powers the AI features in Worksync, including automatic report generation and AI analytics.

Register: Sign up at https://platform.deepseek.com
Get API Key: Generate an API key from the platform dashboard

Set Configuration: Add to backend .env:

DEEPSEEK_API_KEY=your_api_key_here
DEEPSEEK_MODEL=deepseek-v4-flash

Setup PostgreSQL on Railway

If deploying to Railway, follow these steps for managed PostgreSQL:

Deploy PostgreSQL: From Railway Dashboard, click "New" → "Database" → "Add PostgreSQL"
Copy Connection String: Railway provides a DATABASE_URL environment variable automatically
Connect Backend: Set the DATABASE_URL in your backend Railway environment variables
Run Migrations: Railway will run alembic upgrade head automatically if configured in the start command

Run Migrations

cd backend
alembic upgrade head

To verify migration status:

alembic current

Setup Polar.sh Webhook

After deploying your application, configure the Polar.sh webhook:

Go to Polar.sh Organization Settings → API & Webhooks
Add webhook URL: https://your-app.railway.app/api/v1/billing/webhook
Subscribe to these events:
- subscription.created
- subscription.active
- subscription.canceled
- subscription.updated
- subscription.revoked
Copy the Webhook Secret and set it as POLAR_WEBHOOK_SECRET in your backend .env

Mobile Build (Android APK)

Worksync uses Capacitor to wrap the web app into a native Android APK.

Prerequisites

Java JDK 17+ — Download
Android Studio — Download
Android SDK 34 (install via Android Studio SDK Manager)

Build APK

# 1. Build frontend
cd frontend
npm run build

# 2. Sync web assets to native project
npx cap sync

# 3. Export JAVA_HOME (adjust path to your JDK)
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export ANDROID_HOME=$HOME/Android/Sdk

# 4. Build APK
cd android
./gradlew assembleDebug

APK location: frontend/android/app/build/outputs/apk/debug/app-debug.apk

Alternative: Build via Android Studio

cd frontend
npm run build
npx cap sync
npx cap open android

Then in Android Studio: Build → Build Bundle(s) / APK → Build APK

iOS Build (macOS only)

cd frontend
npm run build
npx cap sync
npx cap open ios

Requires Xcode and an Apple Developer account.

Desktop App (Electron)

cd frontend
npm run build
npx cap sync
npx cap open @capacitor-community/electron

Railway Deployment

Railway provides a streamlined deployment experience for full-stack applications. Follow these steps to deploy Worksync:

Prerequisites

A Railway account (https://railway.app)
Your code pushed to a GitHub repository

Steps

Create New Project: Click "New Project" in Railway dashboard
Deploy Backend:
- Click "Deploy from GitHub repo"
- Select your repository
- Set root directory to backend
- Railway auto-detects Python and sets the start command:
```
uvicorn app.main:app --host 0.0.0.0 --port $PORT
```
- Add all environment variables from backend .env
Deploy Frontend:
- Click "New" → "Deploy from GitHub repo"
- Set root directory to frontend
- Build command: npm run build
- Start command: npm run preview
- Add environment variables including VITE_API_BASE_URL pointing to your backend URL
Add PostgreSQL:
- Click "New" → "Database" → "Add PostgreSQL"
- Railway automatically creates the DATABASE_URL variable
- Reference it in your backend service
Configure Domains:
- Railway generates .railway.app URLs for each service
- Generate a public domain for frontend
- Update VITE_API_BASE_URL with the backend domain
Run Migrations: Use Railway CLI or add a post-deploy script:
```
railway run alembic upgrade head
```
Verify Deployment: Visit your frontend domain to confirm everything is working

Railway Configuration Tips

Use Railway's volume mounts for persistent storage of uploaded files
Enable health checks for the backend service
Configure automatic deployments from the main branch
Set up a custom domain for production

Features

Employee

The employee-facing features are designed for simplicity and ease of use:

GPS Attendance with Selfie
- Check-in and check-out with GPS location verification
- Selfie photo capture to prevent attendance fraud
- Automatic reverse geocoding showing the exact address
- Configurable geo-fence radius to restrict attendance to office locations
- Late arrival detection and automatic marking
- Attendance history with calendar view
Expense Tracking with Receipt Photo
- Quick expense recording with receipt photo upload
- Automatic categorization (transport, meals, supplies, etc.)
- Manual category override
- Pending/approved/rejected status tracking
- Expense history with monthly summaries
Daily Reports with AI Assistant
- Describe your day's activities in natural language
- AI structures and formats the report automatically
- Edit and approve AI-generated reports
- Report history with weekly/monthly views
- AI Assistant chat interface for report refinement
Personal History & Monitoring
- Personal attendance dashboard
- Expense history and status tracking
- Daily report archive
- Monthly productivity summary

Admin

The admin dashboard provides comprehensive management and monitoring capabilities:

Dashboard with Weekly Trend Charts
- Overview of attendance rates, expenses, and report completion
- Weekly trend charts for key metrics
- Team performance comparisons
- Quick stats cards for instant insights
Real-time Monitoring with Interactive Map
- Real-time employee locations on an interactive map
- Color-coded markers (checked-in, checked-out, late, absent)
- Click to view employee details and current status
- Office boundary visualization
- Historical location playback
Employee Management
- Employee list with detailed profiles
- Add/remove employees and manage roles
- Set individual work schedules and office locations
- View attendance and expense history per employee
- Export employee data
Late Arrival Notifications
- Real-time notifications when employees are late
- Push notifications for critical events
- Configurable late thresholds
- Notification history log
AI Analytics untuk Insight Data
- Natural language queries about team data
- "Who is frequently late this month?"
- "What is the total overtime cost?"
- "Which department has the highest expense?"
- Automatic insight generation
- Custom report generation
Excel Export (Pro+)
- One-click export of attendance data to Excel
- Expense reports in spreadsheet format
- Custom date range selection
- Ready for accounting and payroll processing
Subscription & Billing Management
- View current plan and usage
- Upgrade/downgrade subscription
- Billing history and invoice download
- Payment method management

API Usage

The Worksync API is fully documented via Swagger UI at /docs and ReDoc at /redoc when the backend is running.

Authentication

All API endpoints (except login/register) require a JWT Bearer token:

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@worksync.com", "password": "yourpassword"}'


# Use the returned token for subsequent requests
curl http://localhost:8000/api/v1/attendances \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

API Endpoints

Method	Endpoint	Description
POST	`/api/v1/auth/login`	User login
POST	`/api/v1/auth/refresh`	Refresh access token
GET	`/api/v1/auth/me`	Get current user profile
POST	`/api/v1/attendances/check-in`	Employee check-in
POST	`/api/v1/attendances/check-out`	Employee check-out
GET	`/api/v1/attendances/summary`	Get attendance summary
POST	`/api/v1/expenses`	Create expense record
GET	`/api/v1/expenses`	List expenses
POST	`/api/v1/reports`	Create daily report
POST	`/api/v1/ai/generate-report`	Generate AI report
POST	`/api/v1/ai/ask-analytics`	Ask AI analytics question
GET	`/api/v1/employees`	List employees (admin)
POST	`/api/v1/billing/create-checkout`	Create checkout session
GET	`/api/v1/billing/subscription`	Get subscription details
POST	`/api/v1/cloudinary/upload`	Upload file to Cloudinary

Rate Limiting

API endpoints are rate-limited to prevent abuse:

Anonymous: 20 requests/minute
Authenticated: 60 requests/minute
Pro/Enterprise: 120 requests/minute

Error Handling

All API errors follow a consistent format:

{
  "detail": "Error message describing what went wrong",
  "code": "ERROR_CODE",
  "status_code": 400
}

Contributing

We welcome contributions to Worksync! To contribute:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow the existing code style and conventions
Write tests for new features
Update documentation as needed
Ensure all tests pass before submitting PR
Use descriptive commit messages

Code Style

Frontend: ESLint + Prettier configuration is included
Backend: Ruff linter is configured for Python code
TypeScript: Strict mode is enabled; avoid using any

License

This software and its associated files are proprietary and confidential. Unauthorized copying, modification, distribution, reverse engineering, or use of this software, via any medium, is strictly prohibited without prior written permission from the copyright holder.

This software is provided "as is" without warranty of any kind. See the LICENSE file for the full legal text.

Worksync — AI-Powered Employee Activity Tracker
Build and Dev by FMA Software Labs 🔥

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
backend		backend
frontend		frontend
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

Worksync - Works Activity Tracker

Table of Contents

Overview

Tech Stack

Frontend

Backend

Architecture

Prerequisites

Local Setup

1. Clone Repository

2. Setup Environment Variables

3. Setup PostgreSQL

4. Backend Setup

5. Frontend Setup

6. Access the Application

Environment Variables

Backend

Frontend

Setup Manual Steps

Generate JWT Secret Key

Setup Polar.sh

Setup Cloudinary

Setup BigDataCloud

Setup DeepSeek

Setup PostgreSQL on Railway

Run Migrations

Setup Polar.sh Webhook

Mobile Build (Android APK)

Prerequisites

Build APK

Alternative: Build via Android Studio

iOS Build (macOS only)

Desktop App (Electron)

Railway Deployment

Prerequisites

Steps

Railway Configuration Tips

Features

Employee

Admin

API Usage

Authentication

API Endpoints

Rate Limiting

Error Handling

Contributing

Development Guidelines

Code Style

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages