The system in its world

Product

Architecture

How the product is put together, drawn for the customer: the system in its world, its parts, its modules, how data moves, where it runs and one request step by step.

Drawn for the customer: each diagram shows what moves between the parts, named on its arrows. Each part carries the mark of the technology it is built with; a technology without a mark shows its initials.

The system in its world

The product, the people who use it and the systems around it.

STS dictionaryand its approval:not part of the demoEmail, partner APIno channel to realsuppliersSuppliers’ own systemssuch as the MMSBI or AI toolsfed by the export,outside the demoPresenterplays every party in turn;nobody signs inVVelmora Battery WorksCustomer —the sustainability leadSTS Exchangeone web application:every party’s screensClaudeAI serviceClaude, called liveduring the sittingSuppliers —each on its own screenQQuillara LithiummineBBrisemont RefiningrefinerFFerrovane Freightcarrierswitches the acting partysetup, decisions,questionslabelled dataand answersthe requestthe responsedocumentsetup input, documents,questionsexample, transactions,answersthe export fileCSV · Excel · JSONnonenothing collected

STS Exchange is one web application. The presenter plays the customer and each of the three suppliers in turn with an always-visible switch — nobody signs in. The only outside service it relies on is the AI service, Claude; the suppliers’ own systems, the BI or AI tools and any channel to real suppliers stay outside, and the export file is how data leaves.

  • The product
  • A party, in its color, or the presenter
  • A service it relies on, with its mark
  • Not part of the system
  • What moves, named on the arrow
  • No connection

Its parts

The parts the product is made of — the web app, the API, the database, the file store, the background jobs, and Claude outside — each with its technology, and how they talk.

STS Exchangethe productNext.jsReactWeb appevery party’s screens; it only showsVCustomer’s screenssetup, chain, review,queries, exportQBFSupplier screensthe request, the upload,the status and decisionPresenter’s switchthe acting party,start overNext.jsNode.jsAPINext.js route handlers on Node.jsevery rule is checked here, whateverthe screen allows: the label’s checks,the citations, one review per transactionPostgreSQLDrizzleDatabasePostgreSQL, Drizzlethe walkthrough’s state, keptthrough a reload, until a newsetup or a start-overS3-compatible storageS3File storeS3-compatiblethe suppliers’ documents, eachwith its supplier’s responsenever to a customerpg-bosspgBackground jobspg-bossthe queue, kept in PostgreSQL:a running interpretation goeson through a reloadExcelJSXLExport fileCSV · Excel · JSONExcel written by ExcelJSfor BI or AI outsideClaudeAI serviceClaudegenerates the example,reads the documents,answers the questionscalled by the server onlysetup, uploads, decisionswhat each screen showsreads, writeskeeps, serves the documentqueues the workthe labelleddatacallsthe resultthe document, to readthe values read, the example

The web app, built with Next.js and React, only shows; the API — Next.js route handlers on Node.js — checks every rule, whatever the screen allows. The walkthrough’s state is kept in PostgreSQL through a reload until a new setup or a start-over, and a running interpretation goes on as a background job. A supplier’s document is kept in the file store and shown on that supplier’s screen only: Claude reads it, the customer never sees it.

  • The product
  • A part of the product, with the mark of its technology
  • No official mark: initials
  • A service outside, called by the server only
  • A file that goes out
  • What passes, named on the arrow
  • The answer to a call
  • Never shown there

Modules

The six modules of the product and what each gives the others.

SETClaudein the demoSetupThe prepared example: industry,company names, the AI’s scenario;the presenter’s switch, start-overMain actor: customer, presenterLABin the demoLabel and requestThe STS label — six fields, eightquestions; the request to eachsupplier; the chain and roll-upMain actor: customerQRYClaudein the demoQueries and exportPlain-language questions answeredwith the transactions behind eachnumber; CSV, Excel or JSONMain actor: customerRSPin the demoSupplier responseEach supplier’s own screen: therequest, the upload of its document,the customer’s decisionMain actor: each of the three suppliersINTClaudein the demoInterpretationThe AI reads a response into oneSTS transaction, linked to itsparent — or puts it in errorMain actor: the AI, on the uploadREVin the demoReviewThe labelled values and context,never the file; accept, or requestclarification with a noteMain actor: customerparties, product,containerthe chain andeach step’s stateprepareddocumentsthe requestlabel fields,the supplier’s placethe transactionand its statusthe uploadeddocumenta transaction,or an errorreview statusreview statusaccepted, or clarification requested — with the note

Six modules along the walkthrough: Setup prepares the example, Label and request asks the suppliers, Supplier response takes their documents, Interpretation turns each into an STS transaction, Review settles it, and Queries and export answers from the chain. All six are in the demo — the demo is the whole build. Each arrow says what one module hands to another.

  • The module’s code
  • In the demo
  • Calls the AI service, Claude
  • What passes, named on the arrow

How data moves

From the setup to the cited answer and the export, with the line the original file never crosses.

