1. Introduction

Captain's Toolkit is a browser-based marine operations application built as an offline-first Progressive Web Application. It is designed to help users manage important vessel-related information without depending on a constant internet connection.

The application can run as a frontend-only tool using local browser storage, or it can be connected to the included optional PHP backend starter for cloud backups and restore functionality.

Main Use Cases

• Marine operations dashboard
• Vessel profile management
• Voyage records and notes
• Fuel and maintenance tracking
• Crew and emergency information
• Safety and operational checklists
• Offline-first marine data storage
• Optional cloud backup and restore

2. Features Overview

3. Folder Structure

The project is organized into frontend application files, reusable core modules, screen modules, assets, PWA files, and an optional backend starter.

captains-toolkit/
├── index.html
├── offline.html
├── app.webmanifest
├── sw.js
├── .htaccess
├── README.md
├── DOCUMENTATION.html
├── LICENSE.text
├── CHANGELOG.txt
├── VERSION.txt
│
├── assets/
│   ├── css/
│   ├── icons/
│   ├── js/
│   └── screenshots/
│
├── core/
│   ├── constants.js
│   ├── helpers.js
│   ├── router.js
│   ├── storage.js
│   ├── sync.js
│   └── ui.js
│
├── screens/
│   ├── dashboard.js
│   ├── vessel.js
│   ├── voyages.js
│   ├── fuel.js
│   ├── maintenance.js
│   ├── crew.js
│   ├── emergency.js
│   ├── checklists.js
│   ├── exports.js
│   ├── settings.js
│   └── onboarding.js
│
├── backend-starter/
│   ├── config.php
│   ├── install.php
│   ├── .htaccess
│   ├── core/
│   └── api/
│
├── components/
├── data/
├── docs/
├── install/
├── screenshots/
└── storage/

Main Folders

4. Installation

Captain's Toolkit can be installed in two different ways:

• Frontend-only installation: the app runs fully offline using browser local storage.
• Frontend + backend installation: the app runs offline locally and can optionally save cloud backups to a PHP/MySQL backend.

Recommended Installation

For a commercial deployment, HTTPS is strongly recommended because PWA installation, service workers, and some browser storage features work best under HTTPS.

5. Frontend Setup

Basic Frontend Setup

1. Upload the full captains-toolkit/ folder to your web server.
2. Open the application URL in a browser.
3. Complete the onboarding wizard.
4. Start using the application.

Example URLs

https://yourdomain.com/captains-toolkit/
https://yourdomain.com/demo/captains-toolkit/
https://app.yourdomain.com/

Important Frontend Files

Changing the Installation Path

Captain's Toolkit is designed to work both in the website root and inside a subfolder.

If the application is installed in the website root:

RewriteBase /

If the application is installed in a dedicated folder:

RewriteBase /captains-toolkit/

If the application is installed inside a demo folder:

RewriteBase /demo/captains-toolkit/

In most hosting environments the included .htaccess works without any changes. Update RewriteBase only if routing or page refreshes do not work correctly after installation.

6. Backend Setup

The backend is optional. The frontend application works without it. The backend starter adds account registration, login, authentication, cloud backup, backup history, and restore support.

Backend Requirements

• PHP 8.0 or newer
• MySQL 5.7+ or MariaDB
• PDO extension enabled
• HTTPS recommended
• Apache with mod_rewrite recommended

Backend Files

7. Backend Config

The file backend-starter/config.php contains example placeholder values. These placeholders are included intentionally so the package can be safely distributed as a reusable starter. Before using the backend, replace them with your real hosting and database values.

Required Values to Replace

Default Starter Example

Your file may look similar to this before configuration:

<?php

return [
    'db_host' => 'localhost',
    'db_name' => 'YOUR_DATABASE_NAME',
    'db_user' => 'YOUR_DATABASE_USER',
    'db_pass' => 'YOUR_DATABASE_PASSWORD',

    'jwt_secret' => 'REPLACE_WITH_YOUR_OWN_LONG_RANDOM_SECRET_KEY',

    'cors_origin' => '*'
];

Configured Example

Example after replacing placeholders:

<?php

return [
    'db_host' => 'localhost',
    'db_name' => 'captains_toolkit',
    'db_user' => 'hosting_user',
    'db_pass' => 'StrongDatabasePassword123',

    'jwt_secret' => 'use-a-long-random-secret-key-generated-for-this-installation',

    'cors_origin' => 'https://yourdomain.com'
];

CORS Origin

During testing, cors_origin may be set to *. For production, it is better to limit it to the domain where the frontend app is installed.

'cors_origin' => 'https://yourdomain.com'

If your frontend is installed in a subfolder, the origin is still only the domain part:

'cors_origin' => 'https://yourdomain.com'

8. Database Installation

Step 1: Create Database

Create a new MySQL or MariaDB database from your hosting control panel.

Step 2: Create Database User

Create a database user and assign it permissions to the new database.

