docs: Describe top-level architecture of SDK #1599

scouten-adobe · 2025-11-14T00:48:17Z

No description provided.

codecov · 2025-11-14T00:52:02Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.47%. Comparing base (b527235) to head (8e1b487).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1599   +/-   ##
=======================================
  Coverage   75.47%   75.47%           
=======================================
  Files         165      165           
  Lines       37019    37019           
=======================================
  Hits        27941    27941           
  Misses       9078     9078

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

codspeed-hq · 2025-11-14T00:53:53Z

CodSpeed Performance Report

Merging #1599 will not alter performance

_{Comparing scouten/doc-top-level-architecture (8e1b487) with main (b527235)}

Summary

✅ 16 untouched
⏩ 2 skipped¹

2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

tmathern · 2025-11-18T00:22:04Z

sdk/src/README.md

+
+## Architectural overview
+
+The SDK follows a layered architecture that separates concerns between user-facing APIs, data models, storage, asset I/O, cryptography, and validation.


I would call user-facing APIs -> public APIs. It's what they are,e ventually.

tmathern · 2025-11-18T00:23:19Z

sdk/src/README.md

+The SDK follows a layered architecture that separates concerns between user-facing APIs, data models, storage, asset I/O, cryptography, and validation.
+
+```mermaid
+graph TB


I sometimes consider the signer public, because users can technically define theirs (callback signers).

tmathern · 2025-11-18T00:25:43Z

sdk/src/README.md

+##### Key responsibilities
+
+- Assemble manifest definitions from ingredients, assertions, and resources
+- Coordinate with signers to create cryptographic signatures


Here, that is why I see Signers as public. They are not totally hidden.

tmathern · 2025-11-18T00:26:03Z

sdk/src/README.md

+
+- Assemble manifest definitions from ingredients, assertions, and resources
+- Coordinate with signers to create cryptographic signatures
+- Embed signed manifests into assets via asset handlers


asset handlers = format handlers?

Yes internally we reference them as asset handlers. I usually like to refer to them as parsers although I'm not sure what language is most clear.

So we have multiple vocabulary options here ;). Maybe we need a glossary at the top..

tmathern · 2025-11-18T00:26:49Z

sdk/src/README.md

+
+##### Key responsibilities
+
+- Extract JUMBF manifest stores from assets


I would rather say read? Since the JUMBF is left in place in the asset, reading is not destructive

tmathern · 2025-11-18T00:34:49Z

sdk/src/README.md

+- Load JUMBF from asset streams (via appropriate handler)
+- Save JUMBF to asset streams (via appropriate handler)
+- Support multiple asset formats through handler registry
+- Provide format detection


Already? I thought that was WIP for some?

tmathern · 2025-11-18T00:36:21Z

sdk/src/README.md

+
+##### Key responsibilities
+
+- Define `ValidationState` enum (Invalid, Valid, Trusted)


Link to the spec maybe?

tmathern · 2025-11-18T00:36:51Z

sdk/src/README.md

+- Define `ValidationState` enum (Invalid, Valid, Trusted)
+- Track validation status codes (success, informational, failure)
+- Support ingredient delta validation (changes from previous validation)
+- Provide structured reporting for validation outcomes


I would put that bullet point second, because the others then clarify this

tmathern · 2025-11-18T00:37:18Z

sdk/src/README.md

+- Provide event iteration and reporting
+- Convert to user-facing validation results
+
+### Identity layer


I think that one may need to be higher up?

tmathern · 2025-11-18T00:38:18Z

sdk/src/README.md

+
+    Builder->>Claim: Build claim structure
+    Claim->>Claim: Add assertions
+    Claim->>Claim: Add ingredients


Add ingredients technically is optional (especially if you "create" an asset, which does not have a parent).

ok-nick · 2025-11-14T15:09:40Z

sdk/src/README.md

+    style Builder fill:#fff4e1
+    style Reader fill:#e1f5ff
+    style Store fill:#e8f5e9
+    style Crypto fill:#f3e5f5


The colors here can be difficult to see in dark mode.

ok-nick · 2025-11-18T14:30:06Z

sdk/src/README.md

+
+The SDK follows a layered architecture that separates concerns between user-facing APIs, data models, storage, asset I/O, cryptography, and validation.
+
+```mermaid


