DEV Community

Nicola Lorenzini
Nicola Lorenzini

Posted on

Building a Read-Only Comics Adapter for MyZubster: From Local Prototype to a Public-Ready Pilot

#python #docker #myzubster #local

Building a Read-Only Comics Adapter for MyZubster: From Local Prototype to a Public-Ready Pilot

Over the last few days, I’ve been working on a small but concrete experiment inside the MyZubster ecosystem: turning my N4K48 × MyZubster comic series into a structured catalog that can be queried by Zorgax.

The goal wasn't to jump directly into minting NFTs.

Instead, I wanted to build and verify the pieces that should come before that: catalog data, API access, rights status, an explicit NFT candidate, and a clean boundary between what is already working and what still needs validation.

The pilot

The project currently contains three comic panels:

  1. Dall’idea software al metaverso
  2. Il software prende forma
  3. Verso Neon Plaza

They are exposed through a read-only catalog adapter.

The first panel is currently marked as:

NFT_CANDIDATE
PROPOSED_FOR_REVIEW
rights_status: TO_VERIFY
Enter fullscreen mode Exit fullscreen mode

This distinction matters.

NFT_CANDIDATE does not mean that an NFT has been minted.

At this stage there is no contract address, token ID or transaction hash associated with the comic. Those fields remain empty until an actual on-chain operation can be performed and independently verified.

A small API for Zorgax

The pilot exposes a few deliberately simple endpoints:

GET /api/comics
GET /api/comics/{comic_id}
POST /api/zorgax/ask
Enter fullscreen mode Exit fullscreen mode

The Zorgax adapter supports four explicit actions:

gallery
detail
candidate
next_steps
Enter fullscreen mode Exit fullscreen mode

For example:

{
  "question": "Quale candidata NFT?",
  "action": "candidate"
}
Enter fullscreen mode Exit fullscreen mode

returns the proposed candidate from the catalog.

The important architectural decision here is that the adapter is read-only.

It cannot mint NFTs, modify the catalog, access wallets or execute payments.

It simply provides a controlled interface between the catalog and the assistant layer.

Testing the complete local flow

I rebuilt the environment using Docker Compose and tested the API from PowerShell.

The API container reached:

healthy
0.0.0.0:5000->5000
Enter fullscreen mode Exit fullscreen mode

Then I manually verified the main flow.

Gallery

gallery returned all three N4K48 comic panels.

Detail

detail correctly returned the complete record for:

n4k48-comic-001
Enter fullscreen mode Exit fullscreen mode

NFT candidate

candidate returned only:

n4k48-comic-001
Dall’idea software al metaverso
Enter fullscreen mode Exit fullscreen mode

with:

nft_status: NFT_CANDIDATE
selection_status: PROPOSED_FOR_REVIEW
rights_status: TO_VERIFY
transaction_hash: null
Enter fullscreen mode Exit fullscreen mode

Next steps

The adapter also correctly reports that provenance/authorizations and the public Zorgax connection still need verification, and that the service itself does not execute minting.

So the local happy path is now working:

request
   ↓
gallery
   ↓
detail
   ↓
comic asset
   ↓
candidate
   ↓
rights / on-chain status
Enter fullscreen mode Exit fullscreen mode

Preparing the adapter for a public environment

The next problem was important.

The API worked on:

http://localhost:5000
Enter fullscreen mode Exit fullscreen mode

but we don't want a public Zorgax service to depend on — or expose — my personal PC.

So I changed the adapter to accept its public base URL through an environment variable:

NICOLA_COMICS_BASE_URL
Enter fullscreen mode Exit fullscreen mode

Without that variable, the API returns relative URLs:

/api/comics/n4k48-comic-001
Enter fullscreen mode Exit fullscreen mode

With a configured public base URL, it can instead return:

https://pilot.example.org/api/comics/n4k48-comic-001
Enter fullscreen mode Exit fullscreen mode

No production URL is hardcoded into the application.

No authentication tokens or secrets are stored in the repository.

An interesting Docker issue

During the test I set:

$env:NICOLA_COMICS_BASE_URL="https://pilot.example.org"
Enter fullscreen mode Exit fullscreen mode

but the API continued returning:

"api_base_url": null
Enter fullscreen mode Exit fullscreen mode

The Python code was working correctly.

The problem was Docker Compose: the environment variable from the host wasn't being forwarded to the API container.

The fix was to explicitly pass it:

environment:
  NICOLA_COMICS_BASE_URL: "${NICOLA_COMICS_BASE_URL:-}"
Enter fullscreen mode Exit fullscreen mode

After rebuilding the containers, the same API request returned:

"api_base_url": "https://pilot.example.org"
Enter fullscreen mode Exit fullscreen mode

and:

"detail_url":
"https://pilot.example.org/api/comics/n4k48-comic-001"
Enter fullscreen mode Exit fullscreen mode

That gave us a useful intermediate verification: the adapter is still running locally, but its URL-generation behavior is ready to be configured for a separate public hosting environment.

What is verified — and what isn't

At this point we have verified:

✓ Docker deployment locally
✓ comic catalog
✓ gallery
✓ comic detail
✓ NFT candidate selection
✓ next-step reporting
✓ configurable API base URL
✓ Docker environment propagation
✓ read-only integration boundary
Enter fullscreen mode Exit fullscreen mode

Still pending:

○ real public HTTPS deployment
○ public Zorgax → pilot connection
○ hosting authentication/authorization
○ rights verification
○ on-chain transaction
○ NFT mint verification
Enter fullscreen mode Exit fullscreen mode

Keeping those two lists separate is one of the most important parts of the experiment.

A prototype shouldn't claim capabilities simply because they're part of the roadmap.

The next milestone

The next test will move the same adapter from the local environment to a reachable HTTPS endpoint.

Then the goal is to verify the complete public flow:

User request
      ↓
Public Zorgax
      ↓
Nicola Comics adapter
      ↓
Gallery
      ↓
Comic detail/card
      ↓
Published image
      ↓
NFT candidate
      ↓
Rights / verified on-chain status
Enter fullscreen mode Exit fullscreen mode

The adapter remains read-only during this phase.

Only after rights and the blockchain step have actually been completed and verified should the project move from NFT candidate to a real minted asset.

For me, that's the interesting part of this pilot: not simply putting a comic “on Web3”, but building a small, reproducible path where every transition has an explicit and verifiable state.

Nicola / N4K48

opensource #python #docker #api #web3 #ai #buildinpublic

Top comments (0)