Jira progress: loading…

ECO

E-C-O^™ Numbers & Client Roles

To understand the framework it is important to understand the ZAYAZ Clients Roles described in this document. Some user roles are specific users only in a specific module, like in the White Labelling where you can find “childs” that are non-paying users like the “Users” and “Gamers” and the “Manager” which is linked to the “Admin” as a client of the “Admin”.

All clients receive a unique 12-digit non-sequential E-C-O^™ Number in the form:

ECO-196-123-456-789-34

with the exception of the Special User Roles where the first three digits are letters (e.g. GOV-033-003-303-35 or AUD-123-324-622-73). In all E-C-O^™ Numbers, the first three digits are the numeric format of the ISO 3166 international standard country code. Viroway Ltd. would be: ECO-196–000-000-000. The E-C-O™ Number is used as a user id and for sustainability tracking and data reporting. For testing purposes use ZYZ-xxx-xxx-xxx-xxx-cc (first three digits the country code and the remaining digits, dummy numbers, except the last two digits which are checksum digits)

1. Key Specifications of the E-C-O^™ Number

E-C-O^™ Number Assignment: Automatically assign a unique E-C-O™ Number to each supplier upon registration. This number will act as an identifier across the platform for report generation and supplier validation.
Public Data Access: Customers should be able to query a supplier’s E-C-O™ Number to view basic public sustainability data (based on the supplier’s reporting tier).
Real-Time Updates: Allow suppliers to update their data, which will automatically trigger recalculations of their ECO-Score^™ and notify relevant stakeholders of any changes.
User Database: The E-C-O™ Number database is the main hub for storing all company and ESG data.

2. The ZAYAZ Clients Roles are:

Super Admin: Viroway Ltd’s personnel responsible for ZAYAZ.
Admin: Viroway’s personnel working on maintenance and updates, etc on a specific ZAYAZ module. Access controlled by Super Admins.
WL-Admin: Viroway’s White Labelling Clients responsible for a number of Users (clients of our White Labelling Partners). Access controlled by Super Admins.
Stakeholder: Non-registered users that would typically check out an client using their E-C-O^™ Number.
ZAYAZ Clients (also referred to as only “Clients” through out the document): Viroway's clients. Mainly suppliers to our White Labelling Partners' clients. Ideally most businesses on planet Earth. Each one will be given a uniques E-C-O^™ Number. A ZAYAZ Clients can be a supplier, manufacturer, distributor, importer, user etc.

2.1. Special User Roles

Government Bodies and Non Government Organisations (NGOs): Bodies that use the information for non-profit reporting-purposes, similar to a government body receiving financial information. These organisations will be verified before given an E-C-O^™ Number and will then get either a GOV-033-003-303-35 number or a NGO-010-422-773-66 number.
Auditors / Verifiers: Classification, certification and technical assurance and advisory companies that are authorised to verify or audit the reporting information. This could be companies like DNV Group AS, ERM.com etc. or simpler forms of verifiers like auditors or accounting firms. All verifiers will be checked out before being approved as “Auditor / Verifiers” and given a specific E-C-O™ Number code starting with “AUD” e.g. AUD-196-123-456-789-73.
Energy Suppliers: Energy suppliers (on the grid) should be given an ESU code e.g. ESU-176-255-564.
Educational Purposes: Educational lienses should be given an EDU code e.g. EDU-196-123-321.
Financial Institutions: Financial lienses should be given a FIN code e.g. FIN-196-123-321.

If some parts of ZAYAZ involve external users without an E-C-O^™ Number yet, they should be issued a temporary E-C-O ID (e.g., ZYZ-196-123-456-789-55).

E-C-O^™ Number Types

ECO-196-123-456-789-34

2.2. Example of a Module Specific User Setup: Waste Management Users

Super Admin:: Viroway Ltd’s personnel responsible for ZAYAZ’s operations.
Admin (ZAYAZ Clients): Viroway's clients. Typically large facility management/cleaning companies with many clients.
Managers (ZAYAZ Clients): Admin’s clients who subscribe to the ZAYAZ solution.
Users: Admin’s employees using ZAYAZ operational applications.
Gamers: Employees of Managers with read-only access to applicable gamification views.

2.3. Business Units and Business Projects

E-B-U and E-B-P are governed E-C-O identity-family scopes — not child identifiers and not independent UOM Numbers.

The identity namespaces have distinct responsibilities:

ECO — Eco Organization
      Legal / reporting / governed organization identity

EBU — Eco Business Unit
      Organizational / management / operational attribution scope

EBP — Eco Business Project
      Project / programme / engagement / investment attribution scope

UOM Number
      Independently issued physical, operational or Resource Point object identity

The canonical recurring field for ECO, EBU and EBP is eco_number. UOM MUST NOT mint a duplicate uom_number merely to place an ECO, EBU or EBP in organizational context.

2.3.1. Stable identity, contextual classification

Examples:

ECO-196-000-000-123   Viroway Ltd
EBU-196-000-000-041   ZAYAZ Product Development
EBU-196-000-000-042   Sales & Partnerships
EBP-196-000-000-317   Pergamum Pulse v1 Launch

