Altus 4 | API

AI-Enhanced MySQL Full-Text Search Engine

Altus 4 is an intelligent search-as-a-service platform that leverages MySQL's built-in full-text search capabilities while adding AI-powered optimizations and enhancements. Instead of requiring users to migrate to specialized search solutions like Elasticsearch or Solr, Altus 4 enhances MySQL's native FULLTEXT search with semantic understanding, query optimization, and comprehensive analytics.

Quick Start

Get Altus 4 running in 5 minutes:

# Clone and install
git clone https://github.com/altus4/api.git
cd core && npm ci

# Option 1: Full Docker Environment (Recommended)
npm run dev:start        # Starts MySQL + Redis + runs migrations
npm run dev              # Start the application
# Server starts at http://localhost:3000

# Option 2: Manual Setup
cp .env.example .env     # Setup environment
# Edit .env with your MySQL/Redis credentials
npm run migrate          # Run database migrations
npm run dev              # Start development server

# When done developing
npm run dev:stop         # Stop Docker services

Database Migrations

Altus 4 includes a Laravel-like migration CLI for managing MySQL schema changes.

SQL files live in migrations/
Each migration has a pair: XYZ_name.up.sql and XYZ_name.down.sql
The CLI loads .env automatically and records state in a migrations table

Common Commands (npm scripts)

# Run outstanding migrations
npm run migrate:run

# Install migrations table if missing
npm run migrate:install

# Show status (applied/pending + batch)
npm run migrate:status

# Rollback last batch
npm run migrate:rollback

# Rollback everything
npm run migrate:reset

# Reset and re-run all
npm run migrate:refresh

# Drop all tables and re-run
npm run migrate:fresh

# Run or rollback a specific file
./bin/altus migrate:up --file 001_create_users_table
./bin/altus migrate:down --file 001_create_users_table

# Convenience alias retained for compatibility
npm run migrate          # equivalent to "up" (legacy alias)

Node-based CLI (no mysql client required)

If your server doesn't have the mysql CLI installed, use the Node-based CLI which connects using mysql2:

# Build once (during deploy/build step)
npm run build

# Run commands via the Node CLI
./bin/altus migrate
./bin/altus migrate:status
./bin/altus migrate:rollback --step 2
./bin/altus migrate:fresh --force

See docs/cli.md for the full reference.

CLI Options

./bin/altus <command> [options]

--path <dir>       Directory of migrations (default: migrations)
--database <name>  Override DB name (uses DB_DATABASE by default)
--step             For migrate: put each file in its own batch
--pretend          Print SQL without executing
--seed             Run SQL seeds from <path>/seeds after migrate/refresh/fresh
--force            Allow in production (APP_ENV=production)
--file <name>      For up/down: base name (e.g. 001_create_users_table)
--batch <n>        For rollback: only the given batch
--step <n>         For rollback: number of files to rollback
--drop-views       For fresh: also drop database views

Behavior notes:

migrate:down without --file rolls back a single file (the most recent). Use migrate:rollback to revert the last batch, migrate:reset for everything, or migrate:fresh to drop all tables and re-run.
In production (APP_ENV=production), destructive commands require --force.
If DB_HOST=localhost, the CLI forces TCP via 127.0.0.1. To use a socket, set DB_SOCKET in .env.
You can override the migrations table name via MIGRATIONS_TABLE env (default migrations).
Seeds: place .sql files under migrations/seeds/ to run them in filename order with --seed.

Developer & testing notes

The Node CLI (src/cli/index.ts) exports command helpers and is test-friendly: core functions are exported so tests can call commands like cmdUpOne and cmdDownOneOrRollback programmatically. To avoid starting the CLI during import, the CLI only executes main() when run directly (i.e. node dist/src/cli/index.js or via ./bin/altus).
For integration tests the repository includes a mocked MySQL setup. Run the integration test suite which contains CLI tests with:

npm run test:integration

If you want to test the CLI against a real MySQL instance, build the project and run the compiled CLI against your database:

npm run build
./bin/altus migrate --path migrations

Destructive operations (reset/fresh) are guarded in production; use --force together with APP_ENV=production only when you are certain.

Environment Variables

The migration CLI uses the same .env as the app:

DB_HOST=127.0.0.1       # or set DB_SOCKET for socket connections
DB_PORT=3306
DB_USERNAME=altus4_user
DB_PASSWORD=your_password
DB_DATABASE=altus4
APP_ENV=development     # production requires --force for destructive ops
# Optional: override migrations table
MIGRATIONS_TABLE=migrations

