Skip to Content
InternalDocsComplianceREADME

README

Source: docs/compliance/README.md

# Compliance Navigator
 
The Compliance Navigator is RGL8R's obligation evaluation engine. It answers the question: **"For this product entering this jurisdiction, what regulatory obligations apply and are they satisfied?"**
 
## Architecture
 
```
Source Documents (PGA guides, CSA program docs)
        |
        v
JSON Snapshots (data/sources/<pack>/)
        |
        v
Ingestion Scripts (scripts/ingest-<pack>.ts)
        |   checksum validation
        |   prisma.$transaction()
        v
ref.ComplianceObligation + app.RuleDefinition
        |
        v
Evaluation Pipeline
        |   complianceNavigator.ts: HS prefix matching, origin/category
        |     filtering, rules engine execution (API-integrated)
        |   cbsaCsaEligibility.ts: entity-based eligibility
        |     (module-level, not yet exposed via API)
        v
API (apps/api/src/routes/compliance.ts)
        |
        v
UI (apps/web — compliance navigator page)
```
 
The system supports two fundamentally different evaluation models:
 
- **Commodity-based** (APHIS CORE): Obligations are matched by HS code prefix, origin country, and product category. The rules engine compiles corridor-scoped rules and matches them against the shipment context.
- **Entity-based** (CBSA CSA): Obligations are matched by entity type (importer, carrier, driver) and evaluated against the tenant's compliance profile fields. No commodity classification is involved.
 
Both models share the same `ref.ComplianceObligation` table and provenance chain. The `criteria` JSON column distinguishes entity-based obligations (which store `entityType` + `requirements`) from commodity-based ones (which use `hsPrefixes`, `productCategories`, and `originCountries`).
 
## Supported Jurisdiction Packs
 
| Pack | Jurisdiction | Authority | Program | Model | Obligations |
|------|-------------|-----------|---------|-------|-------------|
| [APHIS CORE](./aphis-core-pack.md) | US | AAC, ABS, APQ, AVS | CORE | Commodity-based | 20 |
| [CBSA CSA](./cbsa-csa-pack.md) | CA | CBSA | CSA | Entity-based | 5 |
 
## API Endpoints
 
All endpoints are mounted under `/api/compliance` and require JWT or API key authentication.
 
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/compliance/obligations` | List obligations with filtering (jurisdiction, authority, program, hsCode, originCountry, productCategory, status). Paginated. |
| `GET` | `/api/compliance/obligations/:id` | Get a single obligation by UUID. Includes full citation metadata. |
| `POST` | `/api/compliance/check` | Evaluate which obligations apply to a given (hsCode, originCountry, destinationCountry, productCategory) tuple. Returns matched obligations with gap analysis and evidence status. |
| `GET` | `/api/compliance/evidence/:entityType/:entityId` | List obligation evidence for a specific entity (SKU or SHIPMENT). Includes verification status summary. |
 
### Compliance Check Request
 
```json
POST /api/compliance/check
{
  "hsCode": "0603.11",
  "originCountry": "CO",
  "destinationCountry": "US",
  "productCategory": "cut_flowers",
  "importerBondingStatus": "ACTIVE",
  "entityType": "SKU",
  "entityId": "SKU-12345"
}
```
 
Required fields: `hsCode`, `originCountry`. Defaults: `destinationCountry` = `"US"`.
 
### Compliance Check Response
 
Each matched obligation includes:
 
- **Obligation details**: code, name, description, required documents, authority, program
- **Match metadata**: which HS prefix matched, whether origin/category/bonding matched, whether the match came from the rules engine or direct fallback
- **Evidence status**: whether verified evidence exists for this entity
- **Gap analysis**: whether the obligation is satisfied, and which required documents are missing
- **Citation**: source code, source section, release ID, content hash
 
## Data Flow
 
### Source to Database
 
1. **Source documents** (regulatory guides, program manuals) are read and structured into JSON snapshots stored in `data/sources/<pack-name>/`.
2. Each pack includes a **metadata file** with SHA-256 checksums of the snapshot files, source URLs, version identifier, and extraction date.
3. **Ingestion scripts** (`scripts/ingest-<pack>.ts`) validate checksums, then write to the database inside a single `prisma.$transaction()`:
   - `DataSource` — the regulatory body (e.g., USDA APHIS, CBSA)
   - `DataRelease` — the specific version/snapshot being ingested
   - `ComplianceObligation` — individual regulatory obligations
   - `RuleDefinition` — rules engine rules that map obligations to trade corridors
   - `DataChangeLog` — audit trail of every CREATE/UPDATE
 
### Provenance Chain
 
Every obligation carries a full provenance chain back to its source:
 
```
ComplianceObligation
  -> sourceId      -> DataSource (code, name, URL)
  -> releaseId     -> DataRelease (version, checksum, releasedAt)
  -> sourceSection -> "PGA v6.3, APQ section, pp. 120-122"
  -> contentHash   -> SHA-256 of the obligation's normalized payload
```
 
The `DataChangeLog` table records every ingestion event, enabling full audit trail from any obligation back to the exact source document version that created or last modified it.
 
## Database Models
 
### `ref.ComplianceObligation`
 
Central table for all jurisdiction obligations. Key fields:
 
| Field | Type | Purpose |
|-------|------|---------|
| `obligationCode` | `VARCHAR(100)` UNIQUE | Human-readable code (e.g., `APHIS-APQ-CORE-301`) |
| `jurisdictionCode` | `VARCHAR(10)` | ISO country code (US, CA) |
| `authorityCode` | `VARCHAR(30)` | Regulatory authority (APHIS, CBSA) |
| `programCode` | `VARCHAR(30)` | Program within authority (CORE, CSA) |
| `requiredDocuments` | `JSON` | Array of document type codes |
| `hsPrefixes` | `TEXT[]` | HS code prefixes that trigger this obligation |
| `productCategories` | `TEXT[]` | Product categories that trigger this obligation |
| `originCountries` | `TEXT[]` | Origin countries (`*` = all) |
| `criteria` | `JSON?` | Entity-based eligibility criteria (CSA) |
| `status` | `VARCHAR(20)` | ACTIVE, SUSPENDED, REVOKED |
| `sourceSection` | `TEXT` | Citation to source document section |
| `contentHash` | `VARCHAR(64)` | SHA-256 of normalized obligation payload |
 
### `app.ObligationEvidence`
 
Tracks evidence (permits, certificates, declarations) uploaded against obligations for specific entities.
 
### `app.TenantComplianceProfile`
 
Stores entity-based eligibility fields for trusted-trader programs (CSA). One row per tenant + jurisdiction + program.
 
## Further Reading
 
- [APHIS CORE Pack Reference](./aphis-core-pack.md)
- [CBSA CSA Pack Reference](./cbsa-csa-pack.md)
- [Adding New Jurisdiction Packs](./adding-jurisdiction-packs.md)
- [Rule Hierarchy Design](../architecture/cre-rule-hierarchy.md)
Cbsa Csa PackDeployment