HelixTrack Core - Complete User Guide Book

Comprehensive guide with 28 chapters covering all features, tutorials, and best practices

HelixTrack Core - Complete User Guide

Version 2.0

The Open-Source JIRA Alternative for the Free World

Welcome

Welcome to the complete user guide for HelixTrack Core - a modern, powerful, and fully open-source project management and issue tracking system. This guide will help you master all aspects of HelixTrack Core, from basic setup to advanced enterprise deployments.

What is HelixTrack Core?

HelixTrack Core is a production-ready REST API service that provides 85%+ JIRA feature parity with a fully open architecture. Built with Go and designed for the free world, it offers:

✅ 235 API Endpoints - Complete feature coverage
✅ Multi-Database Support - SQLite and PostgreSQL
✅ Multi-Tenancy - Enterprise-ready organizational hierarchy
✅ Agile/Scrum - Full sprint and board management
✅ Workflow Engine - Customizable ticket workflows
✅ Git Integration - Track commits and code changes
✅ Custom Fields - 11 field types for flexibility
✅ Extensions - Pluggable architecture for additional features

Who This Guide Is For

This guide is designed for:

Developers - Learn the API and integrate HelixTrack into your applications
System Administrators - Deploy and configure HelixTrack in production
Project Managers - Understand features and capabilities
Team Leads - Set up workflows and manage teams
Contributors - Extend and customize HelixTrack

Guide Structure

Introduction

What is HelixTrack Core? Key features and capabilities, Architecture overview, Comparison with JIRA.

Installation

System requirements, Installation methods, Initial configuration, Quick start guide.

Configuration

Configuration file structure, Database setup, Service integration, SSL/HTTPS configuration.

Authentication & Authorization

JWT authentication, Permission system, User management, Security best practices.

API Fundamentals

Request/response format, Action-based routing, Error handling, Testing with curl and Postman.

Data Model

Core entities (tickets, projects, users), Relationships and mappings, Soft delete pattern, Database schema V2.0.

Priority & Resolution Management

Setting up priorities, Defining resolutions, Best practices.

Version Management

Creating versions, Affected vs. fix versions, Release tracking, Version lifecycle.

Watcher & Notification System

Adding watchers, Notification subscriptions, Managing notifications.

Custom Fields

Field types overview, Creating custom fields, Field options (select, multi-select), Using custom field values.

Saved Filters

Creating filters, Sharing filters, Advanced filter criteria.

Workflow Engine

Understanding workflows, Creating workflows, Workflow steps and transitions, Ticket statuses and types.

Agile & Scrum

Board management, Sprint/Cycle planning, Story points and estimation, Velocity tracking.

Multi-Tenancy

Account structure, Organizations and teams, User assignments, Permission contexts.

Components & Labels

Project components, Label management, Label categories, Component metadata.

Asset Management

Uploading files, Attaching assets to tickets, Asset metadata, File types and limits.

Git Integration

Repository management, Linking commits to tickets, Repository types, Commit tracking.

Ticket Relationships

Relationship types, Creating relationships, Blocking dependencies, Parent/child hierarchies.

System Administration

Permission management, Audit logging, Report builder, Extension registry.

Complete API Reference

All 235 endpoints, Request/response examples, Authentication requirements, Error codes.

Common Scenarios

Setting up a new project, Creating a sprint, Managing a release, Custom workflow examples.

Integration Examples

Web application integration, Mobile app integration, CI/CD integration, Webhook examples.

Advanced Use Cases

Multi-project management, Enterprise hierarchies, Complex workflows, Custom reporting.

Hands-On Exercises

Exercise 1: Basic ticket management, Exercise 2: Sprint planning, Exercise 3: Custom workflows, Exercise 4: Reporting and analytics.

Troubleshooting Guide

Common issues and solutions, Log analysis, Performance tuning, Database maintenance.

Best Practices

Configuration best practices, Security hardening, Performance optimization, Backup and recovery.

Extending HelixTrack

Extension architecture, Creating custom extensions, API client development, Contributing to core.

Database Schema

Complete schema documentation, Table relationships, Indexes and constraints, Migration guide.

How to Use This Guide

For New Users

Start with Part I: Getting Started to install and configure HelixTrack Core. Then move to Part II: Core Concepts to understand the fundamentals.

For Developers

Jump to Part II: Core Concepts for API fundamentals, then explore Part IV: API Reference for complete endpoint documentation.

For Administrators

Focus on Part I: Getting Started for installation, Part VII: Troubleshooting & Maintenance for operations, and Part IV: System Administration for management.

For Power Users

Explore Part III: Feature Guides for comprehensive feature documentation, and Part V: Practical Examples for real-world scenarios.

Conventions Used in This Guide

Code Examples

# Shell commands are shown with # comments
curl -X POST http://localhost:8080/do

{
  "comment": "JSON examples are formatted for readability"
}

Callout Boxes

Note: Important information that helps clarify concepts

Warning: Critical information to prevent errors or data loss

Tip: Helpful suggestions and best practices

Navigation

📖 Reading: Informational content
🔧 Exercise: Hands-on practice
💡 Example: Real-world scenarios
⚠️ Important: Critical information

Getting Help

Documentation: This guide and USER_MANUAL.md
API Reference: API_REFERENCE_COMPLETE.md
Implementation Details: IMPLEMENTATION_SUMMARY.md
GitHub Issues: Report bugs and request features
Community: Join our community discussions

About This Guide

Version: 2.0

Last Updated: October 11, 2025

API Version: 2.0.0

Coverage: 235 API Endpoints

This guide is maintained alongside the HelixTrack Core codebase and is updated with each release.

Ready to Begin?

Start your journey with Chapter 1: Introduction →

HelixTrack Core - The Open-Source JIRA Alternative for the Free World 🚀