Ensure the database exists before running migrations; the CLI won’t create the database itself.

For comprehensive documentation, see the /docs directory.

Overview

The Problem

Many applications using MySQL struggle with search functionality, often requiring complex migrations to specialized search engines like Elasticsearch. This creates additional infrastructure complexity, data synchronization challenges, and operational overhead.

The Solution

Altus 4 bridges this gap by enhancing MySQL's existing full-text search capabilities with:

AI-powered semantic search for better result relevance
Natural language query processing for user-friendly search interfaces
Intelligent query optimization and performance suggestions
Multi-database federation for searching across multiple data sources
Real-time analytics and search trend insights
Zero-migration setup that works with existing MySQL databases

Features

Core Search Capabilities

Full-Text Search Enhancement: Leverages MySQL's FULLTEXT indexes with intelligent query optimization
Multi-Search Modes: Natural language, boolean, and semantic search options
Cross-Database Search: Federate searches across multiple connected MySQL databases
Intelligent Ranking: Advanced relevance scoring and result ranking algorithms
Auto-Suggestions: Real-time query suggestions and auto-completion

AI-Powered Enhancements

Semantic Search: Uses OpenAI embeddings for concept-based matching beyond keyword search
Query Optimization: AI-powered analysis of search patterns with performance recommendations
Result Categorization: Automatic classification and tagging of search results
Natural Language Processing: Convert plain English queries to optimized SQL
Trend Analysis: Identify search patterns and popular queries over time

Enterprise Features

Multi-Tenant Architecture: Secure isolation between different user accounts and databases
Role-Based Access Control: Fine-grained permissions and user management
Rate Limiting: Configurable API throttling and abuse prevention
Comprehensive Logging: Structured logging with request tracing and analytics
Health Monitoring: Built-in health checks and performance metrics

Security & Performance

Encrypted Credentials: Database connection credentials are encrypted at rest
API Key Authentication: B2B-friendly API key authentication with tiered rate limiting
SQL Injection Prevention: Parameterized queries and input sanitization
Connection Pooling: Optimized database connection management
Redis Caching: Intelligent caching for improved response times
Input Validation: Comprehensive request validation using Zod schemas

Architecture

System Architecture

Altus 4 follows a layered architecture pattern with four primary components:

API Layer: RESTful endpoints with authentication, validation, and rate limiting
Service Layer: Business logic orchestration and data processing
Data Layer: MySQL connection management and Redis caching
Integration Layer: External AI services and third-party integrations

Core Services

DatabaseService: Manages MySQL connections, schema discovery, and query execution
SearchService: Orchestrates search operations and result processing
AIService: Handles OpenAI integration for semantic enhancements
CacheService: Redis-based caching and analytics storage
AuthService: User authentication and authorization management

Technology Stack

Runtime: Node.js 20+
Language: TypeScript with strict type checking
Framework: Express.js with comprehensive middleware
Database: MySQL 8.0+ for both client data and metadata storage
Cache: Redis 6.0+ for performance optimization
AI Integration: OpenAI API (GPT-3.5/GPT-4) for semantic capabilities
Validation: Zod for runtime type checking and validation
Authentication: API keys with bcrypt for password hashing
Logging: Winston with structured logging
Testing: Jest with comprehensive test coverage

Prerequisites

Before installing Altus 4, ensure you have the following dependencies:

Required Software

Node.js: Version 20.0 or higher
npm: Version 10.0 or higher (or yarn/pnpm equivalent)
MySQL: Version 8.0 or higher
Redis: Version 6.0 or higher

Optional Dependencies

OpenAI API Access: Required for AI-enhanced features
Docker: For containerized deployment (recommended for production)

System Requirements

Memory: Minimum 2GB RAM (4GB recommended)
Storage: At least 1GB free disk space
Network: Internet connectivity for AI services and package downloads

Installation

Quick Start

# Clone the repository
git clone https://github.com/altus4/api.git
cd core

# Install dependencies
npm ci

# Copy environment configuration
cp .env.example .env

# Configure your environment variables (see Configuration section)
nano .env

# Run database migrations
npm run migrate

# Build the project
npm run build

# Start development server
npm run dev

Database Setup

Create the required MySQL database and user:

-- Connect to MySQL as root
mysql -u root -p

-- Create database
CREATE DATABASE altus4_metadata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- Create user
CREATE USER 'altus4_user'@'localhost' IDENTIFIED BY 'your_secure_password';