Step 3: Configure Backend

Add your database credentials and JWT secret to:

backend-starter/config.php

Make sure these placeholder values are no longer present:

• YOUR_DATABASE_NAME
• YOUR_DATABASE_USER
• YOUR_DATABASE_PASSWORD
• REPLACE_WITH_YOUR_OWN_LONG_RANDOM_SECRET_KEY

Step 4: Run Installer

Open the installer in your browser:

https://yourdomain.com/captains-toolkit/backend-starter/install.php

If successful, the installer should create the required backend tables.

Step 5: Remove or Protect install.php

After successful installation, delete or block:

backend-starter/install.php

9. Cloud Sync Configuration

Cloud Sync is optional. If Cloud Sync is disabled, the app continues to work locally using browser storage.

How to Enable Cloud Sync

1. Install the backend starter.
2. Open Captain's Toolkit.
3. Go to Settings.
4. Enable Cloud Sync.
5. Enter your Backend API URL.
6. Create an account or log in.
7. Use Exports to save or restore cloud backups.

Backend API URL Example

https://yourdomain.com/captains-toolkit/backend-starter

Do not include a trailing slash unless your server setup requires it.

Health Check

The app can check backend availability using:

https://yourdomain.com/captains-toolkit/backend-starter/api/health.php

When Cloud Sync Is Not Configured

If Cloud Sync is not enabled or no Backend API URL is provided, the app should display a clear notice that cloud sync is not configured. This is normal behavior.

10. Backup System

Captain's Toolkit supports local exports and optional cloud backups.

Local Backup

Local backups export application data as a JSON file. This is useful for manual backups, migration, or restoring data later.

Cloud Backup

Cloud backup requires the optional backend starter. When enabled, the app can save a backup to the backend database under the logged-in user account.

Backup History

Backup history allows users to view previously saved cloud backups and restore a selected version.

Recommended Backup Workflow

1. Use the app normally offline or online.
2. Export a local JSON backup regularly.
3. If backend is enabled, save cloud backups after important changes.
4. Use restore only when you are sure you want to replace local data.

11. Multi-Device Usage

Captain's Toolkit includes a multi-device ready architecture through account-based cloud backups and device information.

How Multi-Device Usage Works

1. User enables Cloud Sync on the first device.
2. User saves a cloud backup.
3. User opens the app on another device.
4. User logs in with the same account.
5. User restores the latest backup.

Important Clarification

The included backend starter is designed for backup and restore workflows. It provides the foundation for multi-device usage, but it is not the same as real-time collaborative synchronization.

12. PWA Installation

Captain's Toolkit is a Progressive Web Application. It can be installed on supported devices and used like a native-style app.

Supported Platforms

• Windows
• macOS
• Linux
• Android
• iPhone and iPad

Important PWA Files

Install App Button

The application includes install detection logic. Depending on the browser and device, users may see an Install App button or use the browser menu to install the app.

Service Worker Cache

After updating files, update the cache version in sw.js to make browsers load the new version.

const CACHE_VERSION = 'v1.0.9';

13. Settings

The Settings screen allows users to configure application preferences and cloud sync options.

Common Settings

• Theme settings
• Unit preferences
• Cloud Sync status
• Backend API URL
• Account information
• Device information
• Last backup information
• Last restore information
• Onboarding reset

Cloud Sync Settings

Cloud Sync settings are only useful when the backend starter has been installed and configured.

Resetting Onboarding

Users can run onboarding again from Settings if they want to reconfigure the initial setup.

14. Data Storage

Captain's Toolkit uses browser local storage for offline-first operation.

Local Storage

The main application data is stored locally in the user's browser. This allows the app to work without a server and without internet access.

Cloud Storage

When the backend starter is enabled, backups can be stored in the backend database.

Data Safety Notes

• Clearing browser data may remove locally stored app data.
• Using another browser will not automatically show the same local data.
• Local JSON export is recommended before clearing browser data.
• Cloud backup is recommended for users who move between devices.

15. Customization

Captain's Toolkit is designed to be customized and rebranded.

Common Customizations

• Change product name
• Change logo and icons
• Change colors
• Modify dashboard cards
• Add or remove screens
• Adjust fields in existing screens
• Connect to a different backend

CSS Files

Adding a New Screen

1. Create a new file in screens/.
2. Register the screen in the router if needed.
3. Add navigation link in the application layout.
4. Add styles to the appropriate CSS file.
5. Test desktop, tablet, and mobile layouts.

16. Branding

Branding can be changed in the application files and PWA manifest.

Main Branding File

Edit:

assets/js/branding.js

Typical values include app name, short name, version, company name, and website.

PWA Branding

Edit:

app.webmanifest

Update the following values:

• name
• short_name
• description
• theme_color
• background_color
• icons
• shortcuts

Icons

Replace icons in:

assets/icons/

Recommended minimum icon sizes:

• 192x192
• 512x512
• Maskable 512x512

