DEV Community

Nicola Lorenzini
Nicola Lorenzini

Posted on

From GitHub to a Real-World Pilot: Building N4K48 MyZubster

#webdev #docker #pythob #myzubster

From GitHub to a Real-World Pilot: Building N4K48 × MyZubster

I’m building Nicola Comics × MyZubster, a project connecting my digital identity, N4K48, three comic pages, and a small software service.

The goal is to bring my idea into the MyZubster metaverse through verifiable steps: create content, organize it in a catalog, expose it through an API, and test the experience with Zorgax.

Alongside this, I’m participating in a separate experiment: recording a free, in-person kefir handover through MyZubster.

This article covers what we built, a deployment bug we encountered, and what still needs to happen.

1. Turning an idea into a visual story

We started with three AI-assisted comic pages, preserving the N4K48 character appearance I selected:

  1. From a Software Idea to the Metaverse
  2. The Software Takes Shape
  3. Toward Neon Plaza

The pages tell the story of my development journey and future ambitions. Their illustrated interfaces are not application screenshots: some scenes depict features that remain to be developed.

👉 Explore the comic gallery on GitHub

2. Turning images into a catalog

Publishing three images is a starting point. To make them usable by software, we added a JSON catalog and an individual record for each comic.

Each entry includes:

  • an identifier and title;
  • series, episode, and description;
  • creative contribution and AI provenance;
  • a link to the image;
  • its Git content hash;
  • rights status;
  • NFT candidacy status.

The manifest lives here:

docs/nicola-comics/comics.manifest.json
Enter fullscreen mode Exit fullscreen mode

We also preserved earlier ecosystem reference images as separate entries, without automatically attributing them to me.

The first new comic is recorded as a proposed NFT candidate. Rights still require verification, and no mint has taken place.

A file hash identifies content. By itself, it does not prove ownership or blockchain registration.

3. Exposing the catalog through an API

The project uses Python and Flask. We added these endpoints:

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

The first returns the three comics created for the pilot. The second returns an individual record.

The third is a read-only adapter intended for integration with Zorgax. It supports four explicit actions:

Action Result
gallery List the comic pages
detail Retrieve a specific comic record
candidate Retrieve the proposed NFT candidate
next_steps Return guidance on the next steps

The adapter reads the catalog directly and constructs its response from that data. It does not independently interpret arbitrary natural-language questions, and these operations do not require Ollama or Qdrant.

The same catalog functionality is available through the existing AI endpoint by specifying the nicola-comics topic.

4. Running the project with Docker

On my Windows PC, from the repository directory, I ran:

git pull --ff-only origin main
docker compose up --build -d
docker compose ps
Enter fullscreen mode Exit fullscreen mode

The stack includes the API, Qdrant, and Open WebUI. However, the comic catalog adapter does not use the AI services to retrieve its records.

The first obstacle was Docker Desktop: the client was installed, but its Linux engine was not running. After starting Docker Desktop, docker info displayed the server information, and we could build the containers.

5. The bug our local tests missed

The API container reported itself as healthy, but this request failed:

Invoke-RestMethod -Uri "http://localhost:5000/api/comics"
Enter fullscreen mode Exit fullscreen mode

The response was:

{
  "error": "Catalogo fumetti temporaneamente non disponibile"
}
Enter fullscreen mode Exit fullscreen mode

That translates to “Comic catalog temporarily unavailable.”

The cause was in .dockerignore: it excluded the entire docs/ directory, which also contained the manifest required at runtime.

The catalog existed on the local filesystem, but it was never copied into the Docker image.

We removed that exclusion and added catalog and adapter requests to the automated Docker verification workflow.

After the fix:

git pull --ff-only origin main
docker compose up --build -d api
Enter fullscreen mode Exit fullscreen mode

The practical lesson: a passing health check does not necessarily verify every application feature. Our health check covered the observations endpoint, not the comic catalog.

6. Testing the catalog and adapter

To retrieve the catalog:

Invoke-RestMethod -Uri "http://localhost:5000/api/comics" |
    ConvertTo-Json -Depth 6
Enter fullscreen mode Exit fullscreen mode

On my PC, the response included:

{
  "count": 3
}
Enter fullscreen mode Exit fullscreen mode

The full response also contained titles, descriptions, links, and the status of each comic.

Next, I tested the adapter:

$body = @{
    question = "Show me Nicola's comics"
    action = "gallery"
} | ConvertTo-Json

$response = Invoke-RestMethod `
    -Uri "http://localhost:5000/api/zorgax/ask" `
    -Method Post `
    -ContentType "application/json" `
    -Body $body

$response.answer
Enter fullscreen mode Exit fullscreen mode

It returned the three catalog entries, whose stored titles are in Italian:

n4k48-comic-001 — Dall’idea software al metaverso
n4k48-comic-002 — Il software prende forma
n4k48-comic-003 — Verso Neon Plaza
Enter fullscreen mode Exit fullscreen mode

The action field selects the operation; changing the wording of question does not translate the catalog or change the selected action.

In the development environment, 19 automated tests passed, covering the new catalog alongside existing AI and observation functionality.

👉 Adapter documentation and integration instructions

7. A second pilot: an in-person kefir handover

In parallel, we are testing a MyZubster workflow involving a physical item: a free kefir donation delivered in person.

The intended sequence is:

Accept the gift
→ donor confirms the handover
→ recipient confirms receipt
→ record the completed handover digitally
Enter fullscreen mode Exit fullscreen mode

During testing, we encountered session-recognition problems and an inconsistent listing: its title displayed “Visual Laser,” while other fields classified it as kefir. These are issues to document and correct.

We also observed a useful validation rule: attempting to record the completed handover before confirming receipt caused the site to reject the operation without advancing its state.

At the time of writing, final registration of that handover has not been confirmed in our documented workflow.

The digital record captures confirmations submitted through the site. It does not automatically certify food quality or safety, and it is not equivalent to a blockchain transaction.

8. What remains before public integration

The catalog and adapter work in my local Docker environment. That does not mean the public Zorgax service is already using them.

The agreed next steps are:

  1. prepare the service for HTTPS hosting;
  2. verify the endpoints in the deployed environment;
  3. agree on configuration and access with the MyZubster team;
  4. connect Zorgax to the service;
  5. test the complete journey together, from a request to a comic record and image.

The service address must be configurable. localhost is appropriate for testing on my PC, but it cannot serve as the address for communication between public services.

What I’m learning

This project is teaching me to distinguish three layers:

  • The vision, expressed through the comic pages.
  • Working software, demonstrated through tests.
  • A public service, which requires deployment and integration.

The most concrete progress so far is turning three images into an API-accessible catalog and running it inside Docker, including fixing a real packaging error.

The next milestone is making that experience available through public Zorgax and documenting what happens during the test.

Repository: Nicola Comics / MyZubster MVP

Roadmap: Project progress

This is an experimental project under development. The visuals and part of the software work were created with AI assistance. Manual checks were performed on my PC, and the results above are described within their tested scope.

Top comments (0)