-- Grant permissions
GRANT ALL PRIVILEGES ON altus4_metadata.* TO 'altus4_user'@'localhost';
FLUSH PRIVILEGES;

Redis Setup

Ensure Redis is running and accessible:

# Start Redis (varies by system)
redis-server

# Test connection
redis-cli ping
# Should return: PONG

Environment Configuration

Generate secure secrets for your environment:

# Generate JWT secret
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Generate encryption key
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Configuration

Environment Variables

Altus 4 uses environment variables for configuration. Copy .env.example to .env and configure:

Server Configuration

NODE_ENV=development          # Environment: development, production, test
PORT=3000                    # Server port

Database Configuration

DB_HOST=localhost            # MySQL host
DB_PORT=3306                # MySQL port
DB_USERNAME=altus4_user     # MySQL username
DB_PASSWORD=secure_password  # MySQL password
DB_DATABASE=altus4_metadata # MySQL database name

Security Configuration

JWT_SECRET=your_32_char_secret    # JWT signing secret (for initial setup only)
ENCRYPTION_KEY=your_32_char_key   # Encryption key for credentials
JWT_EXPIRES_IN=7d                 # JWT token expiration (for bootstrapping)

Redis Configuration

REDIS_HOST=localhost         # Redis host
REDIS_PORT=6379             # Redis port
REDIS_PASSWORD=             # Redis password (if required)

AI Integration Configuration

OPENAI_API_KEY=sk-your_key  # OpenAI API key
OPENAI_MODEL=gpt-3.5-turbo  # OpenAI model to use
OPENAI_MAX_TOKENS=1000      # Maximum tokens per request

Rate Limiting Configuration

RATE_LIMIT_WINDOW_MS=900000      # Rate limit window (15 minutes)
RATE_LIMIT_MAX_REQUESTS=100      # Maximum requests per window

Configuration Validation

Altus 4 validates all configuration on startup and will fail fast if required variables are missing or invalid.

Usage

Starting the Server

# Development mode with hot reload
npm run dev

# Production mode
npm run start

# Build for production
npm run build

Health Check

Verify the server is running:

curl http://localhost:3000/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "version": "0.4.0",
  "uptime": 1234.567
}

Basic API Usage

Authentication

Register a new user and get your first API key:

# 1. Register a new user
curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure_password",
    "name": "Test User"
  }'

# 2. Login to get JWT token (for initial setup only)
curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure_password"
  }'

# 3. Create your first API key (using JWT token from login)
curl -X POST http://localhost:3000/api/v1/management/setup \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Note: After getting your API key, use it for all subsequent requests instead of JWT tokens.

Database Management

Add a database connection:

curl -X POST http://localhost:3000/api/v1/databases \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Database",
    "host": "localhost",
    "port": 3306,
    "database": "my_app_db",
    "username": "db_user",
    "password": "db_password"
  }'

Search Operations

Execute a search:

curl -X POST http://localhost:3000/api/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "search terms",
    "databases": ["database_id"],
    "searchMode": "natural",
    "limit": 20,
    "includeAnalytics": false
  }'

API Reference

Authentication Endpoints

Method	Endpoint	Description	Authentication
POST	`/api/v1/auth/register`	Register new user	None
POST	`/api/v1/auth/login`	User login	None
POST	`/api/v1/management/setup`	Create first API key	JWT Token
POST	`/api/v1/keys`	Create new API key	JWT Token
GET	`/api/v1/keys`	List API keys	JWT Token
DELETE	`/api/v1/keys/:id`	Revoke API key	JWT Token

Database Management Endpoints

Method	Endpoint	Description	Authentication
GET	`/api/v1/databases`	List user databases	JWT Token
POST	`/api/v1/databases`	Add database connection	JWT Token
GET	`/api/v1/databases/:id`	Get database details	JWT Token
PUT	`/api/v1/databases/:id`	Update database connection	JWT Token
DELETE	`/api/v1/databases/:id`	Remove database connection	JWT Token
GET	`/api/v1/databases/:id/schema`	Get database schema	JWT Token

Search Endpoints

Method	Endpoint	Description	Authentication
POST	`/api/v1/search`	Execute search	API Key
GET	`/api/v1/search/suggestions`	Get search suggestions	API Key
POST	`/api/v1/search/analyze`	Analyze query performance	API Key
GET	`/api/v1/search/trends`	Get search trends	API Key
GET	`/api/v1/search/history`	Get search history	API Key

Request/Response Formats