17. Production Checklist

Before using Captain's Toolkit in a real production environment, review this checklist.

18. Updating the Application

When updating Captain's Toolkit, make sure users receive the latest files and the browser does not continue using an old service worker cache.

Recommended Update Steps

1. Backup your current project files.
2. Backup local or cloud data.
3. Replace updated frontend files.
4. Replace updated backend files if applicable.
5. Update version values where needed.
6. Update the cache version in sw.js.
7. Test the application in a private browser window.
8. Test installation and offline behavior.

Files Where Version May Appear

• VERSION.txt
• CHANGELOG.txt
• assets/js/branding.js
• core/constants.js
• sw.js

19. Troubleshooting

Cloud Sync is not configured

This message appears when Cloud Sync is disabled or the Backend API URL is missing.

To fix it:

1. Install the backend starter.
2. Go to Settings.
3. Enable Cloud Sync.
4. Add the correct Backend API URL.
5. Register or log in.

Backend returns 500 Internal Server Error

Usually this means the database credentials are incorrect, the database user does not have permission, or the database tables were not created.

Check:

• backend-starter/config.php
• Database name
• Database username
• Database password
• Database user permissions
• PHP error logs

Access denied for database user

This usually means db_user or db_pass is incorrect, or the database user has not been assigned to the database.

In cPanel-style hosting, make sure the database user is added to the database and has the required permissions.

Install App button does not appear

Browser install prompts depend on browser rules. Make sure:

• The site is served over HTTPS.
• app.webmanifest is valid.
• sw.js is registered.
• Required icons exist.
• The app has not already been installed.

Old version still appears after upload

The browser may still be using an old service worker cache.

Try:

• Update the cache version in sw.js.
• Hard refresh the browser.
• Clear site data in browser developer tools.
• Unregister the old service worker during testing.

Local data disappeared

Local data may disappear if browser data was cleared, another browser was used, or the app was opened under a different domain/path.

Restore data from:

• Local JSON backup
• Cloud backup, if enabled

Backend health check fails

Confirm that this URL opens correctly:

https://yourdomain.com/captains-toolkit/backend-starter/api/health.php

Also check server paths, PHP version, file permissions, config values, and CORS configuration.

20. FAQ

Does Captain's Toolkit work offline?

Yes. The frontend application is designed as an offline-first PWA and stores data locally in the browser.

Is the backend required?

No. The backend is optional. The app works locally without the backend.

What does the backend add?

The backend adds account registration, login, cloud backup, backup history, and restore support.

Can I rebrand the app?

Yes. Rebranding is allowed under both Standard and Extended licenses.

Can I use it for client projects?

With the Standard License, usage is limited to one project. With the Extended License, you may use it for unlimited client projects according to the license terms.

Can I resell the source code?

No. Reselling or redistributing the source code as a standalone product is not allowed.

Can I modify the backend?

Yes. The backend starter is included as source code and can be modified according to your project needs and license terms.

Can I turn this into a SaaS product?

You may build a commercial deployment or client solution based on the license you purchased. You may not resell the original source code package as a competing source-code product.

Does it include real-time sync?

The included backend starter supports backup and restore workflows. It is multi-device ready, but it is not a full real-time synchronization engine by default.

Where is the app data stored?

By default, app data is stored locally in the browser. If Cloud Sync is enabled, backups can also be stored in the backend database.

21. Licensing

Captain's Toolkit is distributed as a commercial source code package under two license options: Standard License and Extended License.

Standard License — $89

The Standard License is intended for one personal or commercial project. It allows you to modify, rebrand, and deploy the application for a single production use case.

• One production deployment
• One personal or commercial project
• Source code modification allowed
• Rebranding allowed
• Optional backend starter included

Extended License — $249

The Extended License is intended for agencies, freelancers, studios, consultants, and commercial teams working on multiple projects or client solutions.

• Unlimited client projects
• Unlimited internal commercial projects
• Multiple production deployments
• Source code modification allowed
• Rebranding allowed
• Optional backend starter included

Not Allowed Under Either License

• Reselling the original source code package as-is
• Redistributing the original source code package
• Publishing the source code publicly
• Uploading the source code to public repositories
• Claiming ownership of the original source code
• Selling Captain's Toolkit as a competing source-code product

For full license terms, please refer to LICENSE.text included in this package.

22. Support

Captain's Toolkit is provided as a commercial source code package. Documentation is included to help buyers install, customize, and deploy the application.

Before Requesting Support

• Read this documentation.
• Check README.md.
• Check CHANGELOG.txt.
• Check LICENSE.text.
• Check your browser console for JavaScript errors.
• Check your PHP error logs for backend issues.

Useful Information for Support

• Product version
• Browser and operating system
• Hosting provider
• PHP version, if using backend
• MySQL or MariaDB version, if using backend
• Exact error message
• Steps to reproduce the issue

Product Website

Website: https://www.cordinant.com