Skip to content

External Integrations

Jump to bottom
overthelex edited this page May 17, 2026 · 3 revisions

External Integrations

SecondLayer integrates with multiple external services for AI processing, authentication, payments, legal data, and infrastructure. The platform uses an adapter-based architecture to abstract external API complexity.

AI Providers

AWS Bedrock (Primary)

Anthropic Claude models accessed via AWS Bedrock (@aws-sdk/client-bedrock-runtime):

  • Primary route for AI analysis and chat (when LLM_PROVIDER_STRATEGY=bedrock-first)
  • Region: eu-central-1
  • Chat models by budget tier:
Tier Default Model
Quick Claude Haiku 4.5
Standard Claude Sonnet 4.6
Deep Claude Opus 4.6
  • Fallback models configured separately (BEDROCK_FALLBACK_MODEL_*)
  • Embeddings: Amazon Titan Embed Text v2 (amazon.titan-embed-text-v2:0, 1024 dimensions)
  • Used for: document analysis, legal reasoning, chat responses, news article analysis

OpenAI

  • Chat models (when strategy is openai-first or as fallback):
Tier Default Model
Quick GPT-5 Nano
Standard GPT-5 Mini
Deep GPT-5.1
  • Configurable via OPENAI_MODEL_QUICK, OPENAI_MODEL_STANDARD, OPENAI_MODEL_DEEP
  • Single-model override available via OPENAI_MODEL env var

Anthropic (Direct API)

  • Available as a direct provider (when ANTHROPIC_API_KEY is set)
  • Models: Claude Haiku 4.5, Claude Sonnet 4.6, Claude Opus 4.6
  • Used as alternative to Bedrock for the same Claude models

VoyageAI (Embeddings)

  • Primary embedding provider for vector search
  • Default model: voyage-multilingual-2
  • Specialized legal model available: voyage-law-2
  • Additional models: voyage-3, voyage-3.5, voyage-3.5-lite, voyage-3-large
  • Configurable via VOYAGEAI_EMBEDDING_MODEL

LLM Client Architecture

graph TD
    Request[Service Request] --> Selector[ModelSelector]
    Selector --> Manager[LLMClientManager]
    Manager --> Bedrock[AWS Bedrock]
    Manager --> OpenAI[OpenAI API]
    Manager --> Anthropic[Anthropic Direct]
    Bedrock --> Claude[Claude Haiku/Sonnet/Opus]
    Bedrock --> Titan[Titan Embed v2]
    OpenAI --> GPT[GPT-5 Nano/Mini/5.1]
    Anthropic --> ClaudeDirect[Claude via API]
    Manager --> Voyage[VoyageAI]
    Voyage --> Embed[voyage-multilingual-2]
Loading

The LLMClientManager from @secondlayer/shared provides:

  • Multi-provider support (OpenAI, Anthropic, Bedrock)
  • Budget-aware model selection via ModelSelector
  • Automatic provider fallback (Bedrock fallback models configured separately)
  • Stream chunk timeout protection (90s between chunks)
  • Cost tracking per request
  • Provider strategy selection (LLM_PROVIDER_STRATEGY)

Authentication Providers

Google OAuth

  • OAuth 2.0 for web user registration and login
  • Configured via GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET
  • Controller: mcp_backend/src/controllers/auth-google.ts

Authentik (OIDC)

  • Self-hosted OIDC identity provider
  • Auto-provisions users for SSO access to Nextcloud and other services
  • Configured via AUTHENTIK_API_URL and AUTHENTIK_API_TOKEN
  • Service: mcp_backend/src/services/authentik-service.ts
  • Controller: mcp_backend/src/controllers/auth-oidc.ts

Diia (Дія.Підпис)

  • Ukrainian national digital identity
  • Strong identity verification via mobile app
  • Company: ТОВ "Лекс ЕйАй"
  • Controller: mcp_backend/src/controllers/auth-diia.ts

WebAuthn / FIDO2

  • Passwordless authentication via hardware security keys or platform authenticators
  • Service: mcp_backend/src/services/webauthn-service.ts

Password Authentication

  • Traditional email + password registration/login
  • Controller: mcp_backend/src/controllers/auth-password.ts

Payment Providers

Monobank (UAH Card Payments)

  • Live payment integration for UAH card payments
  • Acquiring API for payment page generation
  • Webhook callbacks for payment confirmation
  • Dual UAH/USD balance support
  • PUBLIC_URL required for callbacks
  • Routes: mcp_backend/src/routes/payment-routes.ts

NOWPayments (Crypto Payments)

  • Cryptocurrency payment integration via hosted invoices
  • API: https://api.nowpayments.io/v1
  • IPN (Instant Payment Notification) webhook verification
  • Minimum top-up: $1.00 USD
  • Configured via NOWPAYMENTS_API_KEY and NOWPAYMENTS_IPN_SECRET
  • Service: mcp_backend/src/services/nowpayments-service.ts

Deprecated Payment Providers

  • Stripe and Fondy have been removed

Legal Data Sources

ЄДРСР (Unified State Register of Court Decisions)

  • Source: reyestr.court.gov.ua
  • Court decision search and retrieval (full-text and semantic)
  • Data imported via bulk scripts (scripts/edrsr/) from data.gov.ua ZIP archives
  • Incremental sync: sync-edrsr-incremental.sh (downloads current year, imports new records)
  • Stored in PostgreSQL (partitioned tables) with vector embeddings in Qdrant
  • Adapter: mcp_backend/src/adapters/edrsr-local-adapter.ts
  • Services: edrsr-fts-service.ts, edrsr-cache-service.ts, edrsr-vectorizer-service.ts
  • Full-text download from reyestr.court.gov.ua on demand