All API responses follow a consistent format:

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: any;
  };
  meta?: {
    timestamp: Date;
    requestId: string;
    version: string;
  };
}

Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	Missing or invalid API key
`INSUFFICIENT_PERMISSIONS`	403	API key lacks required permissions
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request data
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Documentation

This README provides a quick overview. For comprehensive documentation:

Complete Documentation

Full Documentation - Complete documentation index
API Key Authentication - API key setup and usage guide
API Reference - Detailed API endpoints and schemas
Architecture - System design and patterns
Services - Service classes with code explanations
Setup & Deployment - Installation and deployment guides
Testing - Testing strategies and examples
Development - Developer guides and best practices
Examples - Code examples and tutorials

Quick Links

Service Documentation - Understand each service class
API Schemas - Request/response formats
Code Examples - Working code samples
Testing Guide - How to write and run tests

Development

Project Structure

src/
├── config/          # Configuration management
├── controllers/     # Route controllers
├── middleware/      # Express middleware
├── routes/         # API route definitions
├── services/       # Business logic services
├── types/          # TypeScript type definitions
├── utils/          # Utility functions
└── index.ts        # Application entry point

Development Workflow

Setup development environment:
```
npm run dev
```
Make changes to source code
Run tests:
```
npm run test
npm run test:watch
```
Check code quality:
```
npm run lint
npm run lint:fix
```
Build project:
```
npm run build
```

Code Style Guidelines

TypeScript: Strict mode enabled with comprehensive type definitions
Naming Conventions:
- Variables and functions: camelCase
- Classes and interfaces: PascalCase
- Constants: UPPER_SNAKE_CASE
File Organization: Co-locate related files and group by feature
Error Handling: Use custom AppError class with proper error codes
Async Patterns: Prefer async/await over Promise chains
Logging: Use structured logging with appropriate levels

Adding New Features

When adding new functionality:

Update TypeScript types in src/types/index.ts
Create service classes with dependency injection
Add route handlers with proper validation
Include comprehensive tests
Update API documentation
Add configuration options if needed

Testing

Running Tests

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm run test -- --testPathPattern=SearchService

Test Structure

Unit Tests: Test individual functions and classes
Integration Tests: Test API endpoints and service interactions
Database Tests: Test database operations with test database
Mock Tests: Mock external dependencies (OpenAI, Redis)

Writing Tests

Tests should follow this structure:

describe('ServiceName', () => {
  beforeEach(() => {
    // Setup test environment
  });

  afterEach(() => {
    // Cleanup after each test
  });

  describe('methodName', () => {
    it('should handle success case', async () => {
      // Test implementation
    });

    it('should handle error case', async () => {
      // Test error scenarios
    });
  });
});

Test Coverage

Maintain minimum 80% test coverage across:

Statement coverage
Branch coverage
Function coverage
Line coverage

Deployment

Production Environment

Environment Variables

Set these environment variables for production:

NODE_ENV=production
PORT=3000
LOG_LEVEL=warn
JWT_EXPIRES_IN=24h
ENABLE_QUERY_LOGGING=false

Database Optimization

For production MySQL databases:

-- Optimize for full-text search
SET GLOBAL ft_min_word_len = 2;
SET GLOBAL innodb_ft_min_token_size = 2;

-- Restart MySQL to apply changes

Redis Configuration

Configure Redis for production:

# Enable persistence
appendonly yes
appendfsync everysec

# Set memory policies
maxmemory-policy allkeys-lru

Docker Deployment

Note: An app Dockerfile is not included in this repository. The compose example below assumes you provide one. For local services (MySQL + Redis), prefer the built-in scripts: npm run dev:start / npm run dev:stop / npm run dev:reset.

Docker Compose

version: '3.8'

services:
  altus4:
    build: .
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
    depends_on:
      - mysql
      - redis

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: altus4_metadata
    volumes:
      - mysql_data:/var/lib/mysql

  redis:
    image: redis:6-alpine
    volumes:
      - redis_data:/data

volumes:
  mysql_data:
  redis_data:

Building Docker Image

# Build image
docker build -t altus4:latest .

# Run container
docker run -d -p 3000:3000 altus4:latest

Health Checks

Configure health checks for production monitoring:

# HTTP health check endpoint
curl http://localhost:3000/health

Note: Dedicated DB/Redis HTTP health endpoints are not exposed by the app. Use service/container healthchecks and application logs/metrics.

Monitoring

Monitor these key metrics in production:

