Black Sea Oil Spill Monitoring System

An n8n-based monitoring platform for oil and fuel spill incidents in the Black Sea and Azov Sea region.

The repository contains exported n8n workflows, the PostgreSQL schema, and a local Docker setup that makes it easier to run the project as a portfolio-grade automation stack.

What This Project Does

• Searches for fresh news about real spill incidents in the Black Sea region.
• Stores and deduplicates events in PostgreSQL with vector search support.
• Resolves event coordinates and enriches incidents with satellite imagery.
• Fetches Sentinel-1 scenes through Sentinel Hub.
• Runs a vision-based spill detection step over the latest satellite image.
• Publishes and refreshes Telegram channel posts for each event.
• Exposes a RAG-style chat workflow over the stored incident database.

Main Workflows

• WF_NEWS_ON_DEMAND - searches the web, classifies fresh incidents, and inserts new events.
• AGENT_RAG_QUERY - performs semantic search over the event database.
• WF_EVENT_UPSERT_MANUAL - inserts or updates a hand-curated incident.
• WF_EVENT_COORDS_AGENT - infers coordinates for a specific event.
• WF_EVENT_S1_AGENT - requests a Sentinel-1 image for an event and stores the result.
• WF_EVENT_DET_AGENT - runs satellite-image spill detection.
• WF_EVENT_PUBLISH_AGENT - renders and synchronizes the Telegram channel post.
• AGENT_CHAT_BOT - orchestrates the user-facing Telegram assistant.

Repository Layout

• sql/bd.sql - PostgreSQL schema, vector extension, helper functions, and tables.
• workflows/ - exported n8n workflows ready to import.
• docker-compose.yml - local runtime for n8n plus PostgreSQL.
• .env.example - safe template for local secrets and runtime settings.
• .gitignore - keeps secrets and local data out of git.

Quick Start with Docker

1. Copy .env.example to .env.
2. Fill in the required values in .env.
3. Start the stack with docker compose up -d.
4. Open http://localhost:5678 and log in to n8n.
5. Wait for PostgreSQL to finish initializing. The schema in sql/bd.sql is applied automatically on the first database startup.

Required Local Configuration

The Docker stack uses two sets of configuration values:

• Docker and runtime variables from .env.
• n8n credentials configured inside the n8n UI.

Values Stored in .env

• POSTGRES_DB - database name for the project schema.
• POSTGRES_USER - database user for the project schema.
• POSTGRES_PASSWORD - database password.
• POSTGRES_PORT - host port for PostgreSQL.
• N8N_HOST - public host name used by n8n.
• N8N_HOST_PORT - host port mapped to the n8n container.
• N8N_ENCRYPTION_KEY - required n8n encryption key.
• N8N_EDITOR_BASE_URL - URL shown by the n8n editor.
• WEBHOOK_URL - public base URL for n8n webhooks.
• GENERIC_TIMEZONE and TIMEZONE - keep timestamps aligned.
• SENTINEL_HUB_CLIENT_ID and SENTINEL_HUB_CLIENT_SECRET - Sentinel Hub credentials used directly by the Sentinel-1 workflow.

n8n Credentials to Create

Create these credentials inside n8n after the container starts:

• OpenAi account - OpenAI API key for news search, embeddings, and vision steps.
• Postgres account - points to the project PostgreSQL container (postgres, port 5432, database oil_spills by default).
• Telegram account - bot token for Telegram posting and replies.

Import Order in n8n

Import the workflows in this order so that the tool workflows exist before the main chat bot is linked:

1. WF_NEWS_ON_DEMAND
2. AGENT_RAG_QUERY
3. WF_EVENT_UPSERT_MANUAL
4. WF_EVENT_COORDS_AGENT
5. WF_EVENT_S1_AGENT
6. WF_EVENT_DET_AGENT
7. WF_EVENT_PUBLISH_AGENT
8. AGENT_CHAT_BOT

After import, open AGENT_CHAT_BOT and verify the subworkflow nodes if n8n does not automatically reconnect them by name.

Security Notes

• No secrets are committed to the repository.
• Sensitive values live in .env or inside n8n credentials only.
• The Sentinel Hub client ID and secret are read from environment variables in WF_EVENT_S1_AGENT.
• Keep N8N_ENCRYPTION_KEY unique and private.
• Use a restricted Telegram bot and only the channel you actually intend to publish to.
• For production deployments, move n8n behind HTTPS and rotate tokens before sharing the project publicly.

Data Model

The PostgreSQL schema in sql/bd.sql defines:

• public.events - core incident records.
• public.users - Telegram user metadata for the chat bot.
• public.tg_posts - Telegram post references for published events.
• public.tg_media - stored media references for satellite imagery.
• public.evidence - supporting evidence captured by the workflows.
• public.agent_settings - runtime settings such as the target channel.

Author

Maksym Nahorskyi