Rada Legislation Service
Relevant source files
The following files were used as context for generating this wiki page:
The Rada Legislation Service is a core component of the SecondLayer platform designed to provide AI-powered analysis, retrieval, and management of Ukrainian parliamentary data. It specifically handles legislation, codes, and the Constitution of Ukraine by fetching data from the official Verkhovna Rada open data portals (data.rada.gov.ua and zakon.rada.gov.ua). The service enables semantic search over law texts, tracks legislative status, and facilitates cross-referencing between parliamentary data and court cases.
Sources: mcp_rada/README.md:1-15, CLAUDE.md:104-106
Architecture and Components
The service operates within the Model Context Protocol (MCP) framework, supporting a triple transport system: MCP stdio for local integration, a RESTful HTTP API for web applications, and Server-Sent Events (SSE) for distributed streaming. It utilizes a PostgreSQL database for structured storage and Redis for high-performance caching.
Sources: CLAUDE.md:118-124, mcp_rada/README.md:19-25
Data Flow and Synchronization
Legislation data is synchronized through specialized adapters and scripts. The system maintains a cache-first strategy with specific TTL (Time To Live) durations: 30 days for law texts and 1 day for frequently changing bills.
The diagram illustrates the flow of data from external Ukrainian government sources through adapters into the SecondLayer storage layer.
Sources: mcp_rada/IMPLEMENTATION_STATUS.md:116-125, mcp_rada/README.md:120-125
Core Service Components
RadaLegislationAdapter
This adapter is responsible for the extraction and transformation of HTML legislation data into structured formats. It primarily targets the /print endpoint of the Rada portal to retrieve clean, printable versions of laws.
Key functionalities include:
- Metadata Extraction: Identifies document type (code, law, or regulation), status, and adoption dates.
- Article Parsing: Uses regex and Cheerio to segment law texts into individual articles or paragraphs.
- Chunking: Breaks large articles into smaller segments (default 500 characters with 100-character overlap) for optimal vector search performance.
Sources: mcp_backend/src/adapters/rada-legislation-adapter.ts:47-150, mcp_backend/src/adapters/rada-legislation-adapter.ts:316-350
Legislation Sync Scripts
Specialized scripts automate the ingestion of high-priority legal documents, such as those related to the "TCK" (Territorial Recruitment Centers) or general bylaws.
| Script | Purpose | Target Documents |
|---|---|---|
load-tck-legislation.js | Bulk loads substantive law for disputes. | KUpАП (80731-10), Law on Military Duty (2232-12). |
load-bylaws.js | Loads key regulations and orders. | TCC Regulation (154-2022-п), Mobilization Order (560-2024-п). |
sync-laws.ts | General monthly sync. | Constitution, Civil Code, Criminal Code. |
Sources: scripts/load-tck-legislation.js:4-25, scripts/load-bylaws.js:4-15, mcp_rada/IMPLEMENTATION_STATUS.md:237-250
Data Models
The service utilizes several key data structures to manage the complexity of legal texts.
Legislation Metadata
| Field | Type | Description |
|---|---|---|
rada_id | string | Unique identifier from the Rada portal (e.g., "254к/96-вр"). |
type | enum | Categorization: code, law, or regulation. |
status | enum | Operational status: active, amended, or repealed. |
total_articles | number | Total count of articles/paragraphs extracted. |
Sources: mcp_backend/src/adapters/rada-legislation-adapter.ts:6-20
Legislation Article
| Field | Type | Description |
|---|---|---|
article_number | string | The official number (e.g., "124" or "п.1"). |
full_text | string | Cleaned plain text of the article. |
byte_size | number | Size of the text for storage optimization. |
metadata | JSONB | Extraction dates and methods. |
Sources: mcp_backend/src/adapters/rada-legislation-adapter.ts:22-37
MCP Tools for Legislation
The service exposes its functionality through specific MCP tools that allow AI models to interact with legal data.
search_legislation_text
This tool enables full-text search within specific laws and supports retrieval of individual articles. It includes a feature to find court citations for the requested law.
Input Schema Example:
{
"law_identifier": "constitution",
"article": "124",
"include_court_citations": true
}
Sources: mcp_rada/README.md:66-78
Logic Flow: Legislation Retrieval
The sequence illustrates the cache-first retrieval logic, where external API calls are only made if the data is missing or expired.
Sources: mcp_rada/IMPLEMENTATION_STATUS.md:116-125, mcp_backend/src/adapters/rada-legislation-adapter.ts:50-75
Implementation Status and Setup
The service is largely complete in its core infrastructure but requires ongoing maintenance for synchronization scripts.
Key Deployment Commands
- Database Setup:
npm run db:setupfollowed bynpm run migrate. - Initial Ingestion:
npm run sync:lawsto populate the Constitution and major codes. - Vector Indexing: Indexing for semantic search can be triggered via
indexArticlesForVectorSearch(radaId).
Sources: mcp_rada/README.md:32-45, mcp_backend/src/adapters/rada-legislation-adapter.ts:316-320
Conclusion
The Rada Legislation Service provides a robust pipeline for transforming unstructured government data into a searchable, AI-ready legal knowledge base. By combining specialized parsing adapters, a multi-tier caching strategy, and MCP-compliant tool interfaces, it serves as a critical bridge between official Ukrainian legislation and advanced legal tech applications.
Sources: mcp_rada/README.md:148-160