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 E-C-O^™ Number in the form:

ECO-196-123-456-789

with the exception of the Special User Roles where the first three digits are letters (e.g. GOV-123-456-789 or VER-123-456-789). 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 (first three digits the country code and the remaining digits, dummy numbers)

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.

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.

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-196–412-123-456 number or a NGO-196–321-987-654 number.
• 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 “Verifiers” and given a specific E-C-O™ Number code starting with “VER” e.g. VER-196-123-456-789. If a company is seeking out a verifier, a list with it’s qualifications and in what areas it can be used as a qualified “Verifier” will appear.
• Energy Suppliers: Energy suppliers (on the grid) should be given a ESU code e.g. ESU-176-255-564.
• Educational Purposes: Educational lienses should be given a EDU code e.g. EDU-196-123-321.

If some parts of ZAYAZ involve external users without an E-C-O^™ Number yet (e.g., potential clients filling early demo forms), they should be issued a temporary E-C-O ID (e.g., eco-tmp-xyz-123).

E-C-O^™ Number Types

Client

ECO-196-123-456-789

Verifier

VER-123-324-622

Government

GOV-033-003-303

NGO

NGO-010-422-773

Energy Supplier

ESU-176-255-564

Education

EDU-196-123-321

Example of a Module Specific User Setup: Waste Management Users

• Super Admin:: Viroway Ltd’s personnel responsible for ZAYAZ’s operations. Viroway sell licenses to their partners/clients that allow the clients to sell ZAYAZ solutions to their clients (Admins).
• Admin (ZAYAZ Clients): Viroway's clients. Typically large facility management/cleaning companies with hundreds, thousands or hundreds of thousands of clients they clean for every day. The Admin’s cleaners, which is responsible for taking pictures of the waste bins (and later chemicals etc) are called “Users”. Admins sell reporting solutions to their clients (Managers).
• Managers (ZAYAZ Clients): Admin’s clients who subscribe to the ZAYAZ solution take a significant step toward reducing landfill waste, improving waste sorting, and lowering greenhouse gas emissions. Additionally, they receive comprehensive, finalized reports that can be shared with their Board of Directors, submitted to government or NGO bodies, or used internally for gamification or educational purposes. This not only saves managers time and money but essentially “pays for itself”.
• Users: Admin’s employees. The cleaners who use the ZAYAZ App to photograph waste bins and thus play a key role in enabling the backend system to perform data analysis, generate reports, and update the gamification features.
• Gamers: Employees of Managers. They can see certain parts of the Gaming Dashboard, but cannot alter or change anything.

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.

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

2. Normalization Rules for normalizedclientid

Step	Action
1.	Take official E-C-O Number (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. 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.

4. Uniqueness Guarantee

Responsibility:

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.

This ensures perfect identity traceability over time.

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.

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.

Privacy-respecting by design.

Summary: Why This user_id Policy Matters

Benefit	Impact
Scalability	Easily supports billions of users across millions of clients
Traceability	Full audit chain from event to user to company
Efficiency	Lightweight, simple to parse, and fast for DB operations
Privacy	User identity protected at the ID layer
Resilience	No risk of future ID collisions or technical debt

Final Reminder

• Every user in ZAYAZ must have a unique, immutable user_id assigned immediately upon registration.
• No system event involving a user may be emitted, stored, or processed without a valid user_id.
• This standard applies to all ZAYAZ modules, systems, services, and external integrations.

Simple SQL Example for user_id Generation in ZAYAZ

1. Assumptions

Item	Description
users table	Stores all registered users
normalized_client_id	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})

2. Users Table Structure (simplified)

users.sql

CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    normalized_client_id 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_client_id
• user_serial (simple integer per client)
• user_id (final unique ID string)

3. Transactional Insert Example

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

users-example.sql

BEGIN;

-- 1. Find the current max serial number for the client
SELECT COALESCE(MAX(user_serial), 0) + 1
INTO TEMP serial_to_assign
FROM users
WHERE normalized_client_id = 'eco196123456789';

-- 2. Insert the new user with generated serial
INSERT INTO users (normalized_client_id, user_serial, user_id, user_name, email)
VALUES (
    'eco196123456789',
    (SELECT * FROM serial_to_assign),
    CONCAT('usr-', 'eco196123456789', '-', LPAD((SELECT * FROM serial_to_assign)::TEXT, 8, '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. 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)

Visual Example After Several Inserts

user_id	normalized_client_id	user_serial
usr-eco197123456789-00000001	eco197123456789	1
usr-eco197123456789-00000002	eco197123456789	2
usr-eco197123456789-00000003	eco197123456789	3
usr-eco121987654321-00000001	eco121987654321	1

• Serial numbers are unique per client.
• No collisions across clients.