# najonghwa/safety-law-db architecture

> Architecture diagram of the GitHub repository najonghwa/safety-law-db, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/najonghwa/safety-law-db
- Repository: https://github.com/najonghwa/safety-law-db

## Overview

#### Purpose and Deliverables
This repository builds a local SQLite, article-level search database for Korean safety and environmental regulations. It gathers laws, administrative notices, annexes, KOSHA guidance, and chemical-substance lists, then packages a Claude Code-facing search workspace. Primary target definitions are in `laws.json`; vocabulary normalization is in `synonyms.json`.

#### Pipeline Entry Points
The intended batch sequence is:
1. Collect legal texts: `collector.py`
2. Collect annexes and parse HWP/text: `annex_collector.py`
3. Collect KOSHA guidance and optionally PDFs: `kosha_collector.py`
4. Collect regulated-substance lists: `substance_collector.py`
5. Normalize and import into SQLite: `importer.py`
6. Audit generated data: `verify_db.py`

These are independent Python CLI stages, run manually on an internet-connected machine.

#### Source Acquisition Boundary
Collectors isolate external-source concerns from database construction:
- `collector.py` obtains legislation and notices from law.go.kr without an API key.
- `annex_collector.py` handles separately published annex content, including HWP extraction.
- `kosha_collector.py` consumes the data.go.kr KOSHA Guide service; a local `kosha_config.json` API key enables PDF retrieval.
- `substance_collector.py` imports chemical regulatory data from ICIS.

Optional binary parsing dependencies (`pypdf`, `gethwp`, `olefile`) affect annex/PDF completeness but not the basic legal-text pipeline.

#### Database Construction and Quality Gate
`importer.py` is the central integration boundary: it converts heterogeneous collector outputs into `data/laws.db`, performs legal-text parsing, extracts CAS identifiers, cleans problematic NULL characters, and chunks annex content for retrieval. `verify_db.py` is the required quality gate, comparing database content with source collection output for loss, omissions, and search spot checks—particularly important because HWP/PDF extraction can truncate content.

#### Search Distribution Runtime
`dist/she-law-db/` is a self-contained consumer workspace rather than a build artifact to execute from the repository root. Its SQLite search CLI, `dist/she-law-db/search_law.py`, uses the generated database copied to `dist/she-law-db/data/laws.db`. It supports text, substance/CAS, and law-name lookup and is designed to run without application servers or LLM infrastructure.

#### Claude Code Integration Boundary
Claude Code behavior is constrained in the distributable workspace:
- `dist/she-law-db/CLAUDE.md` defines evidence-first response rules.
- `dist/she-law-db/.claude/skills/she-law/SKILL.md` defines the search skill.
- `dist/she-law-db/search_law.py` is the retrieval mechanism Claude invokes.

The integration requires cited source provisions; when retrieval yields no evidence, the intended behavior is to report that verification is unavailable rather than synthesize an answer.

