This guide explains how European and international public engineering teams can build, test, and register a national sovereign data connector (e.g. National Laws, Companies, Procurement, Geospatial, or Statistics) into the Universal Slasher & BlockNote ecosystem .
🏛️ Architecture Overview
The Sovereign Connector framework operates across three decoupled layers :
📦 Step 1: Install Dependencies
Choose your runtime environment to install the universal contracts:
Frontend TypeScript SDK
Gestionnaire de paquets 📦 npm bash ⚡ pnpm bash 🧶 yarn bash 🍞 bun bash
📋 Copier npm install @suitenumerique/slash-sources-sdk @suitenumerique/blocknote-sources
Backend Python Engine
Environnement Python 🚀 uv bash 🐍 pip bash 📜 poetry bash 🔒 pipenv bash
📋 Copier uv add django-lasuite-sources
🛠️ Step 2: Implement the Python Provider
Create a new file in your Django application or package (e.g. my_country/providers/law.py) inheriting from BaseSourceProvider:
import requests
from lasuite_sources.base import BaseSourceProvider, SourceSearchResult
from lasuite_sources.security import is_safe_external_url
class CountryLawSourceProvider ( BaseSourceProvider ):
provider_id = "country_law"
source_type = "law" # Universal alias mapped automatically to 'law' and 'case-law'
API_URL = "https://api.legislation.country.gov/v1/search"
def is_enabled (self) -> bool :
return True
def search (self, query: str , limit: int = 5 ) -> list[SourceSearchResult]:
if not is_safe_external_url( self . API_URL ):
raise ValueError ( f "Unsafe external API URL: {self . API_URL} " )
try :
resp = requests.get(
self . API_URL ,
params = { "q" : query, "limit" : limit},
headers = { "Accept" : "application/json" },
timeout = 3.5 , # Non-negotiable DINUM resilience rule
)
resp.raise_for_status()
data = resp.json().get( "results" , [])
except Exception :
# Automatic graceful fallback to mock data on network error
return self .get_mock_search_results(query, limit)
results: list[SourceSearchResult] = []
for item in data:
results.append({
"source_id" : str (item.get( "id" , "" )),
"source_type" : "law" ,
"provider" : "National Gazette & Legal Registry" ,
"title" : item.get( "title" , "" ),
"subtitle" : f "Act n° { item.get( 'number' , '' ) } • Enacted on { item.get( 'date' , '' ) } " ,
"status" : "IN FORCE" ,
"status_badge_color" : "success" ,
"content_html" : f "<blockquote> { item.get( 'text' , '' ) } </blockquote>" ,
"summary" : item.get( "description" , "" ),
"meta_field_1_label" : "Official ID" ,
"meta_field_1_value" : str (item.get( "id" , "" )),
"meta_field_2_label" : "Jurisdiction" ,
"meta_field_2_value" : item.get( "jurisdiction" , "Federal" ),
"meta_field_3_label" : "Status" ,
"meta_field_3_value" : "Consolidated" ,
"url" : f "https://legislation.country.gov/acts/ { item.get( 'id' , '' ) } " ,
})
return results
def get_mock_search_results (self, query: str , limit: int = 5 ) -> list[SourceSearchResult]:
return [
{
"source_id" : "ACT-2026-001" ,
"source_type" : "law" ,
"provider" : "National Gazette (Mock Fallback)" ,
"title" : f "Digital Sovereignty & Public Data Act ( { query } )" ,
"subtitle" : "Act n°2026-001 • Section 12" ,
"status" : "IN FORCE" ,
"status_badge_color" : "success" ,
"content_html" : "<p>All official public registries must be accessible via open standards.</p>" ,
"summary" : "Mandatory standard for public administration interoperability." ,
"meta_field_1_label" : "Official ID" ,
"meta_field_1_value" : "ACT-2026-001" ,
"meta_field_2_label" : "Status" ,
"meta_field_2_value" : "Active" ,
"meta_field_3_label" : "Language" ,
"meta_field_3_value" : "EN" ,
"url" : "https://legislation.country.gov/mock/ACT-2026-001" ,
}
]
⚡ Step 3: Register Dynamic Plugin Discovery (pyproject.toml)
No hardcoded modifications in the core engine are required. Register your provider dynamically using standard Python entry_points:
# pyproject.toml of your package or country extension
[project.entry-points."lasuite_sources.providers"]
country_law = "my_country.providers.law:CountryLawSourceProvider"
country_company = "my_country.providers.company:CountryCompanySourceProvider"
country_stats = "my_country.providers.statistics:CountryStatsSourceProvider"
The SourceRegistry singleton discovers and loads your connector automatically at boot time!
⚛️ Step 4: Frontend Provider Definition (TypeScript SDK)
On the client side, declare the slash trigger and auto-completion palette:
import { defineSourceProvider } from "@suitenumerique/slash-sources-sdk" ;
export const countryLawProvider = defineSourceProvider ({
type: "law" ,
name: "National Legal Gazette" ,
iconName: "scale" ,
slashCommand: "law" ,
slashAliases: [ "act" , "gazette" , "code" , "statute" ],
description: "Search and insert consolidated national acts & legislation" ,
suggest : async ( query : string , limit = 5 ) => {
const res = await fetch (
`/api/v1.0/sources/suggest/?type=law&q=${ encodeURIComponent ( query ) }&limit=${ limit }` ,
);
const data = await res. json ();
return data. map (( item : any ) => ({
id: item.source_id,
title: item.title,
subtitle: item.subtitle,
type: "law" ,
}));
},
search : async ( query : string , limit = 10 ) => {
const res = await fetch (
`/api/v1.0/sources/search/?type=law&q=${ encodeURIComponent ( query ) }&limit=${ limit }` ,
);
const data = await res. json ();
return data.results. map (( item : any ) => ({
entityType: "law" ,
displayMode: "callout" ,
sourceId: item.source_id,
title: item.title,
subtitle: item.subtitle,
status: item.status,
contentHtml: item.content_html,
summary: item.summary,
metaField1Label: item.meta_field_1_label,
metaField1Value: item.meta_field_1_value,
url: item.url,
}));
},
});
🔄 Step 5: Dual-Language Full-Stack Overview
Here is the complete contract symmetry between TypeScript and Python:
Comparatif d'implémentation ⚛️ Frontend BlockNote SDK typescript 🐍 Backend Django Provider python
📋 Copier // TypeScript contract
export interface SourceItem {
readonly id: string;
readonly title: string;
readonly subtitle?: string;
readonly type: SourceEntityType;
readonly status?: string;
readonly freshness?: "live" | "cache" | "mock";
}
🧪 Step 6: Automated Testing & Validation
Validate your connector against the complete resilience and quality suite:
# Run Django backend tests (SSRF, Circuit Breakers, Quotas)
pytest packages/django-lasuite-sources/tests/
# Run TypeScript Vitest tests
npm run packages:test
# Verify SSR Documentation build (0 hydration errors)
npm run docs:build
🚀 Existing Certified Sovereign Country Presets
Explore the official preset configurations already available in this monorepo:
🇪🇺
European Union (13 Connectors) 13 Connectors EUR-Lex, Eurostat, TED (Tenders), CORDIS, CURIA Case Law, data.europa.eu, and EU Whoiswho.
Découvrir →
🇨🇦
Canada Federal (8 Connectors) 8 Connectors Justice Laws, Corporations Canada, Parliament LEGISinfo, StatCan, Open Canada CKAN, CanadaBuys.
Découvrir →
🇩🇪
Germany Bund (5 Connectors) 5 Connectors Gesetze im Internet, GovData.de CKAN, Destatis Genesis-Online, Bundestag DIP, Unternehmensregister.
Découvrir →
🇳🇱
Netherlands Gov (5 Connectors) 5 Connectors Wetten.nl, Data.overheid.nl CKAN, CBS StatLine, BAG Address, KVK Handelsregister.
Découvrir →
🇪🇸
Spain BOE & Gob (6 Connectors) 6 Connectors BOE Boletín Oficial, Datos.gob.es CKAN, INE Statistics, Sede Catastro, PLACSP Procurement.
Découvrir →
🌍
International & UN (4 Connectors) 4 Connectors World Bank Open Data, OECD Data Explorer, WHO Global Observatory, HUDOC Human Rights.
Découvrir →
Last modified on October 4, 2026