I'm not sure how accurate this diagram is. There's a few places where the arrows are incorrect, e.g. asset_io doesn't reference jumbf_io, the claim doesn't reference the resource store, etc. I think there's also quite a few missing arrows too, such as in the validation layer.

ok-nick · 2025-11-18T14:31:29Z

sdk/src/README.md

+
+The outermost layer provides high-level APIs for common workflows.
+
+#### `Builder` ([builder.rs](builder.rs))


This is really cool how it knows where to reference the file.

ok-nick · 2025-11-18T14:32:55Z

sdk/src/README.md

+
+#### `Builder` ([builder.rs](builder.rs))
+
+Creates and signs C2PA manifests. The `Builder` provides both declarative (JSON-based) and imperative (method-based) interfaces for constructing manifests.


I like to think of the JSON API as a separate API that's above the Builder. The definitions are a bit intertwined but there's ongoing work to fix that.

It's a little bit like the Signer, they work together eventually.

ok-nick · 2025-11-18T14:34:30Z

sdk/src/README.md

+
+- Assemble manifest definitions from ingredients, assertions, and resources
+- Coordinate with signers to create cryptographic signatures
+- Embed signed manifests into assets via asset handlers


Yes internally we reference them as asset handlers. I usually like to refer to them as parsers although I'm not sure what language is most clear.

ok-nick · 2025-11-18T14:42:10Z

sdk/src/README.md