Main entry points: [`collector.py`](https://github.com/najonghwa/safety-law-db/blob/main/collector.py) (Legal text collector), [`importer.py`](https://github.com/najonghwa/safety-law-db/blob/main/importer.py) (SQLite importer), [`kosha_collector.py`](https://github.com/najonghwa/safety-law-db/blob/main/kosha_collector.py) (KOSHA collector), [`substance_collector.py`](https://github.com/najonghwa/safety-law-db/blob/main/substance_collector.py) (Substance collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_definitions["Definitions"]
  node_laws_definitions["Law targets<br/>JSON definitions<br/>[laws.json]"]
  node_synonyms["Vocabulary normalization<br/>JSON vocabulary<br/>[synonyms.json]"]
end

subgraph group_collection["Source Collection"]
  node_law_go_kr(("law.go.kr<br/>legislation source"))
  node_kosha_api(("KOSHA Guide API<br/>data.go.kr service"))
  node_icis(("ICIS<br/>chemical source"))
  node_legal_collector["Legal text collector<br/>Python CLI<br/>[collector.py]"]
  node_annex_collector["Annex collector<br/>Python CLI<br/>[annex_collector.py]"]
  node_kosha_collector["KOSHA collector<br/>Python CLI<br/>[kosha_collector.py]"]
  node_substance_collector["Substance collector<br/>Python CLI"]
end

subgraph group_build["Database Build"]
  node_collected_outputs["Collected source outputs<br/>heterogeneous data"]
  node_importer["SQLite importer<br/>Python CLI<br/>[importer.py]"]
  node_laws_db[("Search database<br/>SQLite")]
  node_verifier["Database audit<br/>Python CLI<br/>[verify_db.py]"]
end

subgraph group_workspace["Search Workspace"]
  node_distributed_db[("Bundled database<br/>SQLite")]
  node_search_cli["Search CLI<br/>Python CLI<br/>[search_law.py]"]
  node_claude_rules["Evidence rules<br/>Claude instructions<br/>[CLAUDE.md]"]
  node_search_skill["SHE law search skill<br/>Claude skill<br/>[SKILL.md]"]
end

node_laws_definitions -->|"defines targets"| node_legal_collector
node_law_go_kr -->|"collects"| node_legal_collector
node_legal_collector -->|"legal texts"| node_collected_outputs
node_annex_collector -->|"annexes"| node_collected_outputs
node_kosha_api -->|"guidance and PDFs"| node_kosha_collector
node_kosha_collector -->|"KOSHA content"| node_collected_outputs
node_icis -->|"regulatory lists"| node_substance_collector
node_substance_collector -->|"substances"| node_collected_outputs
node_synonyms -->|"normalizes vocabulary"| node_importer
node_collected_outputs -->|"integrates"| node_importer
node_importer -->|"builds"| node_laws_db
node_collected_outputs -->|"compares sources"| node_verifier
node_laws_db -->|"audits"| node_verifier
node_laws_db -->|"copies for distribution"| node_distributed_db
node_distributed_db -->|"queries"| node_search_cli
node_claude_rules -->|"constrains behavior"| node_search_skill
node_search_skill -->|"invokes retrieval"| node_search_cli

click node_laws_definitions "https://github.com/najonghwa/safety-law-db/blob/main/laws.json"
click node_synonyms "https://github.com/najonghwa/safety-law-db/blob/main/synonyms.json"
click node_legal_collector "https://github.com/najonghwa/safety-law-db/blob/main/collector.py"
click node_annex_collector "https://github.com/najonghwa/safety-law-db/blob/main/annex_collector.py"
click node_kosha_collector "https://github.com/najonghwa/safety-law-db/blob/main/kosha_collector.py"
click node_substance_collector "https://github.com/najonghwa/safety-law-db/blob/main/substance_collector.py"
click node_importer "https://github.com/najonghwa/safety-law-db/blob/main/importer.py"
click node_verifier "https://github.com/najonghwa/safety-law-db/blob/main/verify_db.py"
click node_search_cli "https://github.com/najonghwa/safety-law-db/blob/main/dist/she-law-db/search_law.py"
click node_claude_rules "https://github.com/najonghwa/safety-law-db/blob/main/dist/she-law-db/CLAUDE.md"
click node_search_skill "https://github.com/najonghwa/safety-law-db/blob/main/dist/she-law-db/.claude/skills/she-law/SKILL.md"

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_laws_definitions,node_synonyms toneBlue
class node_law_go_kr,node_kosha_api,node_icis,node_legal_collector,node_annex_collector,node_kosha_collector,node_substance_collector toneAmber
class node_collected_outputs,node_importer,node_laws_db,node_verifier toneMint
class node_distributed_db,node_search_cli,node_claude_rules,node_search_skill toneRose
```

## Components

### Definitions

- [Law targets](https://github.com/najonghwa/safety-law-db/blob/main/laws.json): JSON definitions · Primary target law definitions. · `laws.json`
- [Vocabulary normalization](https://github.com/najonghwa/safety-law-db/blob/main/synonyms.json): JSON vocabulary · `synonyms.json`

### Source Collection

- **law.go.kr**: legislation source · Public laws and administrative notices.
- **KOSHA Guide API**: data.go.kr service · Optional API-key-enabled PDF retrieval.
- **ICIS**: chemical source
- [Legal text collector](https://github.com/najonghwa/safety-law-db/blob/main/collector.py): Python CLI · `collector.py`
- [Annex collector](https://github.com/najonghwa/safety-law-db/blob/main/annex_collector.py): Python CLI · Collects annexes and extracts HWP/text. · `annex_collector.py`
- [KOSHA collector](https://github.com/najonghwa/safety-law-db/blob/main/kosha_collector.py): Python CLI · Collects guidance and optional PDFs. · `kosha_collector.py`
- [Substance collector](https://github.com/najonghwa/safety-law-db/blob/main/substance_collector.py): Python CLI · `substance_collector.py`

### Database Build

- **Collected source outputs**: heterogeneous data · Intermediate legal, annex, guide, and substance content.
- [SQLite importer](https://github.com/najonghwa/safety-law-db/blob/main/importer.py): Python CLI · Parses, cleans, extracts CAS, and chunks annex retrieval content. · `importer.py`
- **Search database**: SQLite · Article-level Korean safety and environmental regulation index.
- [Database audit](https://github.com/najonghwa/safety-law-db/blob/main/verify_db.py): Python CLI · Checks loss, omissions, extraction completeness, and search results. · `verify_db.py`

### Search Workspace

- **Bundled database**: SQLite
- [Search CLI](https://github.com/najonghwa/safety-law-db/blob/main/dist/she-law-db/search_law.py): Python CLI · Text, substance/CAS, and law-name retrieval. · `dist/she-law-db/search_law.py`
- [Evidence rules](https://github.com/najonghwa/safety-law-db/blob/main/dist/she-law-db/CLAUDE.md): Claude instructions · Requires cited provisions and unavailable-verification responses. · `dist/she-law-db/CLAUDE.md`
- [SHE law search skill](https://github.com/najonghwa/safety-law-db/blob/main/dist/she-law-db/.claude/skills/she-law/SKILL.md): Claude skill · `dist/she-law-db/.claude/skills/she-law/SKILL.md`

## Connections

- Law targets → Legal text collector: defines targets
- law.go.kr → Legal text collector: collects
- Legal text collector → Collected source outputs: legal texts
- Annex collector → Collected source outputs: annexes
- KOSHA Guide API → KOSHA collector: guidance and PDFs
- KOSHA collector → Collected source outputs: KOSHA content
- ICIS → Substance collector: regulatory lists
- Substance collector → Collected source outputs: substances
- Vocabulary normalization → SQLite importer: normalizes vocabulary
- Collected source outputs → SQLite importer: integrates
- SQLite importer → Search database: builds
- Collected source outputs → Database audit: compares sources
- Search database → Database audit: audits
- Search database → Bundled database: copies for distribution
- Bundled database → Search CLI: queries
- Evidence rules → SHE law search skill: constrains behavior
- SHE law search skill → Search CLI: invokes retrieval