APMT AI Operations Assistant

AI-powered terminal intelligence platform for APM Terminals. Ask questions about vessel operations, yard inventory, gate activity, and equipment performance using natural language. Powered by Claude (Anthropic).

Features

AI Chat

• Natural language queries against live terminal database

• 31 specialized database tools (vessels, yard, gate, equipment, delays)

• Smart follow-up suggestions after each response

• Natural language date handling ("last week", "this month", "Q1")

• Multi-step analysis for root cause questions

• Conversation history (SQLite)

Visualization

• Interactive charts (ApexCharts) — bar, line, pie, doughnut

• Paginated tables and charts (10 items per page)

• Terminal Overview — full dashboard in one query

• Weekly comparison mode (moves, productivity, delays)

Reports

• Expand to fullscreen modal

• Export to PDF with charts (html2canvas + jsPDF)

• Email report delivery (SMTP)

• Response feedback (thumbs up/down)

Executive Queries (HQ)

• CMPH vs target benchmarking

• Best/worst vessel ranking

• Delay root cause analysis

• Delay breakdown by category

• Gate throughput patterns

• Berth utilization trends

• Dwell time analysis

UX

• KPI summary cards (auto-refresh)

• Voice input with terminal vocabulary correction

• Onboarding tour (driver.js)

• Keyboard shortcuts (Ctrl+K, Ctrl+E, Ctrl+N)

• Sound notification on response

• Two-layer caching (query + response)

• Admin health dashboard (/admin)

• Maersk Headline font

Quick Start

Prerequisites

• Node.js 20+

• MySQL 8.0

• Anthropic API key

Setup

# Install dependencies
npm install

# Copy and configure environment
cp .env.example .env
# Edit .env with your MySQL and Anthropic credentials

# Build
npm run build

# Start
npm start

The app will import the demo database on first run and start at http://localhost:3000.

Environment Variables

# MySQL
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=root
DB_NAME=compass_db

# AI
ANTHROPIC_API_KEY=sk-ant-...
# CLAUDE_MODEL=claude-sonnet-4-20250514

# Server
CHAT_SERVER_PORT=3000

# Cache TTLs (minutes)
CACHE_TTL_STATIC=60
CACHE_TTL_SLOW=60
CACHE_TTL_LIVE=60
CACHE_TTL_RESPONSE=60

# Email (optional)
# SMTP_HOST=smtp.gmail.com
# SMTP_PORT=587
# SMTP_USER=your-email@gmail.com
# SMTP_PASS=your-app-password

Docker

docker compose up -d

Or deploy to Coolify — the MYSQL_DATABASE env var creates the DB automatically.

Project Structure

src/
  chat-server.ts    # Express server, Claude API, all endpoints
  chat-history.ts   # SQLite conversation history (sql.js)
  database.ts       # MySQL connection pool
  init-database.ts  # Auto-import demo data on first run
  queries.ts        # All SQL queries (50+)
public/
  index.html        # UI (Tailwind CSS, Lucide icons)
  script.js         # Frontend logic (charts, pagination, voice, etc.)
  fonts/            # Maersk Headline webfont
demo_database.sql   # Slim demo dataset (1.8MB, ~30 vessel visits)

API Endpoints

Keyboard Shortcuts