HelixTrack Core - User Manual

Complete guide for installation, configuration, and usage

HelixTrack Core - User Manual

Table of Contents

  1. Introduction
  2. Installation
  3. Configuration
  4. Running the Application
  5. API Reference
  6. Testing
  7. Troubleshooting
  8. Architecture

Introduction

HelixTrack Core is a production-ready, modern REST API service built with Go and the Gin Gonic framework. It serves as the main microservice for the HelixTrack project - a JIRA alternative for the free world.

Current Status: ✅ Version 3.0.0 - Full JIRA Parity Achieved

Key Features

System Requirements

Installation

From Source

  1. Clone the repository:
    git clone <repository-url>
    cd Core/Application
  2. Install dependencies:
    go mod download
  3. Build the application:
    go build -o htCore main.go

Binary Installation

Download the pre-built binary for your platform from the releases page and place it in your PATH.

Configuration

HelixTrack Core uses JSON configuration files located in the Configurations/ directory.

Configuration File Structure

{
  "log": {
    "log_path": "/tmp/htCoreLogs",
    "logfile_base_name": "htCore",
    "log_size_limit": 100000000,
    "level": "info"
  },
  "listeners": [
    {
      "address": "0.0.0.0",
      "port": 8080,
      "https": false
    }
  ],
  "database": {
    "type": "sqlite",
    "sqlite_path": "Database/Definition.sqlite"
  },
  "services": {
    "authentication": {
      "enabled": false,
      "url": "http://localhost:8081",
      "timeout": 30
    },
    "permissions": {
      "enabled": false,
      "url": "http://localhost:8082",
      "timeout": 30
    }
  }
}

Configuration Options

Log Configuration

Listener Configuration

Database Configuration

SQLite:

{
  "type": "sqlite",
  "sqlite_path": "Database/Definition.sqlite"
}

PostgreSQL:

{
  "type": "postgres",
  "postgres_host": "localhost",
  "postgres_port": 5432,
  "postgres_user": "htcore",
  "postgres_password": "secret",
  "postgres_database": "htcore",
  "postgres_ssl_mode": "disable"
}

Services Configuration

Environment-Specific Configurations

Create different configuration files for different environments:

Running the Application

Basic Usage

# Run with default configuration
./htCore

# Run with custom configuration
./htCore -config=/path/to/config.json

# Show version
./htCore -version

Running in Development Mode

# With SQLite (no external dependencies)
./htCore -config=Configurations/dev.json

Running in Production

# With PostgreSQL and all services enabled
./htCore -config=Configurations/production.json

Docker Deployment

# Build Docker image
docker build -t helixtrack-core:latest .

# Run container
docker run -d \
  -p 8080:8080 \
  -v /path/to/config.json:/app/config.json \
  -v /path/to/database:/app/Database \
  helixtrack-core:latest

API Reference

Unified `/do` Endpoint

All API operations use the `/do` endpoint with action-based routing.

Request Format

{
  "action": "string",      // Required: action to perform
  "jwt": "string",         // Required for authenticated actions
  "locale": "string",      // Optional: locale for localized responses
  "object": "string",      // Required for CRUD operations
  "data": {}               // Additional action-specific data
}

Response Format

{
  "errorCode": -1,                    // -1 means success
  "errorMessage": "string",           // Error message (if any)
  "errorMessageLocalised": "string",  // Localized error message
  "data": {}                          // Response data
}

Public Endpoints (No Authentication Required)

Version

Get API version information.

Request:

{
  "action": "version"
}

Response:

{
  "errorCode": -1,
  "data": {
    "version": "1.0.0",
    "api": "1.0.0"
  }
}

JWT Capable

Check if JWT authentication is available.

Request:

{
  "action": "jwtCapable"
}

Response:

{
  "errorCode": -1,
  "data": {
    "jwtCapable": true,
    "enabled": true
  }
}

DB Capable

Check database availability and health.

Request:

{
  "action": "dbCapable"
}

Response:

{
  "errorCode": -1,
  "data": {
    "dbCapable": true,
    "type": "sqlite"
  }
}

Health

Get service health status.

Request:

{
  "action": "health"
}

Response:

{
  "errorCode": -1,
  "data": {
    "status": "healthy",
    "checks": {
      "database": "healthy",
      "authService": "enabled",
      "permissionService": "enabled"
    }
  }
}

Authentication Endpoint

Authenticate

Authenticate user credentials.

Request:

{
  "action": "authenticate",
  "data": {
    "username": "testuser",
    "password": "testpass"
  }
}

Response:

{
  "errorCode": -1,
  "data": {
    "username": "testuser",
    "role": "admin",
    "name": "Test User"
  }
}

Protected Endpoints (Authentication Required)

Create

Create a new entity.

Request:

{
  "action": "create",
  "jwt": "your-jwt-token",
  "object": "project",
  "data": {
    "name": "New Project",
    "description": "Project description"
  }
}

Modify

Modify an existing entity.

Request:

{
  "action": "modify",
  "jwt": "your-jwt-token",
  "object": "project",
  "data": {
    "id": "123",
    "name": "Updated Project"
  }
}

Remove

Remove an entity.

Request:

{
  "action": "remove",
  "jwt": "your-jwt-token",
  "object": "project",
  "data": {
    "id": "123"
  }
}

Read

Read a specific entity.

Request:

{
  "action": "read",
  "jwt": "your-jwt-token",
  "data": {
    "id": "123"
  }
}

List

List entities.

Request:

{
  "action": "list",
  "jwt": "your-jwt-token",
  "data": {
    "filter": {},
    "limit": 50,
    "offset": 0
  }
}

V3.0 Features - 100% JIRA Parity Achieved ✅

