# legalize-dev/legalize architecture

> Architecture diagram of the GitHub repository legalize-dev/legalize, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/legalize-dev/legalize
- Repository: https://github.com/legalize-dev/legalize

## Overview

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`](https://github.com/legalize-dev/legalize/blob/main/README.md) (README), [`SPEC.md`](https://github.com/legalize-dev/legalize/blob/main/SPEC.md) (SPEC), [`LICENSE`](https://github.com/legalize-dev/legalize/tree/main/LICENSE) (License)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo_docs["Repo docs"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_spec["SPEC<br/>contract<br/>[SPEC.md]"]
  node_license["License<br/>legal"]
end

subgraph group_platform_core["Platform core"]
  node_country_repos[("Country repos<br/>jurisdiction repos")]
  node_law_md["Law markdown<br/>content model"]
  node_frontmatter["YAML frontmatter<br/>metadata model"]
  node_git_history{{"Git history<br/>versioning"}}
end

subgraph group_ecosystem["Ecosystem"]
  node_sources(("Official sources<br/>government sources"))
  node_pipeline["Pipeline"]
  node_normalize["Normalize<br/>transformation"]
  node_site(("legalize.dev<br/>browse/search surface"))
  node_api["REST API"]
  node_python_sdk["Python SDK<br/>client SDK"]
  node_node_sdk["Node SDK<br/>client SDK"]
  node_go_sdk["Go SDK<br/>client SDK"]
  node_curl_client(("curl<br/>client"))
end

node_readme -->|"points to"| node_spec
node_readme -.->|"separates from"| node_pipeline
node_readme -->|"describes"| node_site
node_spec -->|"defines format for"| node_country_repos
node_license -.->|"governs"| node_readme
node_sources -->|"feeds"| node_pipeline
node_pipeline -->|"runs"| node_normalize
node_normalize -->|"writes"| node_law_md
node_law_md -->|"annotated by"| node_frontmatter
node_law_md -->|"stored in"| node_country_repos
node_country_repos -->|"versioned as"| node_git_history
node_git_history -->|"renders"| node_site
node_git_history -->|"exposed through"| node_api
node_api -->|"consumed by"| node_python_sdk
node_api -->|"consumed by"| node_node_sdk
node_api -->|"consumed by"| node_go_sdk
node_api -->|"queried by"| node_curl_client

click node_readme "https://github.com/legalize-dev/legalize/blob/main/README.md"
click node_spec "https://github.com/legalize-dev/legalize/blob/main/SPEC.md"
click node_license "https://github.com/legalize-dev/legalize/tree/main/LICENSE"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_spec,node_license toneBlue
class node_country_repos,node_law_md,node_frontmatter,node_git_history toneAmber
class node_sources,node_pipeline,node_normalize,node_site,node_api,node_python_sdk,node_node_sdk,node_go_sdk,node_curl_client toneMint
```

## Components

### Repo docs

Top-level documentation and governance files in this umbrella repository.

- [README](https://github.com/legalize-dev/legalize/blob/main/README.md): docs · Umbrella overview of the Legalize platform and ecosystem boundaries. · `README.md`
- [SPEC](https://github.com/legalize-dev/legalize/blob/main/SPEC.md): contract · Minimal format contract for country repositories and interoperability. · `SPEC.md`
- [License](https://github.com/legalize-dev/legalize/tree/main/LICENSE): legal · MIT license for repository structure, metadata, and tooling. · `LICENSE`

### Platform core

Shared data model and repository-based storage model for the Legalize ecosystem.

- **Country repos**: jurisdiction repos · One Git repository per jurisdiction holding the versioned legal corpus.
- **Law markdown**: content model · Canonical storage unit for a law as Markdown text.
- **YAML frontmatter**: metadata model · Machine-readable metadata attached to each law document.
- **Git history**: versioning · Legal change history encoded as commits and diffs.

### Ecosystem

Upstream sources, processing pipeline, and downstream consumers outside this repo.

- **Official sources**: government sources · Country-specific legislative publication sites and official legal feeds.
- **Pipeline**: ingestion pipeline · Fetches, parses, and commits legislation from official sources.
- **Normalize**: transformation · Restructures source legislation into the canonical repository format.
- **legalize.dev**: browse/search surface · Public interface for browsing laws, searching, and inspecting diffs.
- **REST API**: api · Programmatic access layer for legal data and history.
- **Python SDK**: client SDK · Python client for accessing Legalize data and API.
- **Node SDK**: client SDK · Node and TypeScript client for Legalize data access.
- **Go SDK**: client SDK · Go client for Legalize data access.
- **curl**: client · Command-line access pattern for the REST API.

## Connections

- 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.
