External Integrations
Relevant source files
The following files were used as context for generating this wiki page:
External Integrations represent the critical bridge between the SecondLayer platform and third-party data providers, AI models, and governmental databases. The system utilizes an adapter-based architecture to interface with Ukrainian legal databases (ZakonOnline), parliament data (Verkhovna Rada), and state registries, while managing Large Language Model (LLM) communications through specialized client managers.
These integrations enable core functionalities such as AI-powered document analysis, semantic search over court decisions, and real-time monitoring of legislative changes. By abstracting the complexity of external APIs into standardized services, the platform ensures consistent data handling and robust error recovery across different providers.
Sources: CLAUDE.md:65-71, mcp_rada/IMPLEMENTATION_STATUS.md:143-155
AI Provider Integration
The platform manages AI capabilities through the LLMClientManager, which handles communication with both OpenAI and Anthropic. This layer provides automatic retry logic, token rotation, and budget-aware model selection.
LLM Client Management
The integration supports multiple providers to ensure high availability and cost-efficiency. The system differentiates between "Quick" (gpt-4o-mini), "Standard" (gpt-4o-mini), and "Deep" (gpt-4o) analysis tiers.
The diagram shows how service requests are routed through a model selector to the appropriate LLM provider based on budget and complexity.
| Component | Provider | Usage |
|---|---|---|
| OpenAI API | OpenAI | Embeddings (text-embedding-ada-002) and Analysis (GPT-4o) |
| Anthropic API | Anthropic | Alternative LLM provider for analysis |
| ModelSelector | Internal | Logic for choosing models based on task budget |
Sources: CLAUDE.md:124-129, mcp_rada/IMPLEMENTATION_STATUS.md:46-51, deployment/LOCAL_DEVELOPMENT.md:160-165
Legal Data Adapters
The system employs specific adapters to fetch and normalize data from Ukrainian legal and governmental sources.
ZakonOnline (ZO) Adapter
The ZOAdapter is the primary interface for court case data. The platform maintains two distinct instances of this adapter: one dedicated to searching court cases and another for the legal practice database. It handles document retrieval, metadata extraction, and full-text searches.
Key Endpoints & Functionality:
- Court Case Search: Fetches judicial decisions and metadata.
- Practice Database: Retrieves specialized legal practice documents.
- Document Text: Fetches raw text for analysis tools.
Sources: CLAUDE.md:154-157, mcp_backend/src/adapters/zo-adapter.ts, mcp_backend/DEPLOYMENT.md:255-258
Verkhovna Rada (Parliament) Integration
The RadaAPIAdapter and ZakonRadaAdapter fetch data from official parliament sources (data.rada.gov.ua and zakon.rada.gov.ua). This integration provides real-time access to:
- Deputies: Information on members of parliament.
- Bills: Status and details of legislative proposals.
- Legislation: Official law texts, including codes and the Constitution.
- Voting: Plenary session voting records for analysis.
This flowchart illustrates the separation between parliament open data (API) and official legislative text retrieval (Zakon).
Sources: mcp_rada/IMPLEMENTATION_STATUS.md:65-115, CLAUDE.md:99-105
Infrastructure & Service Integration
External integrations are supported by a localized infrastructure including vector databases and caching layers.
Vector and Caching Layers
- Qdrant: Stores vector embeddings generated via OpenAI for semantic search and legal pattern matching.
- Redis: Acts as a caching layer for external API responses to reduce latency and API costs.
- MinIO: Provides object storage for uploaded legal documents and processed files.
| Service | Port | Integration Purpose |
|---|---|---|
| Qdrant | 6333 | Semantic/Vector Search Storage |
| Redis | 6379 | API Response Caching |
| PostgreSQL | 5432 | Structured Metadata Storage |
Sources: CLAUDE.md:131-140, deployment/LOCAL_DEVELOPMENT.md:65-75
Cross-Reference Logic
The CrossReferenceService links disparate data sources, such as connecting parliament bills to existing court cases.
The sequence diagram demonstrates the flow of data when analyzing the impact of a legislative bill by searching for related court precedents.
Sources: mcp_rada/IMPLEMENTATION_STATUS.md:143-157, mcp_backend/src/routes/TEMPLATE_ROUTES_INTEGRATION.md:175-195
Configuration & Authentication
Integrations are authenticated using a dual-layer approach:
- API Keys: Provided in environment variables (e.g.,
OPENAI_API_KEY,ZAKONONLINE_API_TOKEN). - Internal Bearer Tokens: Controlled via
SECONDARY_LAYER_KEYSfor client-to-server communication.
Required Environment Variables:
| Variable | Description |
|---|---|
OPENAI_API_KEY | Credential for OpenAI LLM and Embedding services. |
ZAKONONLINE_API_TOKEN | Token for accessing the ZakonOnline court database. |
DATABASE_URL | Connection string for the PostgreSQL persistence layer. |
QDRANT_URL | URL for the vector database endpoint. |
Sources: deployment/LOCAL_DEVELOPMENT.md:140-155, CLAUDE.md:215-225
Conclusion
The external integrations within SecondLayer form a sophisticated network of adapters and managers that abstract the volatility of external legal and AI APIs. By combining standardized LLM management with specialized adapters for Ukrainian parliament and court data, the system provides a unified interface for complex legal technology applications. This architecture facilitates high-performance features like semantic search and legislative impact analysis while maintaining robust error handling and cost efficiency.