# TimeTrack

> TimeTrack is an open-source time tracking SaaS for teams. It provides persistent timers, project management, team collaboration, reporting, and Stripe-powered billing. Built with FastAPI, React, MongoDB, and Clerk authentication.

TimeTrack is designed to be self-hostable and developer-friendly. The API exposes 79 endpoints across 16 modules, with a complete OpenAPI 3.1 specification. The platform also includes a Model Context Protocol (MCP) server for AI assistant integration.

## Documentation

- [Getting Started](https://docs.timetracker.cargoffer.com/getting-started.html): Set up TimeTrack locally with Docker Compose in under 5 minutes.
- [API Reference](https://docs.timetracker.cargoffer.com/api-reference.html): Complete reference for all 79 REST endpoints with parameters, request bodies, and responses.
- [Integrations](https://docs.timetracker.cargoffer.com/integrations.html): Connect TimeTrack with Stripe, Clerk, AI assistants, and your own tools.
- [OpenAPI Spec (JSON)](https://docs.timetracker.cargoffer.com/api/openapi.json): Machine-readable OpenAPI 3.1 specification.
- [OpenAPI Spec (YAML)](https://docs.timetracker.cargoffer.com/api/openapi.yaml): Human-readable OpenAPI 3.1 specification.

## Live Resources

- Application: https://timetracker.cargoffer.com/
- API Base: https://api.timetracker.cargoffer.com
- Swagger UI: https://api.timetracker.cargoffer.com/api/docs
- API Health: https://api.timetracker.cargoffer.com/api/v1/health

## Source Code

- Backend (FastAPI): https://github.com/cargoffer/timetracker_back
- Frontend (React): https://github.com/cargoffer/timetracker_front
- Landing (Next.js): https://github.com/cargoffer/timetracker_landing
- MCP Server (FastMCP): https://github.com/cargoffer/timetracker_mcp

## Key Features

- **Persistent timer** with one-click start/stop from any page
- **Project hierarchy**: Organization → Clients → Projects → Tasks
- **Team management**: Members, roles (admin/manager/member), invitations
- **Time entries**: Manual entry, timer-based, with idle detection and overtime warnings
- **Reports**: Summary, detailed, weekly, attendance, and CSV export
- **Billing**: Stripe Checkout subscriptions, customer portal, webhooks
- **API access**: Programmatic access with usage tracking and rate limits
- **MCP server**: Manage time, projects, and tasks from Claude/ChatGPT
- **Multi-language**: English, Spanish, Galician
- **PWA**: Installable web app with offline support
- **i18n**: Fully translatable frontend

## Tech Stack

**Backend:**
- FastAPI 0.115 (Python 3.12)
- MongoDB 7 via Motor (async driver)
- Redis 7 (caching, sessions)
- Clerk JWT for authentication
- Stripe SDK for billing
- pytest + httpx for testing

**Frontend:**
- React 19 + Vite 6
- TypeScript
- Tailwind CSS + shadcn/ui
- Zustand for state management
- react-i18next (en, es, gal)
- Clerk React SDK
- PWA with service worker

**Infrastructure:**
- Cloudflare Pages (static frontend)
- Coolify (backend deploy)
- MongoDB cluster
- Redis cluster
- Docker for all services

## Authentication

TimeTrack uses Clerk for authentication. Two methods supported:

1. **Clerk JWT**: User-context requests from the frontend. JWT obtained via Clerk React SDK.
2. **API Keys**: Server-to-server. Create via `POST /api/v1/api-keys` or in account settings.

All authenticated requests use Bearer token:
```
Authorization: Bearer eyJhbGc...
```

## API Endpoints by Module

### Health (3 endpoints)
- `GET /api/v1/health` - Service health check
- `GET /api/v1/ready` - Database readiness check
- `GET /api/v1/config` - Public configuration (Clerk publishable key)

### Time Entries (10 endpoints)
- `GET /api/v1/time-entries/active` - Get the user's active timer
- `PUT /api/v1/time-entries/active` - Update active entry
- `GET /api/v1/time-entries/recent` - Recent entries
- `POST /api/v1/time-entries/start` - Start a new timer
- `POST /api/v1/time-entries/stop` - Stop the active timer
- `POST /api/v1/time-entries` - Create manual entry
- `GET /api/v1/time-entries/{entry_id}` - Get entry by ID
- `PUT /api/v1/time-entries/{entry_id}` - Update entry
- `DELETE /api/v1/time-entries/{entry_id}` - Delete entry
- `POST /api/v1/time-entries/{entry_id}/location` - Attach geolocation

### Projects (5 endpoints)
- `GET /api/v1/projects` - List projects
- `POST /api/v1/projects` - Create project
- `GET /api/v1/projects/{project_id}` - Get project details
- `PUT /api/v1/projects/{project_id}` - Update project
- `DELETE /api/v1/projects/{project_id}` - Delete project

### Tasks (4 endpoints)
- `GET /api/v1/projects/{project_id}/tasks` - List tasks for a project
- `POST /api/v1/projects/{project_id}/tasks` - Create task
- `PUT /api/v1/projects/tasks/{task_id}` - Update task
- `DELETE /api/v1/projects/tasks/{task_id}` - Delete task

### Clients (5 endpoints)
- `GET /api/v1/clients` - List clients
- `POST /api/v1/clients` - Create client
- `GET /api/v1/clients/{client_id}` - Get client
- `PUT /api/v1/clients/{client_id}` - Update client
- `DELETE /api/v1/clients/{client_id}` - Delete client

### Organization (9 endpoints)
- `GET /api/v1/organization` - Get current organization
- `POST /api/v1/organization` - Create organization
- `PUT /api/v1/organization` - Update organization
- `GET /api/v1/organization/all` - List all user orgs
- `POST /api/v1/organization/{org_id}/invite` - Invite member
- `GET /api/v1/organization/{org_id}/members` - List members
- And more...

### Members (5 endpoints)
- `GET /api/v1/members` - List members
- `POST /api/v1/members/invite` - Invite new member
- `PUT /api/v1/members/{member_id}/role` - Change role
- `PUT /api/v1/members/{member_id}/status` - Activate/deactivate
- `DELETE /api/v1/members/{member_id}` - Remove member

### Reports (5 endpoints)
- `POST /api/v1/reports/summary` - Summary report
- `POST /api/v1/reports/detailed` - Detailed entries report
- `POST /api/v1/reports/weekly` - Weekly breakdown
- `POST /api/v1/reports/attendance` - Attendance report
- `POST /api/v1/reports/export/csv` - CSV export

### Dashboard (3 endpoints)
- `GET /api/v1/dashboard/active-now` - Currently active members
- `GET /api/v1/dashboard/today` - Today's totals
- `GET /api/v1/dashboard/week` - Weekly summary

### Billing (5 endpoints)
- `GET /api/v1/billing/plans` - Available subscription plans
- `POST /api/v1/billing/create-checkout-session` - Start Stripe Checkout
- `POST /api/v1/billing/create-portal-session` - Open customer portal
- `GET /api/v1/billing/subscription` - Current subscription
- `POST /api/v1/billing/webhook` - Stripe webhook handler

### API Keys (5 endpoints)
- `GET /api/v1/api-keys` - List user's API keys
- `POST /api/v1/api-keys` - Create new key (returns raw key once)
- `DELETE /api/v1/api-keys/{key_id}` - Revoke key
- `GET /api/v1/api-keys/stats` - Usage statistics
- `GET /api/v1/api-keys/export` - Export keys

### Leaves (5 endpoints)
- `GET /api/v1/leaves` - List leaves
- `POST /api/v1/leaves` - Request leave
- `PUT /api/v1/leaves/{leave_id}/status` - Approve/reject
- `GET /api/v1/holidays` - Organization holidays
- `POST /api/v1/holidays` - Add holiday

### Timesheets (5 endpoints)
- `GET /api/v1/timesheets` - List timesheets
- `GET /api/v1/timesheets/current` - Current week timesheet
- `POST /api/v1/timesheets/submit` - Submit for approval
- `POST /api/v1/timesheets/approve/{id}` - Approve
- `POST /api/v1/timesheets/reject/{id}` - Reject

### Pomodoro (7 endpoints)
- `GET /api/v1/pomodoro/config` - Get Pomodoro settings
- `PUT /api/v1/pomodoro/config` - Update settings
- `POST /api/v1/pomodoro/start` - Start a Pomodoro session
- `POST /api/v1/pomodoro/pause` - Pause session
- `POST /api/v1/pomodoro/resume` - Resume session
- `POST /api/v1/pomodoro/complete` - Complete session
- `GET /api/v1/pomodoro/stats` - Pomodoro statistics

### User (2 endpoints)
- `GET /api/v1/user/teams` - User's teams
- `PUT /api/v1/user/active-team` - Switch active team

### Geo (1 endpoint)
- `POST /api/v1/time-entries/{entry_id}/location` - Add GPS to entry

## Common Use Cases

### Start a timer via API
```bash
curl -X POST https://api.timetracker.cargoffer.com/api/v1/time-entries/start \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "proj_123", "task_id": "task_456", "description": "Working on feature X"}'
```

### Get this week's hours
```bash
curl -X POST https://api.timetracker.cargoffer.com/api/v1/reports/weekly \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"week_start": "2026-07-06"}'
```

### Create an API key
```bash
curl -X POST https://api.timetracker.cargoffer.com/api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production server"}'
```

## MCP Integration

TimeTrack provides a Model Context Protocol (MCP) server for AI assistant integration. Compatible with Claude Desktop, ChatGPT with custom GPTs, and other MCP clients.

The MCP server exposes tools like:
- `start_timer` - Start a timer via natural language
- `stop_timer` - Stop the active timer
- `create_project` - Create a new project
- `log_hours` - Log time manually
- `get_report` - Generate reports

MCP endpoint: https://mcp.timetracker.cargoffer.com (SSE transport on port 8000)

## Self-Hosting

Deploy your own instance with Docker Compose:

```bash
git clone https://github.com/cargoffer/timetracker_back.git
cd timetracker_back
cp .env.example .env
# Edit .env with your credentials
docker-compose up -d
```

Environment variables required:
- `CLERK_PUBLISHABLE_KEY` - Clerk frontend key
- `CLERK_SECRET_KEY` - Clerk backend secret
- `MONGODB_URL` - MongoDB connection string
- `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD` - Redis connection
- `STRIPE_SECRET_KEY` - Stripe API key
- `STRIPE_WEBHOOK_SECRET` - Stripe webhook signing secret

## License

MIT License - See https://github.com/cargoffer/timetracker_back/blob/main/LICENSE