The identifier MUST NOT encode a parent hierarchy. Restructuring changes relationships, not identity.

An E-C-O-backed graph participant MAY carry governed UOM classification metadata without acquiring a UOM Number:

eco_number: EBU-196-000-000-041
uom_type: COST_CENTER
uom_category_code: CST

uom_type and uom_category_code are classification, not identity. Their allowed bindings are governed by config/system/uom-number-types.json.

2.3.2. Why E-B-U is needed

ERP and accounting systems expose organizational scopes such as company codes, controlling areas, cost centers, profit centers, departments, classes and dimensions. They do not all mean legal entity.

ACF therefore resolves source semantics according to meaning:

legal/reporting organization -> ECO
business unit / division / department / cost center / profit center -> EBU
project / WBS / programme -> EBP
physical site / facility / Resource Point -> UOM Number

For example:

SAP Cost Center 4710
       ↓
source semantic resolution
       ↓
EBU-196-000-000-041
       ↓
uom_type: COST_CENTER
uom_category_code: CST

The source-system identifier remains a mapping/provenance reference rather than becoming the canonical ZAYAZ identity.

2.3.3. E-B-P as a project scope

Projects naturally aggregate purchases, travel, employee time, suppliers, assets, energy, logistics, waste, capital goods, budgets, targets, emissions and evidence. ACF SHOULD resolve applicable project/WBS identifiers from source systems into EBP rather than propagate incompatible connector-specific project identities.

An EBP may span multiple organizations while retaining one immutable project identity.

2.3.4. Consolidation invariant

Neither EBU nor EBP automatically creates additional emissions in consolidation. They are attribution scopes unless an explicit governed calculation scope says otherwise.

inventory_role:
  type: attributed
  consolidation_behavior: included_in_parent

A genuinely independent inventory requires explicit semantics:

inventory_role:
  type: primary_inventory
  consolidation_behavior: independently_consolidatable

Therefore an ECO inventory and EBU/EBP allocations derived from that inventory MUST NOT be summed merely because each has a footprint value. Consolidation engines must resolve scope role and allocation lineage before aggregation.

2.3.5. UOM is the canonical context graph

E-C-O Numbers govern identity. UOM governs organizational and operational graph topology. Section 2.3 does not define a parallel E-C-O relationship graph or an independent relationship vocabulary.

ECO, EBU and EBP may participate in UOM relationships alongside UOM-owned objects. Each relationship assertion uses neutral endpoints plus a governed predicate:

relationship_id: rel-000000001
object_a: EBU-196-000-000-041
uom_relationship: OPERATES
object_b: FAC-196-123-456-789-34
effective_from: 2026-01-01T00:00:00Z
effective_to: null

object_a and object_b are neutral storage coordinates. They do not imply parent/child, source/target or owner/owned semantics. Meaning comes from uom_relationship, governed by config/system/uom-relationship-types.json.

For cross-company projects, use the applicable governed UOM predicates rather than project-local relationship names. For example, project ownership may use OWNED_BY and participation may use a governed participation predicate once that predicate is registered. No implementation may invent project_owner, project_participant, reports_to, executes, finances, or another relationship value locally. A missing semantic is a registry-governance change, not permission to create a parallel vocabulary.

Allocation percentages are calculation/accounting semantics associated with the relevant attribution or allocation record. They are not encoded into identity and should not be inferred solely from graph topology.

2.3.6. Resulting architecture

              GOVERNED IDENTITY
                    │
        ┌───────────┴───────────┐
        │                       │
 E-C-O identity family      UOM Numbers
 ECO / EBU / EBP / ...      FAC / BLD / RSP / ...
        │                       │
        └───────────┬───────────┘
                    │
             UOM context graph
                    │
      neutral endpoints + governed predicate
                    │
     effective period + provenance/evidence

The responsibility boundary is:

E-C-O family -> organizational/business scope identity
UOM Number   -> independent UOM-owned object identity
UOM          -> contextual graph topology and relationship semantics
ZPDV         -> recurring physical field semantics
ACF          -> source semantic resolution and mappings
Computation  -> allocation, inventory-role and consolidation behavior

This preserves stable identity through restructurings, supports shared facilities and cross-company projects, and prevents identity, graph topology and consolidation semantics from being conflated.

3. ZAYAZ Platform — Official user_id Assignment Policy

The user_id is a globally unique identifier assigned to each individual user within the ZAYAZ platform. It:

Ensures traceability at both company (client) and user levels.
Supports telemetry tracking, security auditing, and data analysis.
Is designed to scale to tens of millions of clients and hundreds of millions of users without conflict.

A strong identity structure is critical for ZAYAZ’s long-term scalability and AI intelligence.

3.1. user_id Format Specification

Component	Description	Example
usr	Fixed prefix indicating user type	usr
normalizedclientid	Full client E-C-O Number , normalized (no dashes, lowercase)	eco196987654321
serialnumber	Zero-padded 8-digit user serial per client	00000001, 00000235, 00012345

Full Example:

usr-eco196987654321-00000001

