# Sydonia Toolkit > A faithful, fully-grounded PostgreSQL reference data model of the UNCTAD ASYCUDA World (SYDONIA) customs management system, reconstructed from public documentation only. 55 tables across 8 modules (manifest, SAD declaration, valuation, taxes, selectivity, accounting, transit/suspense, audit), for sandbox, analytics, integration and training use. Every `CREATE TABLE` is grounded in public documentation (`-- src:`) or honestly marked `-- inferred` (49 documented / 6 inferred). The model loads into a dedicated `asycuda` PostgreSQL schema and ships with reference seed data and a worked end-to-end example (manifest → declaration → valuation → taxes → selectivity → payment → release). This is a reference reconstruction — it contains no proprietary ASYCUDA schema, pirated software, or data from any live customs system. For the entire documentation as a single file, see [llms-full.txt](https://francoischastel.github.io/sydonia-toolkit/latest/llms-full.txt). ## Getting started - [Quickstart](https://francoischastel.github.io/sydonia-toolkit/latest/getting-started/quickstart/): create a database and run the end-to-end example in one minute. - [Installation](https://francoischastel.github.io/sydonia-toolkit/latest/getting-started/installation/): PostgreSQL 14+, the `asycuda` schema, idempotent reloads, Docker, troubleshooting. - [Customs concepts](https://francoischastel.github.io/sydonia-toolkit/latest/getting-started/concepts/): domain primer — manifest, bill of lading, the SAD, valuation, taxes, selectivity, lifecycle — mapped to tables. ## Querying Sydonia (the real ASYCUDA World tables) - [Querying Sydonia](https://francoischastel.github.io/sydonia-toolkit/latest/querying-sydonia/): how to query a real ASYCUDA World database — the wide, denormalised real tables, and the two ways to query them (directly, or via the friendly logical model + compiler). - [Declaration tables](https://francoischastel.github.io/sydonia-toolkit/latest/querying-sydonia/declaration-tables/): SAD_General_Segment, SAD_Item, SAD_Tax — columns, the documented COD/BSE/RAT/AMT/MOP tax roots, HS split across TAR_HSC_NB1..5, PTY colour flags. - [Manifest tables](https://francoischastel.github.io/sydonia-toolkit/latest/querying-sydonia/manifest-tables/): GEN_TAB, BOL_TAB, CTN_TAB — manifest general segment, bills of lading, containers. - [Reference tables](https://francoischastel.github.io/sydonia-toolkit/latest/querying-sydonia/reference-tables/): the UN*/xx*TAB code tables — code+name stored inline, VALID_FROM/VALID_TO temporal validity. - [Joins & gotchas](https://francoischastel.github.io/sydonia-toolkit/latest/querying-sydonia/joins-and-gotchas/): INSTANCE_ID keys, general-segment repetition, HS split, code+name inline, validity dates — and how the compiler handles each automatically. ## The query compiler (write friendly, run genuine) - [The query compiler](https://francoischastel.github.io/sydonia-toolkit/latest/compiler/): compile friendly logical SQL (or a no-SQL query spec) into genuine ASYCUDA World SQL you can run read-only on a real Sydonia — via a CTE prelude over the real tables. - [Logical SQL](https://francoischastel.github.io/sydonia-toolkit/latest/compiler/logical-sql/): write against the friendly names; `python -m compiler compile` emits the genuine SQL. - [The query builder](https://francoischastel.github.io/sydonia-toolkit/latest/compiler/builder/): a no-SQL query spec (from/join/where/select) → logical SQL → genuine SQL. - [The mapping](https://francoischastel.github.io/sydonia-toolkit/latest/compiler/mapping/): the logical→physical mapping, documented default + per-instance overrides, and emit-views for persistent compatibility views. - [Running it](https://francoischastel.github.io/sydonia-toolkit/latest/compiler/running/): the reconstruction sandbox, the mock ASYCUDA World database (proves the round-trip), and a real instance — read-only, privacy-preserving. ## The logical model - [Schema overview](https://francoischastel.github.io/sydonia-toolkit/latest/schema/): the 8 modules, conventions, and provenance legend — the friendly logical layer the compiler maps from. - [Reference & configuration](https://francoischastel.github.io/sydonia-toolkit/latest/schema/reference-config/): the `ref_*` code tables (ISO/UN/WCO standards) plus traders and system users. - [Manifest & cargo](https://francoischastel.github.io/sydonia-toolkit/latest/schema/manifest/): manifest, bills of lading (master/house degroupage), containers, cargo lines. - [Declaration (the SAD)](https://francoischastel.github.io/sydonia-toolkit/latest/schema/declaration/): general + item segments, valuation notes, tax lines, attached/previous documents. - [Selectivity & risk](https://francoischastel.github.io/sydonia-toolkit/latest/schema/selectivity/): risk criteria, GREEN/YELLOW/RED/BLUE lanes, inspection acts. - [Accounting](https://francoischastel.github.io/sydonia-toolkit/latest/schema/accounting/): accounts, payments, receipts, ledger movements, guarantees. - [Transit & suspense](https://francoischastel.github.io/sydonia-toolkit/latest/schema/transit-suspense/): warehousing, transit, temporary admission. - [Audit & workflow](https://francoischastel.github.io/sydonia-toolkit/latest/schema/audit/): the audit log and status-history pattern. - [Entity-relationship diagram](https://francoischastel.github.io/sydonia-toolkit/latest/schema/erd/): every foreign key, rendered from the loaded schema. - [Data dictionary](https://francoischastel.github.io/sydonia-toolkit/latest/schema/data-dictionary/): every table and column with type, nullability and source. ## The platform (ASYCUDA itself) - [The platform](https://francoischastel.github.io/sydonia-toolkit/latest/platform/): which ASYCUDA version this toolbox models (ASYCUDA World, v4) and how to fingerprint the one you have. - [Version lineage](https://francoischastel.github.io/sydonia-toolkit/latest/platform/versions/): the five generations (v1 1981 → v2 → ASYCUDA++ → ASYCUDA World → ASY5/New Generation), compared. - [ASYCUDA World](https://francoischastel.github.io/sydonia-toolkit/latest/platform/asycuda-world/): the modeled version in depth — XML e-document model, Java client, closed protocol, and how our schema relates to the unpublished physical one. - [XML messages & wire format](https://francoischastel.github.io/sydonia-toolkit/latest/platform/xml-messages/): the SAD Box → AW XML tag → toolbox column map, the ``-root wire-format gotcha, the AWMDS manifest stream, WCO Data Model and EDIFACT lineage. - [Integration surfaces](https://francoischastel.github.io/sydonia-toolkit/latest/platform/integration/): the doors that actually exist (RDBMS/ETL, ASYHUB, IATA Cargo-XML, XML import, ASY5) and the restricted specs you must request. - [Running on a real ASYCUDA World](https://francoischastel.github.io/sydonia-toolkit/latest/platform/running-on-real-asycuda/): the bridge from this toolbox to your live ASYCUDA data for analytics / ML / selectivity — read-only compatibility views (adapting the wide real schema to our normalised model so every query and skill runs unchanged) or ETL into the reference model for bulk work. - [Selectivity & clearance](https://francoischastel.github.io/sydonia-toolkit/latest/platform/selectivity-clearance/): the clearance state machine (C/L/PRN serials) and four-lane risk model, mapped to the schema. - [Further reading](https://francoischastel.github.io/sydonia-toolkit/latest/platform/resources/): curated map of the public ASYCUDA documentation landscape and what is member-restricted. ## Guides - [Loading the schema](https://francoischastel.github.io/sydonia-toolkit/latest/guides/loading/): integration patterns — CI, test resets, coexisting with your own tables, namespacing. - [Querying the model](https://francoischastel.github.io/sydonia-toolkit/latest/guides/querying/): the key join paths and an analytics cookbook (revenue by HS, assessed-vs-paid, lane throughput, warehouse stock). - [Useful queries](https://francoischastel.github.io/sydonia-toolkit/latest/guides/useful-queries/): a growing, verified library of analytical queries with a copy-paste entry format — effective duty rates, valuation/unit-price outliers, selectivity criterion hit-rates, importer discrepancy profiles, lifecycle dwell times, data-quality checks — the feature-extraction and selectivity building blocks for ML. - [Extending the schema](https://francoischastel.github.io/sydonia-toolkit/latest/guides/extending/): add tables/columns while keeping conventions and provenance intact. - [Worked example](https://francoischastel.github.io/sydonia-toolkit/latest/guides/worked-example/): `e2e.sql` narrated step by step. - [ML on customs data](https://francoischastel.github.io/sydonia-toolkit/latest/guides/ml-risk-engine/): the ML risk-engine blueprint — public customs-ML features mapped to SAD boxes and toolbox columns, labels from the Inspection Act, the lane loop, prototyping on this schema. ## Provenance - [Reconstruction methodology](https://francoischastel.github.io/sydonia-toolkit/latest/provenance/methodology/): the evidence-first loop, source policy, and verification gates. - [Sources](https://francoischastel.github.io/sydonia-toolkit/latest/provenance/sources/): the public documentation consulted, cited as generic categories. - [Coverage](https://francoischastel.github.io/sydonia-toolkit/latest/provenance/coverage/): every module/table marked documented / partial / inferred, with known gaps. - [Official fit & gap](https://francoischastel.github.io/sydonia-toolkit/latest/provenance/fit/): table-by-table mapping against the official ASYCUDA World tables. ## Agent Skills - [Agent Skills](https://francoischastel.github.io/sydonia-toolkit/latest/skills/): a suite of standard Agent Skills (setup, query, seed, extend, validate) — installable into any agent (Claude Code, Cursor, Codex, opencode, …) via `npx skills add` — to use the model on your own codebase. ## Optional - [GitHub repository](https://github.com/FrancoisChastel/sydonia-toolkit): the SQL schema, seed data, worked example, cached sources, and skills. - [Schema SQL](https://github.com/FrancoisChastel/sydonia-toolkit/blob/master/Sydonia/schema/asycuda.sql): the 55-table DDL with inline provenance tags.