# 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

Selected Systems