Response times: API endpoint performance
Error rates: Application and system errors
Resource usage: CPU, memory, disk utilization
Database performance: Query execution times, connection pool usage
Cache performance: Redis hit/miss ratios
Search analytics: Query volumes, popular searches

Contributing

We welcome contributions to Altus 4! Please follow these guidelines:

Development Setup

Fork the repository on GitHub
Clone your fork locally
Create a feature branch from main
Install dependencies: npm ci
Set up development environment following the Installation guide

Local Development with Docker

For easy local development, use the provided Docker-based scripts to start MySQL and Redis services:

Quick Start (Recommended)

# Start services (MySQL + Redis) and run migrations
npm run dev:start

# Start the Node.js server
npm run dev

# Tail container logs
npm run dev:logs

# Stop services when done
npm run dev:stop

# Reset services and data (fresh start)
npm run dev:reset

Contribution Workflow

Create an issue describing the feature or bug
Create a feature branch: git checkout -b feature/your-feature-name
Make your changes following the code style guidelines
Add tests for new functionality
Run the test suite: npm run test
Run linting: npm run lint:fix
Commit your changes: git commit -m "Add feature: description"
Push to your fork: git push origin feature/your-feature-name
Create a Pull Request with a detailed description

Pull Request Guidelines

Title: Clear, descriptive title
Description: Detailed explanation of changes
Tests: Include tests for new functionality
Documentation: Update relevant documentation
Breaking Changes: Clearly note any breaking changes

Code Review Process

All contributions go through code review:

Automated checks: CI runs tests and linting
Manual review: Core team reviews code quality and design
Feedback: Address any review comments
Approval: Two approvals required for merge

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Apache-2.0 Summary (not legal advice)

Commercial use, modification, distribution, and private use are permitted.
You must include the LICENSE (and NOTICE, if provided) with any redistribution and state significant changes.
Includes a patent license from contributors; it terminates if you initiate patent litigation.
No trademark rights are granted.
Provided “AS IS” without warranties or conditions; liability is limited.

Support

Getting Help

Documentation: Check this README and inline code documentation
Issues: Report bugs and request features on GitHub Issues
Discussions: Ask questions on GitHub Discussions

Commercial Support

For enterprise support, custom development, or consulting services, please contact:

Email: altus4@thavarshan.com
Website: https://altus4.thavarshan.com

Community

GitHub: https://github.com/altus4/api
Documentation: https://altus4.thavarshan.com/docs
Changelog: https://github.com/altus4/api/releases

Altus 4 - Making MySQL search intelligent, one query at a time.

Name		Name	Last commit message	Last commit date
Latest commit History 80 Commits
.claude		.claude
.github		.github
.husky		.husky
bin		bin
migrations		migrations
openapi		openapi
src		src
tests		tests
.auditci.json		.auditci.json
.editorconfig		.editorconfig
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.slugignore		.slugignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Procfile		Procfile
README.md		README.md
app.json		app.json
copilot-instructions.md		copilot-instructions.md
jest.config.js		jest.config.js
jest.integration.config.js		jest.integration.config.js
lint-staged.config.js		lint-staged.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

altus4/api

Folders and files

Latest commit

History

Repository files navigation

Altus 4 | API

Table of Contents

Quick Start

Database Migrations

Common Commands (npm scripts)

Node-based CLI (no mysql client required)

CLI Options

Developer & testing notes

Environment Variables

Overview

The Problem

The Solution

Features

Core Search Capabilities

AI-Powered Enhancements

Enterprise Features

Security & Performance

Architecture

System Architecture

Core Services

Technology Stack

Prerequisites

Required Software

Optional Dependencies

System Requirements

Installation

Quick Start

Database Setup

Redis Setup

Environment Configuration

Configuration

Environment Variables

Server Configuration

Database Configuration

Security Configuration

Redis Configuration

AI Integration Configuration

Rate Limiting Configuration

Configuration Validation

Usage

Starting the Server

Health Check

Basic API Usage

Authentication

Database Management

Search Operations

API Reference

Authentication Endpoints

Database Management Endpoints

Search Endpoints

Request/Response Formats

Error Codes

Documentation

Complete Documentation

Quick Links

Development

Project Structure

Development Workflow

Code Style Guidelines

Adding New Features

Testing

Running Tests

Test Structure

Writing Tests

Test Coverage

Deployment

Production Environment

Environment Variables

Database Optimization

Redis Configuration

Docker Deployment

Docker Compose

Building Docker Image

Health Checks