Supplier’s sideits own screenSetup inputindustry,company namesPostgreSQLin the databasePrepared exampleparties, container, documents;the AI’s, when changedPostgreSQLin the databaseSTS label6 mandatory fields,8 questionsPostgreSQLin the databaseRequestsone to eachsupplierPostgreSQLin the databasethe request, addressed to each supplierResponse documentthe supplier’s ownformat, e.g. PDFS3-compatible storageS3with its responseClaudeInterpretationClaude readsthe document;values come outSTS transactionreview pendingor in error, withthe missing items namedor failed — the fileis uploaded againPostgreSQLin the databaseReviewaccept, or requestclarificationPostgreSQLin the databaseChain and roll-upthe three transactions,in chain orderPostgreSQLin the databaseAnswerscite transactionsPostgreSQLin the databaseExcelJSXLExportCSV · Excel · JSONa file, out of the demostatus, its own label read only, outcome and note — to the supplierPrivacy line: nothing to its right ever shows the original file

Data moves from two setup inputs — the industry and the company names — to an answer that cites its transactions, and out as an export file. The supplier’s document stays on the supplier’s side of the red line: the AI reads it there, and only the labelled values cross. Nothing to the right of the line — the transaction, the review, the chain, the answers, the export — ever shows the original file.

  • The privacy line
  • Kept in the database, PostgreSQL
  • No official mark: initials — S3 for the file store, XL for ExcelJS
  • The AI service, Claude
  • Becomes the next
  • Status back to the supplier

Where it runs

One installation in one region, how a change gets there, and what the demo does not require.

GitHub ActionsGitHub Actionschecks every change,builds one imagethe imageDockerDocker imagethe same on a laptopand on the hosta releaseOn a developer’s machineMinIOMinIO stands infor the S3 storeLarge screenor screen sharePresenter’s laptopa current desktop browsershown onClaudeAI serviceClaude, called liveNext.jsReactNode.jsApplicationthe web app and the API, one imageDockerpg-bosspgBackground jobspg-boss: the queue keptin PostgreSQLPostgreSQLManaged PostgreSQLthe walkthrough’s state, kept untila new setup or a start-overS3-compatible storageS3S3-compatible storagethe suppliers’ documents, eachwith its responseHosting in one region1ROne installation, in one regionprovider chosen when the work is cut; no hosting or data-location requirementHTTPScalled from the regionthe statethe documentsNo backup or recovery requirementfor the demoNo email or sign-in servicesends nothing, no sign-inOne presenter at a timeno accounts

GitHub Actions checks every change and builds one Docker image, the same on a laptop and on the host. It runs as one installation in one region — the provider is chosen when the work is cut — with a managed PostgreSQL and S3-compatible storage, and Claude is called from there. The presenter opens it in a desktop browser, shown on a large screen or by screen share. The demo needs no backups or recovery, sends no email and has no sign-in.

  • One installation, in one region
  • A part of the product, with the mark of its technology
  • No official mark: initials
  • A service outside, called live
  • Only on a developer’s machine
  • Stated plainly: what the demo does not need

One request

A supplier’s upload through the parts, step by step.

FNext.jsReactFerrovaneits own screenNext.jsNode.jsAPIevery ruleS3-compatible storageS3File storeS3-compatiblepg-bosspgBackground jobspg-bossClaudeAI serviceClaude, called livePostgreSQLDrizzleDatabasePostgreSQLVNext.jsReactVelmorathe chain view1uploads the document2kept with the response2status: submitted3interpretation queued3chain step: being interpreted4document, label fields,Ferrovane’s placethe values read5the values, to checkchecks fields, unitsand method flags6STS-SH-0001 kept,review pending7interpreted;its label, read only8the labelled values, in placenever the file

Ferrovane Freight answers the request, followed through the parts: the web app, the API, the file store, a background job, Claude and the database. The document never leaves Ferrovane’s side: the customer sees the chain change in place and, in the review, the labelled values only.

  • A part, over time, with the mark of its technology
  • No official mark: initials
  • A step, numbered as in the list
  • A call from one part to another
  • The answer to a call
  • Never shown there
  1. The presenter, acting as Ferrovane Freight, uploads its document on the request screen; the web app sends it to the API.
  2. The API keeps the document in the file store with Ferrovane’s response; in the database its status reads submitted.
  3. The API queues the interpretation as a background job; the customer’s chain step for Ferrovane reads being interpreted.
  4. The job sends Claude the document, the label’s fields and Ferrovane’s place: parent STS-PR-0001, transportation, Category 4.
  5. The job hands Claude’s values to the API, which checks every mandatory field, its unit and the method flag of each emission figure.
  6. The database keeps STS-SH-0001, parent STS-PR-0001, review pending.
  7. Ferrovane’s screen shows interpreted, and Ferrovane reads its own label, read only; it confirms nothing before the review.
  8. The customer’s chain view changes in place; the review shows the labelled values, never the file.

In this section

Technology stack

The technologies the product is built with, by layer: each with its official mark, one line of what it is for, and a link to its site.