A task management API with built-in productivity tracking. Built this to help organize projects and measure actual time spent on tasks through focus sessions.
Tasklytic is a RESTful API for managing tasks and projects while tracking how much time you actually spend working on them. The focus session feature lets you start a timer when you begin working on a task, giving you real insights into where your time goes versus what you estimated.
The core idea: organize tasks into projects, tag them for easy filtering, and track focus sessions to see how long things really take. Pretty useful for comparing estimated time against reality.
Backend:
- Ruby 3.3.6
- Rails 8.0.2 (latest version as of writing)
- PostgreSQL for data storage
- Redis for caching and job queuing
- Sidekiq for background job processing
Authentication:
- Devise for user management
- JWT tokens for API authentication
- Token revocation through a denylist system
API Documentation:
- Swagger/OpenAPI via rswag
- Interactive API docs at
/api-docs
Testing:
- RSpec for testing framework
- FactoryBot for test data
- Shoulda matchers for cleaner validations
Other Tools:
- Kaminari for pagination
- Active Model Serializers for JSON responses
- CORS support for frontend integration
- Docker setup included
Standard project management stuff - create projects, add tasks to them, set priorities (low, medium, high, urgent), and due dates. Tasks have statuses: pending, in_progress, completed, or cancelled.
Each task can have an estimated time in minutes, which becomes interesting when you compare it against actual focus time.
This is where it gets useful. Start a focus session when you begin working on a task, stop it when you're done. The system calculates:
- Total time spent per task
- Estimated vs. actual time (shows you if you're terrible at estimating, like most of us)
- Statistics across all your sessions
- Currently active session tracking
Tag your tasks however you want. The system tracks which tags are most used and lets you filter tasks by tags. Basic but effective.
The API supports filtering tasks by:
- Status (pending, in progress, etc.)
- Project
- Due date (overdue, due today, due this week)
- Priority level
- Tags
All list endpoints are paginated to keep things performant.
The architecture is straightforward Rails API:
-
Authentication Flow: Users sign up/login and get a JWT token. This token goes in the Authorization header for all subsequent requests. Logout revokes the token by adding it to a denylist.
-
Data Model: Users own Projects, Projects contain Tasks, Tasks can have many Tags (through a join table), and Tasks can have multiple FocusSession records. Each FocusSession tracks start time, end time, and duration.
-
Focus Session Logic: When you start a focus session, it records the start time. Only one session can be active at a time per user. When you stop it, the system calculates the duration in minutes and updates the task's total focus time.
-
Statistics: The models have methods that calculate useful metrics - project completion percentages, total focus hours, estimated vs actual time ratios. These feed into the API stats endpoints.
- Ruby 3.3.6
- PostgreSQL
- Redis (for Sidekiq)
Clone and install dependencies:
git clone <repository-url>
cd tasklytic
bundle installSet up the database:
rails db:create
rails db:migrate
rails db:seedStart Redis (in a separate terminal):
redis-serverStart Sidekiq (in another terminal):
bundle exec sidekiqRun the server:
rails serverThe API will be available at http://localhost:3000
If you prefer Docker:
docker-compose upCheck out the interactive API documentation at http://localhost:3000/api-docs after starting the server. It has a complete reference with examples you can try directly in the browser.
Quick example to get started:
# Sign up
curl -X POST http://localhost:3000/users/sign_up \
-H "Content-Type: application/json" \
-d '{"user": {"email": "test@example.com", "password": "password123", "first_name": "John", "last_name": "Doe"}}'
# Login (save the token from the Authorization header)
curl -X POST http://localhost:3000/users/sign_in \
-H "Content-Type: application/json" \
-d '{"user": {"email": "test@example.com", "password": "password123"}}'
# Create a project
curl -X POST http://localhost:3000/api/v1/projects \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"project": {"name": "My Project", "description": "Test project"}}'
# Create a task
curl -X POST http://localhost:3000/api/v1/tasks \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"task": {"title": "My Task", "status": "pending", "priority": "medium", "estimated_minutes": 60, "due_date": "2024-12-31", "project_id": 1}}'
# Start a focus session
curl -X POST http://localhost:3000/api/v1/focus_sessions \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"focus_session": {"task_id": 1}}'More detailed examples and all available endpoints are in API_DOCUMENTATION.md.
The test suite uses RSpec:
# Run all tests
bundle exec rspec
# Run specific test file
bundle exec rspec spec/models/task_spec.rb
# Run with coverage
COVERAGE=true bundle exec rspecapp/
├── controllers/
│ └── api/v1/ # API endpoints
├── models/ # Data models
│ ├── user.rb
│ ├── project.rb
│ ├── task.rb
│ ├── tag.rb
│ └── focus_session.rb
spec/ # Test suite
├── models/ # Model tests
├── controllers/ # Controller tests
└── requests/ # Integration tests
Key configuration files:
config/database.yml- Database settingsconfig/initializers/devise.rb- Authentication configconfig/initializers/cors.rb- CORS settings for frontend integrationconfig/routes.rb- API routes
Environment variables needed (create a .env file):
DATABASE_URL=postgresql://localhost/tasklytic_development
REDIS_URL=redis://localhost:6379/0
SECRET_KEY_BASE=your_secret_key
Currently on v1 (/api/v1/). All endpoints are versioned so breaking changes can be introduced in v2 without affecting existing clients.
- JWT tokens expire after 30 minutes by default (configurable in
config/initializers/devise.rb) - Pagination defaults to 10 items per page, max 50
- Only one focus session can be active per user at a time
- Tags are shared across all users (global)
- Deleting a project deletes all its tasks and associated focus sessions
Standard Rails API practices apply. Write tests for new features. The test suite should pass before submitting PRs.
MIT License - see LICENSE file for details.
Potential improvements:
- Pomodoro timer integration for focus sessions
- Task dependencies and subtasks
- Team collaboration features
- Analytics dashboard
- Mobile app
- Email notifications for due dates
- AI-powered task time estimation (there's already ruby-openai in the Gemfile for this)
Check the issues tab for planned features and known bugs.