Verkhovna Rada APIs

Two separate APIs used:

1. zakon.rada.gov.ua (Legislation)

  • Legislation full-text retrieval (HTML scraping of /laws/show/{id}/print)
  • Used by mcp_backend via RadaLegislationAdapter
  • Fetches, parses into articles/sections, stores in PostgreSQL
  • SSRF protection on legislation IDs
  • 30s timeout, rate-limited

2. data.rada.gov.ua (Open Data)

  • Deputies, factions, committees, assistants data (JSON)
  • Bill tracking and status
  • Voting records
  • Used by mcp_rada via RadaAPIAdapter
  • Rate limit: 10 rps (100ms between requests)
  • Cache TTL: 5 minutes for main data blob

data.gov.ua (NAIS Registries via OpenReyestr)

11 registries imported from data.gov.ua into mcp_openreyestr:

Registry Table Size Frequency
Notaries notaries Small Weekly
Court Experts court_experts Small Weekly
Arbitration Managers arbitration_managers Small Daily
Special Notarial Forms special_forms Large Weekly
Forensic Methods forensic_methods Small Weekly
Bankruptcy Cases bankruptcy_cases Medium Daily
Legal Acts (EDRNPA) legal_acts Medium Weekly
Administrative Units administrative_units Large Weekly
Streets Dictionary streets Large Weekly
Enforcement Proceedings (ASVP) enforcement_proceedings Huge Daily
ARMA Seized Assets arma_assets - On demand

Format: XML (windows-1251 or UTF-8) and CSV. Downloaded as ZIP, parsed, imported via GenericXmlImporter.

Prozorro (Public Procurement)

  • Source: public-api.prozorro.gov.ua/api/2.5
  • Tender metadata import (buyer, amount, status, CPV codes)
  • Paginated crawl with configurable concurrency and resume capability
  • Stored in prozorro_tenders table
  • Import script: mcp_openreyestr/src/scripts/import-prozorro.ts

HUDOC (European Court of Human Rights)

  • ECHR case law and legal positions
  • Court session schedules
  • Import scripts: scripts/hudoc/
  • Data stored in PostgreSQL, vectorized for semantic search
  • Tool: search_echr_practice, get_echr_document

OpenData Sources (Additional)

  • UIPV -- Ukrainian IP office (patents, trademarks) via scripts/opendata/nipo/
  • NKCPFR -- Securities and stock market commission data via scripts/opendata/nkcpfr-bulk-import.py
  • spending.gov.ua -- Government spending data via scripts/opendata/spending/
  • EU Open Data -- European datasets via scripts/opendata/eu/
  • Offshore registries -- Luxembourg and other offshore entity data via scripts/opendata/offshore/
  • Vectorization: mcp_backend/src/scripts/vectorize-datasets.ts

Spain Legal Data

  • BOE -- Boletin Oficial del Estado (12,228 consolidated Spanish laws)
  • AEPD -- Agencia Espanola de Proteccion de Datos (GDPR decisions)
  • Full-text search in Spanish with normative type and date filters
  • Tool handler: mcp_backend/src/api/tools/spain-legal-tools.ts
  • Import scripts: scripts/opendata/spain/

KMU Government News

  • Source: www.kmu.gov.ua/api/rss (RSS feed) and individual article pages
  • Headless browser scraping (Playwright) for article content
  • AI analysis generated via LLM
  • Cached in PostgreSQL (news_articles table)
  • Service: mcp_backend/src/services/news-article-service.ts

OSINT Integration (SneakyPiper)

External OSINT proxy service accessed via OsintProxyAdapter:

  • Tool execution via POST /api/v1/tools/execute
  • API key authentication (X-Api-Key header)
  • 30s timeout per request
  • Health check endpoint available

Available OSINT tools (proxied):

  • search_credentials -- Data breach and credential leak lookup
  • search_ransomware_victims -- Ransomware victim database
  • search_forum_subjects -- Darknet forum publications
  • search_sanctions -- Global sanctions lists (OFAC, EU, UN, UA RNBO) and PEP via OpenSanctions
  • search_interpol -- Interpol Red Notices

Infrastructure Services

Cloudflare

  • DNS management and CDN
  • SSL/TLS certificates
  • DDoS protection and WAF rules
  • Rate limiting integration (Turnstile)
  • Maintenance mode scripts: deployment/maintenance/cf-maintenance.sh
  • WAF rules: deployment/cloudflare/waf-rules.sh
  • Credentials: .env.cloudflare (Global API Key + Email)

MinIO (S3-Compatible Storage)

  • Object storage for documents, uploads, consultation files
  • Used in both local dev and production
  • Vault service stores encrypted documents
  • Upload routes for file handling

SMTP (Email)

  • Nodemailer-based email delivery
  • Configurable SMTP host (default: smtp.gmail.com:587)
  • Supports authenticated and IP-based auth modes
  • Used for: payment confirmations, invoices, referrals, GDPR requests
  • Env vars: SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, SMTP_PASS

Deprecated Integrations

ZakonOnline API

ZakonOnline is deprecated and should not be used. The zo-adapter.ts file remains for reference but all HTTP methods return empty results. The EdsrLocalAdapter is the active successor, operating against local PostgreSQL/Qdrant databases while preserving the same public method signatures for backward compatibility.

Previously:

  • Two ZOAdapter instances (court cases vs practice)
  • ZAKONONLINE_API_TOKEN env var (no longer needed)

SecondLayer

Getting Started

Architecture

Backend

Services

Business Logic

Frontend & Mobile

Operations

Clone this wiki locally