3.2. Normalization Rules for normalizedclientid

Step	Action
1.	Take official E-C-O Number (exclude the two checksum numbers at the end) (e.g., eco-196-987-654-321).
2.	Remove all dashes -.
3.	Keep everything lowercase.
4.	Final normalized client prefix: eco196987654321.

Standardized format guarantees no ID collision across the entire ZAYAZ platform.

3.3. Serial Number Assignment

Rule	Description
Per client	Serial numbers are unique within each client.
Start at 0000001	The first user registered for a client starts at 00000001.
Zero-padded	Always 8 digits, even for early clients (e.g., usr-eco123456789-00000001).
Sequential or Random	Sequential is preferred (simpler and more auditable). Random optional if future privacy requirements emerge.

3.4. Uniqueness Guarantee

The ZAYAZ User Management Service must guarantee uniqueness by:

Checking the latest serial number assigned for each normalizedclientid.
Incrementing the serial atomically (transaction-safe).
Never reusing or recycling user_ids even if users are deleted.

3.5. Usage in Telemetry, APIs, and Internal Systems

Context	Required?
Telemetry Events (SDK)	✅ Mandatory field
API Payloads involving users	✅ Mandatory field
Database Storage (user tables)	✅ Mandatory primary or foreign key
Audit Trails and Security Logs	✅ Mandatory field
Analytics, AI, Reporting	✅ Mandatory field

user_id is a core primary key for all user-facing and system-facing interactions.

3.6. Security and Privacy

user_id does not contain any personally identifiable information (PII).
user_id alone cannot reveal a user’s name, email, phone number, or sensitive data.
ZAYAZ complies with GDPR, CCPA, and similar data protection standards regarding user tracking.

4. Simple SQL Example for user_id Generation in ZAYAZ

4.1. Assumptions

Item	Description
users table	Stores all registered users
normalized_eco_number	Field storing the normalized E-C-O™ Number (e.g., eco123456789)
user_serial	Integer auto-incremented per client
user_id	Final constructed ID `(usr-{normalizedclientid}-{serial})`

4.2. Users Table Structure (simplified)

users.sqlGitHub ↗
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    normalized_eco_number VARCHAR(20) NOT NULL,
    user_serial BIGINT NOT NULL,
    user_id VARCHAR(40) UNIQUE NOT NULL,
    user_name VARCHAR(255), -- Optional (not in user_id)
    email VARCHAR(255), -- Optional
    created_at TIMESTAMP DEFAULT NOW()
);

We store:

normalized_eco_number
user_serial (simple integer per client)
user_id (final unique ID string)

4.3. Transactional Insert Example

Here’s how a new user would be created safely:

users-example.sqlGitHub ↗
SELECT COALESCE(MAX(user_serial), 0) + 1
INTO TEMP serial_to_assign
FROM users
WHERE normalized_eco_number = 'eco196123456789';

-- 2. Insert the new user with generated serial
INSERT INTO users (normalized_eco_number, user_serial, user_id, user_name, email)
VALUES (
    'eco196123456789',
    (SELECT * FROM serial_to_assign),
    CONCAT('usr-', 'eco196123456789', '-', LPAD((SELECT * FROM serial_to_assign)::TEXT, 7, '0')),
    'Jane Doe',
    'jane.doe@example.com'
);

COMMIT;

This guarantees:

Serial numbers are unique per client.
User IDs are consistently formatted (usr-eco197123456789-0000001).
Full atomicity — no risk of collision even if two users are registered simultaneously.

4.4. Key Functions Used

Function	Purpose
MAX() + COALESCE()	Get next available serial number
LPAD(text, length, padstring)	Left-pad serial with zeros to always get 8 digits
CONCAT()	Assemble final `user_id`

Production Notes

Note	Reason
Always wrap in BEGIN/COMMIT transaction	Prevents race conditions
Use a unique constraint on user_id	Protects against rare race edge cases
Optionally optimize with per-client serial_sequences	Advanced scaling for billions of users

GitHub Repo Request for Change (RFC)

1. Key Specifications of the E-C-O™ Number​

2. The ZAYAZ Clients Roles are:​

2.1. Special User Roles​

2.2. Example of a Module Specific User Setup: Waste Management Users​

2.3. Business Units and Business Projects​

2.3.1. Stable identity, contextual classification​

2.3.2. Why E-B-U is needed​

2.3.3. E-B-P as a project scope​

2.3.4. Consolidation invariant​

2.3.5. UOM is the canonical context graph​

2.3.6. Resulting architecture​

3. ZAYAZ Platform — Official user_id Assignment Policy​

3.1. user_id Format Specification​

3.2. Normalization Rules for normalizedclientid​

3.3. Serial Number Assignment​

3.4. Uniqueness Guarantee​

3.5. Usage in Telemetry, APIs, and Internal Systems​

3.6. Security and Privacy​

4. Simple SQL Example for user_id Generation in ZAYAZ​

4.1. Assumptions​

4.2. Users Table Structure (simplified)​

4.3. Transactional Insert Example​

4.4. Key Functions Used​