Leviathan

Leviathan is a Phoenix LiveView application for global ship tracking intelligence. It combines an interactive Leaflet world map, vessel and port management, simulated AIS-style vessel movement, user authentication, role-aware administration, a maritime photo gallery, and a lightweight maritime news feed into one cohesive operations dashboard.

The project is built as a real-time Elixir/Phoenix system: LiveViews render the operational UI, PubSub broadcasts vessel and port updates, and the tracking simulator keeps map state moving without requiring an external AIS provider during development.

Features

• Interactive world map with vessel and port overlays
• Real-time vessel updates through Phoenix PubSub and LiveView pushed events
• Built-in vessel tracking simulator with pause/resume controls
• Vessel directory with searchable listings, detail views, create/edit/delete flows, and position metadata
• Port directory with searchable listings, geofenced radius data, LOCODE support, and detail views
• User authentication with magic-link login, password login, session management, and profile settings
• Role-aware UI controls for administrative actions
• Maritime photo gallery with upload support and user-owned images
• Maritime news fetching and caching layer
• Responsive dashboard UI built with Tailwind CSS, daisyUI, Heroicons, and Leaflet marker clustering
• Focused test coverage for contexts, LiveViews, controllers, simulator behavior, and news/cache flows

Demo

Map Overview

App Overview

Ports Page

Vessels Page

News Page

Profile

Tech Stack

• Elixir and Phoenix 1.8
• Phoenix LiveView 1.1
• PostgreSQL with Ecto
• Bandit web server
• Tailwind CSS 4 and daisyUI
• Leaflet and leaflet.markercluster
• Swoosh for email delivery
• Req for HTTP fetching
• ExAws S3 support for production uploads

Getting Started

Prerequisites

Install:

• Elixir/Erlang compatible with mix.exs
• PostgreSQL
• Node.js/npm, used by frontend asset dependencies

Setup

From the project root:

mix setup

This installs Elixir dependencies, prepares the database, runs migrations, seeds sample data, and builds assets.

Start the Phoenix server:

mix phx.server

Or run it inside IEx:

iex -S mix phx.server

Open:

http://localhost:4000

Common Commands

mix setup          # Install deps, setup database, seed data, build assets
mix phx.server     # Start the development server
mix test           # Run the test suite
mix format         # Format Elixir code
mix precommit      # Compile, check unused deps, format, and test
mix ecto.reset     # Drop, recreate, migrate, and seed the database
mix assets.build   # Build development assets
mix assets.deploy  # Build minified production assets and digest them

Configuration

Development and test environments can load variables from .env through Dotenvy. Production is configured at runtime through environment variables.

Important production variables:

DATABASE_URL=ecto://USER:PASS@HOST/DATABASE
SECRET_KEY_BASE=...
PHX_HOST=example.com
PORT=4000
POOL_SIZE=10

Optional upload/S3 configuration:

UPLOAD_STORAGE=s3
AWS_BUCKET=...
AWS_REGION=...
AWS_S3_PUBLIC_URL=...
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

Generate a production secret with:

mix phx.gen.secret

Project Structure

lib/leviathan/                  Core contexts: accounts, tracking, geography, photos, news
lib/leviathan/tracking/         Vessel schemas, simulator, broadcaster, and movement engine
lib/leviathan_web/live/         LiveView screens for map, vessels, ports, photos, users, and news
lib/leviathan_web/components/   Shared UI components and domain-specific tables/cards
assets/js/hooks/map/            Leaflet map hook, layers, tiles, and satellite controls
priv/repo/migrations/           Database migrations
priv/repo/seeds.exs             Sample users, ports, vessels, and related demo data
test/                           Context, controller, LiveView, simulator, and support tests
doc/                            Generated project documentation

Data Model Overview

Leviathan centers on a few domain areas:

• Accounts: users, roles, magic-link/session tokens, profile data
• Tracking: vessels, positions, vessel-port visits, simulator events
• Geography: ports with coordinates, country codes, types, radius, LOCODE, timezone
• Photos: uploaded maritime images associated with users and domain entities
• News: external maritime news fetching and cache management

Testing

Run all tests:

mix test

Run a focused test file:

mix test test/leviathan_web/live/map_live_test.exs

The suite covers business contexts, validation rules, LiveView flows, authentication/session behavior, the tracking simulator, and map event integration.

Production Notes

For production releases, set PHX_SERVER=true when starting the release:

PHX_SERVER=true bin/leviathan start

Before deploying, ensure:

• DATABASE_URL and SECRET_KEY_BASE are set
• Upload storage is configured for the target environment
• Assets have been built with mix assets.deploy
• Database migrations have run

License

This project is licensed under the MIT License — a permissive open-source license that allows anyone to use, modify, distribute, and sublicense the software with minimal restrictions.

See the LICENSE file for full details.