Codebase
TWIN, the Trade Worldwide Information Network, evolves the TLIP proof-of-concept into TWIN Core (v2). The architecture focuses on practical deployment, distributed ledger integration, and open-source delivery.
Codebase History
The initiative started in August 2019 and was developed in collaboration with Trademark Africa. The first generation, TLIP/GTSC (v1), moved from proof-of-concept into application form around 2020. The second generation, TWIN Core (v2), started as a new codebase in March 2024, applying the lessons learned from v1.
Design Rationale
The architecture is intentionally shaped by experience from v1. It uses open source to reduce adoption barriers, is designed to augment existing systems rather than replace them, and prioritises interoperability with established infrastructure. Standards-first modelling, extensibility, modularity, and testability are treated as core design constraints.
Philosophy
The codebase is built on standardised patterns and engineering practices that prioritise refactor safety, type-driven development, and consistent message handling across the system. For detailed guidance on the architectural philosophy, patterns, and the reasoning behind key design decisions, see Codebase Philosophy.
Repository Breakdown
The repositories are organised by capability domains such as blob storage. Each repository generally contains models, connectors, and components that work together. Models define standards-aligned object shapes, including REST request and response types. Connectors provide contract implementations for concrete providers such as AWS S3, IPFS, GCP Storage, or Azure Storage. Components usually wrap one or more connectors and add shared business logic such as encryption. Service variants expose component capabilities on the server side, while client variants preserve the same interfaces and route calls through REST.
Package Layers
- Fundamentals (Is, Guards, i18n)
- Cryptography
- Tools (TypeScript to Schema, TypeScript to OpenAPI)
- Standards (Schema.org, DID, ODRL, GS1, UN/CEFACT)
- Data (JSON-LD)
- API Core
- Logging, Telemetry, Background Tasks, Event Bus
- Entity Storage (MySql, Mongo, Scylla, AWS, Azure, GCP)
- Blob Storage (IPFS, AWS, Azure, GCP)
- Messaging (AWS)
- Vault (Hashicorp)
- Wallet / Gas Station
- Identity
- NFT
- Verifiable Storage
- Auditable Item Graph
- Auditable Item Streams
- Document Management
- Attestation
- Immutable Proof
- Rights Management
- Data Processing
- Federated Catalogue
- Dataspace
- Engine Core
- Engine Server (REST/WebSocket)
- Node Core
- Node
- React UI Components
- Svelte UI Components
- Identity Components (Future)
- Playground
- TWIN Identity
- Supply Chain App
- TLIP
The stack is layered from top to bottom. The base layer provides standards, data conventions, and API foundations. Components and connectors provide the operational services and infrastructure integrations. DLT connectors expose ledger-focused capabilities. Building blocks compose higher-level business modules, which then flow into runtime execution across engine, node, and UI surfaces. Applications sit at the bottom as the product-facing layer built on top of these capabilities.
GitHub and Packaging
The codebase is maintained under TWIN Foundation on GitHub and published through the twin.org npm organisation. It currently spans approximately 160 packages, with automated pipelines for build, test, release publishing, and documentation generation.
Usage Model
Connectors are designed to be consumed independently when needed. For composed solutions, the engine is used to configure and instantiate components, and the engine server is used to expose those components over REST. Application teams then build their own business logic by extending engine and engine server capabilities and by adding application-specific endpoints that can call engine services directly.