HelixTrack Core V3.0 provides complete JIRA feature parity with 282 API actions across all features (V1 + Phase 1 + Phase 2 + Phase 3). All planned features are now production-ready.

For complete API documentation with all 282 API actions, see API_REFERENCE_COMPLETE.md or JIRA_FEATURE_GAP_ANALYSIS.md for detailed feature comparison.

Feature Summary (All Phases Complete ✅)

Public & Authentication (4 actions):

Generic CRUD (5 actions):

V1 Core Features (144 actions):

Phase 1 - JIRA Parity ✅ COMPLETE (45 actions):

Phase 2 - Agile Enhancements ✅ COMPLETE (62 actions):

Phase 3 - Collaboration ✅ COMPLETE (31 actions):

Total API Actions: 282 (144 V1 + 45 Phase 1 + 62 Phase 2 + 31 Phase 3)

Quick Reference

Action Pattern Description Example
{feature}Create Create new entity priorityCreate, boardCreate
{feature}Read Read entity by ID versionRead, cycleRead
{feature}List List all entities resolutionList, teamList
{feature}Modify Update entity customFieldModify, labelModify
{feature}Remove Soft-delete entity workflowRemove, assetRemove

Example: Working with Priorities

# Create a priority
curl -X POST http://localhost:8080/do \
  -H "Content-Type: application/json" \
  -d '{
    "action": "priorityCreate",
    "jwt": "your-jwt-token",
    "data": {
      "title": "Critical",
      "level": 5,
      "color": "#FF0000"
    }
  }'

# List all priorities
curl -X POST http://localhost:8080/do \
  -H "Content-Type: application/json" \
  -d '{
    "action": "priorityList",
    "jwt": "your-jwt-token",
    "data": {}
  }'

Example: Working with Boards

# Create a board
curl -X POST http://localhost:8080/do \
  -H "Content-Type: application/json" \
  -d '{
    "action": "boardCreate",
    "jwt": "your-jwt-token",
    "data": {
      "title": "Sprint Board",
      "description": "Main development board"
    }
  }'

# Add ticket to board
curl -X POST http://localhost:8080/do \
  -H "Content-Type: application/json" \
  -d '{
    "action": "boardAddTicket",
    "jwt": "your-jwt-token",
    "data": {
      "boardId": "board-id",
      "ticketId": "PROJ-123"
    }
  }'

Testing Resources

Error Codes

Code Range Description
-1 - Success (no error)
1000-1009 Request Request-related errors
2000-2006 System System-related errors
3000-3005 Entity Entity-related errors

Request Errors (100X):

System Errors (200X):

Entity Errors (300X):

Testing

Running Tests

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html

API Testing

Using curl

# Test version endpoint
curl -X POST http://localhost:8080/do \
  -H "Content-Type: application/json" \
  -d '{"action": "version"}'

# Run all tests
cd test-scripts
./test-all.sh

Using Postman

  1. Import the Postman collection: test-scripts/HelixTrack-Core-API.postman_collection.json
  2. Set the base_url variable to your server address
  3. For authenticated requests, set the jwt_token variable
  4. Run the collection

Troubleshooting

Common Issues

Application won't start

Problem: Configuration file not found

Solution:

# Ensure configuration file exists
ls -l Configurations/default.json

# Or specify custom path
./htCore -config=/path/to/config.json

Database connection errors

Problem: SQLite database file not found

Solution:

# Create database directory
mkdir -p Database

# Ensure database file exists or application has write permissions
chmod 755 Database

Problem: PostgreSQL connection refused

Solution:

Permission denied errors

Problem: Cannot write to log directory

Solution:

# Create log directory with correct permissions
sudo mkdir -p /tmp/htCoreLogs
sudo chown $USER:$USER /tmp/htCoreLogs

Logging

Logs are written to both console and file. Check logs for detailed error information:

# View recent logs
tail -f /tmp/htCoreLogs/htCore.log

# Search for errors
grep ERROR /tmp/htCoreLogs/htCore.log

Architecture

Project Structure

Application/
├── main.go                      # Application entry point
├── go.mod                       # Go module definition
├── Configurations/              # Configuration files
│   └── default.json
├── internal/                    # Internal packages
│   ├── config/                  # Configuration management
│   ├── models/                  # Data models
│   ├── database/                # Database abstraction
│   ├── logger/                  # Logging system
│   ├── middleware/              # HTTP middleware
│   ├── services/                # External service clients
│   ├── handlers/                # HTTP handlers
│   └── server/                  # HTTP server
├── test-scripts/                # API test scripts
└── docs/                        # Documentation

Service Architecture

HelixTrack Core is designed as a modular microservice system:

┌─────────────────┐
│   Client Apps   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  HelixTrack     │
│     Core        │◄────► Authentication Service (optional)
│   (This API)    │
└────────┬────────┘◄────► Permissions Service (optional)
         │
         ├────────────► Extension: Chats (optional)
         ├────────────► Extension: Documents (optional)
         └────────────► Extension: Times (optional)

Component Decoupling

All components are fully decoupled and communicate via HTTP:

Each service can run on:

Database Layer

The database layer is abstracted to support multiple database backends:

Switch between databases by changing configuration - no code changes required.

Version: 3.0.0 (Full JIRA Parity Edition)

Last Updated: 2025-10-12

Status: ✅ PRODUCTION READY - ALL FEATURES COMPLETE

JIRA Parity: ✅ 100% ACHIEVED

API Actions: 282 (144 V1 + 45 Phase 1 + 62 Phase 2 + 31 Phase 3)

Database: V3 Schema with 89 tables

Test Coverage: 1,375 tests (98.8% pass rate, 71.9% average coverage)

License: See LICENSE file

Complete References: