1. A Short Introduction to IGSDB V2

What's changed

The first version of the IGSDB moved away from the the largely flat, file-centric IGDB/CGDB (.mdb) world to a web-based database and a prototype API. In IGSDB v2, we've refined and extended both the database and the API, moving toward a normalized, relationship-first data model. In the process, we've greatly improved data quality, API clarity, and the overall codebase.

Data model

Products now explicitly reference their components, manufacturers, and related resources, and complex assemblies (like venetian blinds) are represented as "compositions" with well-defined child products and structured geometry/extra-data. Identifiers are modernized: the V1-only integer product_id is deprecated in favor of a stable, opaque token identifier that travel consistently across APIs and versions and has semantic value for human readers. Versioning, checksums, and provenance are tracked so data lineage is auditable.

API structure and documentation

The API surface is rebuilt for clarity and consistency. V2 introduces token-based retrieval and a clean separation between list and detail representations, with list endpoints focused on discovery and detail endpoints returning full spectral data and summaries. Data is shaped for consumers, for example:

• Spectral data and integrated summary values are more structured and contain more detail.
• Product relationships (components, manufacturers, equivalents) are explicit.
• Identifiers are stable and opaque, avoiding leakage of internal database details.
• More consistent and logical enumerated values (e.g. product type, subtype).

Meanwhile, legacy consumers are supported through a compatibility V1 layer backed by the v2 database (including exclusions for films/coatings/interlayers where V1 clients, like LBNL's WINDOW application, expect them). Where applicable, v2 now uses a composition structure to expose nested relationships in a single response, such as venetian blinds referencing their shade-material child, or laminates referencing their glass, interlayer, and coating components. For logged in users, the API is fully documented with Swagger/OpenAPI , including example requests and responses, and is browsable through the web interface.

The API was also structured to support publication of new IGDB and CGDB versions from LBNL's companion tool, the "Checkertool", complete with fully documented and structured release notes.

Performance

Performance and reliability are addressed end-to-end. Heavy endpoints are fronted by prebuilt caches keyed by clear cache types; Celery workers build and refresh those caches asynchronously with atomic cache locks to avoid duplicate work; and timeouts/logging provide operational visibility. CSV generation and other one-off artifacts are handled transactionally with get_or_create/select_for_update patterns to prevent race conditions.

Developer ergonomics and operability

Finally, developer ergonomics and operability improved. The test framework was overhauled to use pytest, with factories and fixtures to simplify test setup and teardown, and more comprehensive test coverage. The codebase was restructured to separate apps by domain (products, versions, users) and the API classes were reorganized for clarity and consistency. Documentation was added and improved, including auto-generated API docs with Swagger/OpenAPI, and a new help section on the website.

Summary

Together, these changes shift IGSDB from a file-era, consumer-specific feed to a robust, API-first platform with a richer domain model, clearer contracts, and operational durability.