How legalize-dev/legalize works
1. What this repository is
- This repo is the umbrella/index repository for the Legalize platform.
- It does not appear to contain application code or the ingestion pipeline itself; it mainly defines the project’s documentation, standards, and ecosystem map.
2. Core architecture in one sentence
- Legalize is a federated, Git-native legal data platform: official legislation is pulled from government sources, normalized into Markdown files with YAML frontmatter, and stored in country-specific Git repositories.
3. Primary subsystems in the overall system
- Source ingestion: official government/legal publication sites per country.
- Normalization pipeline: parses and restructures source legislation into a consistent format.
- Country repositories: one repo per jurisdiction, containing the versioned legal corpus.
- Browse/search/diff surface: legalize.dev and related tooling consume the Git history and structured files.
- Client SDKs: separate repos provide API access for Python, Node/TypeScript, Go, and curl.
4. Main data model
- The canonical unit of storage is a law as a Markdown file.
- File metadata lives in YAML frontmatter, which provides machine-readable fields around the legal text.
- Legal changes are represented as Git commits, with the official publication date used as the commit date/context.
5. Data flow
- Official legislative source publishes or updates a law.
- A pipeline fetches and parses the source text.
- The law is written to the appropriate country repo as Markdown + frontmatter.
- Subsequent reforms update the same file and are committed.
- Consumers use Git operations and the Legalize site/API to browse current text, search across laws, and inspect diffs over time.
6. Key boundary: this repo vs. pipeline
- The README explicitly separates this repo from legalize-pipeline, which is the engine that fetches, parses, and commits legislation.
- This repo acts as the documentation and coordination layer, not the transformation engine.
7. Key boundary: country repos
- Each country has its own repository and schema-compliant corpus.
- That means the platform is distributed by jurisdiction, not stored as one monolithic database.
- This makes country data independently maintainable and lets contributors add a new country without changing the rest of the platform.
8. Standards contract
- SPEC.md is the important architectural artifact here: it defines the minimal format contract that each country repo must follow.
- The spec is what keeps independently built pipelines interoperable with the Legalize ecosystem.
9. Consumption layer
- The public site, legalize.dev, is the primary human-facing interface for browsing laws, seeing diffs, and searching across legislation.
- The README also references a REST API and official SDKs, indicating the structured data is intended for both humans and programmatic clients.
10. Operational model
- The system is designed around Git history as legal history.
- This is the central architectural idea: version control is the database, and commits/diffs are the audit trail for legal reform.
11. Technology and runtime implications
- The platform is repository-centric rather than service-centric.
- Git is the main storage/versioning primitive.
- Markdown and YAML are the interchange formats.
- Any pipeline or API implementation lives outside this repo, so the architectural focus here is on format, governance, and repo topology.
12. Trust and licensing boundary
- Legislative content is treated as public domain because it comes from official government publications.
- The repository structure, metadata, and tooling are under MIT License.
- That separation matters architecturally: content rights and platform code are governed differently.
13. What an architecture diagram should show
- At the center: the Legalize specification and repo ecosystem.
- Upstream: many official government sources by country.
- Processing edge: legalize-pipeline or independent pipelines.
- Storage layer: country-specific Git repos with Markdown + YAML.
- Downstream: legalize.dev, API consumers, and SDKs.
- Cross-cutting: SPEC.md as the shared contract.
14. Scope note
- Since this repository is mostly overview/documentation, the important architectural truth is not internal module structure, but the platform decomposition across repos and the Git-based legal data flow.
Main entry points: README.md README · SPEC.md SPEC · LICENSE License
Components 16
Repo docs
Top-level documentation and governance files in this umbrella repository.
Platform core
Shared data model and repository-based storage model for the Legalize ecosystem.
- Country repos · One Git repository per jurisdiction holding the versioned legal corpus.
- Law markdown · Canonical storage unit for a law as Markdown text.
- YAML frontmatter · Machine-readable metadata attached to each law document.
- Git history · Legal change history encoded as commits and diffs.
Ecosystem
Upstream sources, processing pipeline, and downstream consumers outside this repo.
- Official sources · Country-specific legislative publication sites and official legal feeds.
- Pipeline · Fetches, parses, and commits legislation from official sources.
- Normalize · Restructures source legislation into the canonical repository format.
- legalize.dev · Public interface for browsing laws, searching, and inspecting diffs.
- REST API · Programmatic access layer for legal data and history.
- Python SDK · Python client for accessing Legalize data and API.
- Node SDK · Node and TypeScript client for Legalize data access.
- Go SDK · Go client for Legalize data access.
- curl · Command-line access pattern for the REST API.
Connections 17
- README → SPEC: points to · The README centers the shared repository contract.
- README → Pipeline: separates from · Documents the pipeline as a separate repository and runtime.
- README → legalize.dev: describes · Introduces the public browsing and search surface.
- SPEC → Country repos: defines format for · SPEC.md sets the minimum schema each country repo must follow.
- License → README: governs · Repository-level licensing applies to the platform docs and tooling.
- Official sources → Pipeline: feeds · Official publications are fetched from government sources.
- Pipeline → Normalize: runs · The ingestion pipeline parses and normalizes source text.
- Normalize → Law markdown: writes · Normalized laws are emitted as Markdown documents.
- Law markdown → YAML frontmatter: annotated by · YAML frontmatter carries machine-readable metadata.
- Law markdown → Country repos: stored in · Markdown law files live in jurisdiction-specific Git repositories.
- Country repos → Git history: versioned as · Changes to laws are represented as commits and diffs.
- Git history → legalize.dev: renders · The public site reads repository history for browsing and diffs.
- Git history → REST API: exposed through · The API serves structured views over repository history and content.
- REST API → Python SDK: consumed by · Python client integrates with the API.
- REST API → Node SDK: consumed by · Node/TypeScript client integrates with the API.
- REST API → Go SDK: consumed by · Go client integrates with the API.
- REST API → curl: queried by · The API is directly usable from curl.