NOTQIN Ecosystem — Modular Integration Architecture
Companion to NOTQIN Ecosystem Map. The map answers what each repo does; this doc answers how they bind — both as standalone plug-and-play products and as a single integrated suite.
The product thesis in one sentence.
Each NOTQIN product runs alone with measurable value on day one against the customer’s existing stack, AND any subset composes into a coherent platform without rewrites — because every repo speaks the same data, identity, and event contracts defined by the Morocco UNS Standard v0.1.
This is the architectural commitment that makes the sales motion work for both YNNA Steel (urgent, single wedge — CBAM only) and OCP Group (full-stack, multi-site, multi-year).
1. The dual-mode principle
Every product in the ecosystem must satisfy both of these — not one or the other:
| Mode | Customer scenario | What the product must do |
|---|---|---|
| Standalone (plug-and-play) | “We have AVEVA / Rockwell Automation / Siemens Energy PI System / a custom historian — we just want one piece of yours” | Run end-to-end with a documented adapter to the customer’s existing data plane; deliver its own value proposition without depending on any other NOTQIN repo |
| Bundled (full suite) | “We have nothing modern — give us the whole thing, day one” | Plug into the other NOTQIN products natively over the Morocco UNS Standard v0.1 contracts; share auth, identity, observability, and runbooks |
The rule. A product that only works in bundle mode is a feature, not a product. A product that only works standalone is a silo. Every repo must do both.
2. The four active repos as products
| Repo | Product name | Standalone value proposition | Bundle role |
|---|---|---|---|
notqin (Ahmed-BenAhmed/notqin) | NOTQIN Core — Industrial Data Plane | Drop-in Unified Namespace / Sparkplug B broker + edge gateway + historian. Replaces or complements existing SCADA/historian. Ships CBAM-ready signed envelopes from day one. | Source of truth for every other repo. Publishes UNS topics; everything else subscribes. |
notqin-agent-v2 / carbonPilot | NOTQIN IEIA — Energy & CBAM Agent | LLM agent that investigates energy anomalies, computes MAD/CO₂ scenarios, drafts CBAM quarterly XML. Reads from any InfluxDB-compatible historian — including the customer’s existing one. | Native consumer of NOTQIN Core’s UNS topics; emits ProofObjects to Physics for verification. |
| notqin-physics | NOTQIN Physics — Physics-Informed Verifier | Runs alongside any AI/agent stack to verify recommendations against ODE simulations, governing equations, and hard constraints. Returns PASS / WARN / BLOCK. Wraps the customer’s existing AI tools. | Verification layer for IEIA outputs before any operator-facing recommendation; gates write actions on R3+ deployments. |
| notqin-research | NOTQIN Research — R&D engine (internal) | Not a customer SKU. Academic monorepo (4 papers: NILM, Bayesian CBAM, CarbonGuard, Causal CBAM) that ships methods into the three SKUs above. | Models trained here are deployed as services consumed by IEIA and Physics. |
Three customer-facing SKUs, one internal R&D engine. Be honest about this in sales — do not pitch NOTQIN Research as a buyable product. Its value is that the SKUs above keep getting smarter without the customer paying for the research.
notqin-agent (v1) is archived at Ahmed-BenAhmed/notqin-agent — README redirects to carbonPilot.
3. Integration contracts (what makes the dual-mode real)
The reason both modes work is that all repos commit to four contracts, defined once in the standard and not re-negotiated per repo. No repo invents its own contract.
3.1 Data contract — UNS topic namespace
Defined in Morocco UNS Standard v0.1 §§3–5.
uns/ma/<region>/<enterprise>/<site>/<area>/<line>/<equipment>/<signal>
- NOTQIN Core publishes topics conforming to this path.
- IEIA subscribes to topics conforming to this path.
- Physics subscribes to the same and publishes verification results back as
.../verification/prooftopics. - Customer’s existing historian can be wrapped by an adapter that publishes into this namespace — that’s how “we already have AVEVA” stops being a blocker and becomes a 2-week adapter project.
3.2 Identity contract — mTLS + path-prefix ACL
Defined in Morocco UNS Standard v0.2 — Security & i18n §§11.3–11.4.
- Edge node CN:
<edge-node-id>.<enterprise>.uns.ma - Backend service identity via mTLS or OAuth2 client-credentials with broker-validated JWT
- ACL is derived from identity, not configured per service
This means: a customer can run Physics standalone with their own CA, OR plug it into NOTQIN Core’s CA without code changes. Identity scope changes; identity mechanism doesn’t.
3.3 Event / payload contract — signed Sparkplug B envelope
Defined in Morocco UNS Standard v0.2 §11.6.
- Every CBAM-relevant payload carries
schema_version,timestamp_utc,producer_id, and an Ed25519 signature over the metadata envelope. - ProofObjects emitted by Physics conform to a separate but versioned schema (
notqin-physics:proof@v1). - IEIA’s CBAM XML output conforms to the EU CBAM Transitional Registry XML schema — independent of the upstream stack.
3.4 Storage contract — read-only consumer pattern
- NOTQIN Core is the write owner of the production InfluxDB bucket.
- IEIA, Physics, and any downstream consumer get read-only access to a defined set of measurements.
- A standalone IEIA at a customer with AVEVA PI gets the same read-only contract via a PI → InfluxDB or PI → MQTT adapter; the IEIA code is identical.
3.5 Why these four contracts are sufficient
These four — data, identity, event, storage — cover everything two repos need to talk to each other in production. There is no fifth contract. If a repo needs something the four contracts don’t provide, the standard is updated; the repo does not invent a private side-channel.
4. Standalone deployment patterns (per-product)
Each pattern is a real sales motion. None require the others.
4.1 NOTQIN Core, standalone
Customer profile. Has PLCs, no modern UNS. Probably running AVEVA / Rockwell FactoryTalk / Siemens SIMATIC IT / a homegrown historian. Wants visibility, CBAM-readiness, or a clean foundation for future AI.
Plug points to customer stack.
- South: PLC connectors (S7, OPC UA, Modbus TCP, FINS, Sparkplug B passthrough). Hot-reloadable per notqin AGENTS.md.
- North: Grafana dashboards, optional ERP/MES bridge over REST or message queue.
What we add to their existing stack. UNS broker + edge gateway + signed CBAM envelope + Grafana. Their AVEVA stays running. We do not replace it; we add the modern data plane next to it.
Pilot exemplar. Overlay — Managem Tizert Sparkplug B — they already have Sparkplug B from a prior vendor; we layer the standard, ACL, and signed-envelope on top without rip-and-replace.
4.2 NOTQIN IEIA, standalone
Customer profile. Already has working telemetry (their own historian, or a basic InfluxDB) but no AI layer. Wants energy anomaly investigation, CBAM-XML generation, MAD/CO₂ scenario costing.
Plug points.
- Read-only adapter to customer’s historian (the
DATA_SOURCE=csv|influx|pi|historianfactory in IEIA’sbackend/tools/data_sources/). - Maintenance source plug:
MAINTENANCE_SOURCE=json|db|sap|cmms. - Scenario engine driven by
backend/config/root_causes.yaml— adding a customer-specific root cause is a YAML edit, not a code change.
What we add. A working agent that produces CBAM XML and energy-anomaly reports against their existing data. They keep their stack; they get a new outcome.
Pilot exemplar. Overlay — Sonasid CBAM Pilot — Sonasid likely has SCADA + ERP; IEIA reads from those, emits the EU-importable XML. NOTQIN Core not required.
4.3 NOTQIN Physics, standalone
Customer profile. Already running an AI / ML / digital-twin stack from another vendor and the operations team does not trust black-box recommendations. Wants verification — “prove this recommendation is physically reasonable before I act on it.”
Plug points.
- HTTP / SSE endpoint accepting
(recommendation, context)and returning a ProofObject. - Equations and constraints in
config/equations.yamlandconfig/constraints.yaml— customisable per asset class.
What we add. An independent verification gate over their existing AI. They keep their AI vendor; we sit between the AI and the operator.
Pilot exemplar. Plant with an existing predictive-maintenance vendor whose recommendations the maintenance team distrusts. Physics wraps the vendor’s API, attaches a PASS / WARN / BLOCK, and the team only acts on PASS.
4.4 Composition examples — partial bundles
Two of three is a real configuration:
| Customer wants | Bundle | Note |
|---|---|---|
| CBAM XML + verified scenario costing | IEIA + Physics | They keep their historian. Physics validates IEIA’s MAD/CO₂ calculations against governing equations before the CFO sees the number. |
| Modern data plane + agent, no verifier yet | Core + IEIA | The default starting bundle for new builds. Physics added in a later wave once the agent has a track record. |
| Modern data plane + verifier, no agent yet | Core + Physics | Used when the customer has an in-house ops team that prefers their own analysts and just wants verified physics behind dashboards. |
5. Bundled deployment — the full suite as one product
When a customer takes the full bundle, the integration is native, not glued. The four contracts above mean there is no integration project — the products discover each other through the broker.
5.1 Reference architecture (full suite)
Customer plant network
┌──────────────────────────────────────────────────────────────────┐
│ │
│ PLCs ──┐ │
│ │ S7 / OPC UA / Modbus / FINS │
│ ▼ │
│ ┌──────────────┐ │
│ │ Edge Gateway │ ── reads telemetry, signs envelopes │
│ │ (notqin) │ │
│ └──────┬───────┘ │
│ │ MQTT/TLS 1.3 + Sparkplug B + Ed25519 │
│ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ UNS Broker cluster (HiveMQ / │ │
│ │ EMQX / Mosquitto) — notqin │ │
│ └────┬──────────────┬──────────────┘ │
│ │ subscribe │ subscribe │
│ ▼ ▼ │
│ ┌─────────┐ ┌──────────┐ │
│ │ IEIA │ ───▶ Physics │ recommendation → ProofObject │
│ │ (agent) │ │ (verify) │ │
│ └────┬────┘ └────┬─────┘ │
│ │ │ │
│ └──────┬───────┘ │
│ │ verified outputs only │
│ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ Customer Portal + CBAM XML + │ │
│ │ Operator dashboards (Grafana) │ │
│ └──────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
│
│ TLS, mTLS, audited egress
▼
EU CBAM Transitional Registry (the only data egress)
5.2 Shared services in bundle mode
| Concern | Standalone | Bundle |
|---|---|---|
| Identity / PKI | Customer’s CA or self-issued | Shared CA across Core / IEIA / Physics edge identities |
| Observability | Per-product Grafana / Prometheus | Single Grafana org, single Prometheus federation, one on-call dashboard |
| Audit log | Per-product append-only log | Federated audit log indexed by producer_id |
| Runbook | Per-product runbook | Single 24/7 runbook covering all three; a single on-call rotation |
| Pricing | Per-product MAD line item | Bundle discount on the total — but each line stays itemised on the invoice |
The invoice stays modular. Even when bundled, each product is a separate line item in MAD. The customer can drop Physics in year 2 if they want, without renegotiating Core and IEIA.
6. Decoupling rules — what each repo MUST NOT depend on
This section is the daily discipline. Every PR and every wave must respect it.
| Rule | Why |
|---|---|
| No repo imports another repo’s code | Imports are coupling. Cross-repo communication is over the four contracts only. |
| No repo assumes another repo is running | If IEIA crashes, Core keeps publishing. If Core is down, Physics returns WARN: stale telemetry. No cascading failures. |
| No repo writes to another repo’s storage | Single-writer-per-store rule. IEIA does not write to Core’s bucket. |
| No repo embeds another repo’s auth tokens | Each gets its own identity. ACLs are derived from the standard. |
| No repo encodes the others’ topic schema in a private way | Topic structure lives in Morocco UNS Standard v0.1. Period. |
| No repo can be required for the customer’s PLCs to function | The UNS is a data bus, not a control bus — see Risk Mitigation Framework — Trust, PLC Safety & UNS Resilience §3. |
If a feature is tempted to break one of these rules, it goes back to design or the standard is updated — never the rule is bent quietly inside a repo.
7. Per-customer composition — current pipeline
| Account | Likely entry product | Likely additions year 2+ | Reasoning |
|---|---|---|---|
| YNNA Steel | IEIA (CBAM XML generator) standalone, reading from a minimal Core install for the metering only | Core (full plant), Physics (when scenario costing matures) | CBAM-urgent (Jan 2026 deadline). Cannot wait for full stack. Ship the wedge. See Overlay — YNNA Steel CBAM Urgent. |
| Sonasid | Core + IEIA bundle | Physics, Research-trained NILM model for sub-metering | CBAM monetisation play; multi-year intent. See Overlay — Sonasid CBAM Pilot. |
| OCP Group (Safi) | Full suite (Core + IEIA + Physics) | Multi-site replication | OCIV scale; can absorb the full architecture from day one. See Overlay — OCP Safi Pilot. |
| Managem Tizert | Core conformance audit + signed-envelope retrofit on existing Sparkplug B | IEIA later if energy intelligence becomes a budget line | They already have Sparkplug B. We layer the standard. See Overlay — Managem Tizert Sparkplug B. |
| Lesieur Cristal | Core + IEIA (energy/Scope 1-2 measurement) | Physics for verified recommendations | Adil Ousti is the named champion; energy-led entry. See Overlay — Lesieur Cristal. |
| Tanger Med | Core + IEIA (CBAM apportionment for shippers using the terminal) | Cross-tenant ACL governance (v0.3 standard) | CBAM apportionment is a multi-tenant problem the standard does not yet fully cover at the governance layer. See Overlay — Tanger Med. |
The pattern. Every account starts with one product. The four contracts make adding the second a data-plane operation, not a re-architecture.
8. Migration paths — how a customer grows from 1 product to N
Adding a NOTQIN product to a customer who already runs one is bounded work because of the contracts:
| From | Add | Bounded work |
|---|---|---|
| IEIA standalone (against customer’s historian) | + NOTQIN Core | Migrate IEIA’s read-only data source from the customer’s historian adapter to NOTQIN Core’s InfluxDB — config change + verification week. PLCs are not retouched. |
| Core standalone | + IEIA | Provision IEIA mTLS identity, subscribe to the relevant UNS prefix, deploy IEIA — 1–2 weeks. |
| Core + IEIA | + Physics | Provision Physics mTLS identity, point IEIA’s recommendation pipeline at Physics’s verify endpoint — 1 week. |
| Any bundle | + a Research-trained model (e.g. NILM disaggregation) | Deploy the trained model as a service IEIA already knows how to call — days, not weeks. |
The hard rule. Adding a product never requires rewriting an existing one. If it does, the contracts are wrong and the standard updates first.
9. Pricing implication — bundling without coupling
Because the products are independently deployable but contractually composable, the pricing follows:
- Per-product MAD line items on every quote. A customer always knows what each product costs.
- Bundle discount when ≥2 products are taken at the same time, applied as a percentage on the bundle, not folded into a single opaque line.
- Year-2+ optionality. A customer can drop or add a product at renewal without renegotiating the others.
- Migration credit. A customer who started standalone (e.g. IEIA against AVEVA) and adopts Core in year 2 gets the standalone integration cost credited toward the bundle work — incentivises them to consolidate.
This pricing only works because the architecture above holds. The moment two products become impossible to separate, the pricing collapses into “platform license,” and the door to standalone-entry customers like YNNA Steel closes.
10. Anti-patterns to refuse
These look reasonable in PR review and kill the architecture if accepted:
- A “platform” repo that all the others depend on. Looks DRY; turns the suite into a single product. The four contracts replace the platform repo.
- A shared types package imported by all repos. Acceptable only if it’s a thin code-generation target from the standard’s schema, with no logic. Otherwise it becomes the de facto platform repo.
- A shared database. Single-writer-per-store rule (§6) forbids it.
- An “internal” SDK that bundles auth, telemetry, logging. Same trap. Each repo owns its own observability; federation happens at the dashboard layer, not the SDK layer.
- Cross-repo feature flags. A flag in IEIA that gates behaviour on Physics being present is a coupling smell. The pattern instead: IEIA degrades gracefully if Physics is absent (skips the verify step), without configuration.
11. What v0.3 of the standard must add to support v2 of this architecture
(Tracked here so v1.1 of this doc updates when v0.3 lands.)
- Cross-tenant signal sharing in shared brokers (relevant for Tanger Med CBAM apportionment).
- Hardware root of trust on edge nodes (deferred from v0.2).
- Formal liability framework for R3+ writes at OCP Group scale.
- A canonical schema for ProofObjects (currently lives in
notqin-physics; should be in the standard so a third-party verifier could be swapped in).
12. Closing principle
The contracts are the product, not the code.
Any of the four repos could be rewritten in a different language or replaced by a third-party vendor — and the suite would still work, as long as the replacement honoured the four contracts. That is what “plug-and-play” means in this ecosystem. It is also what protects us from the customer who has AVEVA today and is paying us anyway: they are not buying our code; they are buying conformance to a standard their plant can adopt incrementally without locking them in.