+- [`Assertion`](#assertion-assertionrs)
+- [`assertions/`](#assertions)
+- [`hashed_uri.rs`](hashed_uri.rs)
+- [`ResourceStore`](#resourcestore-resource_storers)


Claim doesn't use the ResourceStore.

ok-nick · 2025-11-18T14:44:33Z

sdk/src/README.md

+- [`assertions/`](#assertions)
+- [`ResourceStore`](#resourcestore-resource_storers)
+
+#### `Ingredient` ([ingredient.rs](ingredient.rs))


We should make it clear here that an "ingredient" is really just an assertion that wraps a C2PA manifest. I believe there is ongoing work to clarify this in the APIs.

ok-nick · 2025-11-18T14:47:22Z

sdk/src/README.md

+
+Defines traits for asset I/O operations. These traits abstract over different asset formats, allowing the SDK to handle JPEG, PNG, MP4, and other formats uniformly.
+
+##### Key traits


There's a few more traits we may want to describe here. There's also the CAIRead trait.

ok-nick · 2025-11-18T14:48:05Z

sdk/src/README.md

+- Load JUMBF from asset streams (via appropriate handler)
+- Save JUMBF to asset streams (via appropriate handler)
+- Support multiple asset formats through handler registry
+- Provide format detection


We don't necessarily detect formats.

ok-nick · 2025-11-18T14:48:39Z

sdk/src/README.md

+
+Defines the `Signer` and `AsyncSigner` traits that abstract over different signing implementations. This allows the SDK to work with various signing mechanisms (local keys, HSMs, remote services, etc.).
+
+##### Key responsibilities


Also good to mention time authorities here.

Isn't that Coordinate with timestamp authorities? Or do you mean more details?

tmathern · 2025-11-19T03:41:31Z

sdk/src/README.md

+
+#### `Builder` ([builder.rs](builder.rs))
+
+Creates and signs C2PA manifests. The `Builder` provides both declarative (JSON-based) and imperative (method-based) interfaces for constructing manifests.


It's a little bit like the Signer, they work together eventually.

tmathern · 2025-11-19T03:42:07Z

sdk/src/README.md

+
+- Assemble manifest definitions from ingredients, assertions, and resources
+- Coordinate with signers to create cryptographic signatures
+- Embed signed manifests into assets via asset handlers


So we have multiple vocabulary options here ;). Maybe we need a glossary at the top..

tmathern · 2025-11-19T03:43:23Z

sdk/src/README.md

+- [`status_tracker/`](#status_tracker)
+- [`asset_io.rs`](#asset_iors)
+
+#### Public type exports


Maybe we should just keep the ones that are stable, and exposed in the other SDKs?
Reader, Builder, Signer for instance are good candidates.

tmathern · 2025-11-19T03:45:29Z

sdk/src/README.md

+
+Defines the `Signer` and `AsyncSigner` traits that abstract over different signing implementations. This allows the SDK to work with various signing mechanisms (local keys, HSMs, remote services, etc.).
+
+##### Key responsibilities


Isn't that Coordinate with timestamp authorities? Or do you mean more details?

tmathern · 2025-11-19T03:45:53Z

sdk/src/README.md

+
+- Wrap callback functions as `Signer` trait
+- Support custom signing logic
+- Enable HSM and remote signing workflows


tmathern · 2025-11-19T03:46:08Z

sdk/src/README.md

+- Validate certificate chains against trust anchors
+- Verify timestamp tokens
+- Check OCSP responses
+- Apply trust policies and EKU requirements


tmathern · 2025-11-19T03:47:19Z

sdk/src/README.md

+
+### Specialized modules
+
+#### [dynamic_assertion.rs](dynamic_assertion.rs)


Isn't that a key module? Eg. to add CAWG data on signing?

tmathern · 2025-11-19T03:47:51Z

sdk/src/README.md

+
+#### [settings/](settings/)
+
+SDK-wide configuration system using thread-local settings.


Suggested change

SDK-wide configuration system using thread-local settings.

SDK-wide configuration system using *thread-local* settings.

It needs the emphasis, currently.

docs: Describe top-level architecture of SDK

5bec301

scouten-adobe self-assigned this Nov 14, 2025

scouten-adobe added 3 commits November 13, 2025 17:26

Refine presentation style

004d79e

Use intra-document links where feasible

35a2dbf

Merge branch 'main' into scouten/doc-top-level-architecture

8e1b487

scouten-adobe marked this pull request as ready for review November 14, 2025 01:39

scouten-adobe mentioned this pull request Nov 14, 2025

docs: Create overview of core SDK architecture #1585

Closed

scouten-adobe requested review from gpeacock, mauricefisher64, ok-nick and tmathern November 14, 2025 01:43

tmathern reviewed Nov 18, 2025

View reviewed changes

ok-nick reviewed Nov 18, 2025

View reviewed changes

tmathern reviewed Nov 19, 2025

View reviewed changes


		## Architectural overview

		The SDK follows a layered architecture that separates concerns between user-facing APIs, data models, storage, asset I/O, cryptography, and validation.


		##### Key responsibilities

		- Extract JUMBF manifest stores from assets


		##### Key responsibilities

		- Define `ValidationState` enum (Invalid, Valid, Trusted)


		The SDK follows a layered architecture that separates concerns between user-facing APIs, data models, storage, asset I/O, cryptography, and validation.

		```mermaid


		The outermost layer provides high-level APIs for common workflows.

		#### `Builder` ([builder.rs](builder.rs))


		#### `Builder` ([builder.rs](builder.rs))

		Creates and signs C2PA manifests. The `Builder` provides both declarative (JSON-based) and imperative (method-based) interfaces for constructing manifests.


		Defines traits for asset I/O operations. These traits abstract over different asset formats, allowing the SDK to handle JPEG, PNG, MP4, and other formats uniformly.

		##### Key traits


		Defines the `Signer` and `AsyncSigner` traits that abstract over different signing implementations. This allows the SDK to work with various signing mechanisms (local keys, HSMs, remote services, etc.).

		##### Key responsibilities


		### Specialized modules

		#### [dynamic_assertion.rs](dynamic_assertion.rs)


		#### [settings/](settings/)

		SDK-wide configuration system using thread-local settings.

	SDK-wide configuration system using thread-local settings.
	SDK-wide configuration system using thread-local settings.

docs: Describe top-level architecture of SDK #1599

Are you sure you want to change the base?

docs: Describe top-level architecture of SDK #1599

Uh oh!

Conversation

scouten-adobe commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

codspeed-hq bot commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging #1599 will not alter performance

Summary

Footnotes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

scouten-adobe commented Nov 14, 2025 •

edited

Loading

codecov bot commented Nov 14, 2025 •

edited

Loading

codspeed-hq bot commented Nov 14, 2025 •

edited

Loading