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 VER-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.
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-73. 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 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. Bank-grade access should only be granted to institutions registered in national financial institution registries. (Financial licenses are given so financial institutions can verify client's ESG status.)

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., 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. 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.

2.3. Business Units and Business Projects

E-B-U and E-B-P are governed identities — not “sub-E-C-O Numbers.”

That distinction matters.

An E-C-O Number mean an organization/entity identity. An E-B-U or E-B-P mean a scope identity that can receive data, calculations, evidence, targets, budgets and reporting attribution without pretending to be a company.

2.3.1. We define the identity family like this

E-C-O — Eco Organization
        Legal / reporting / governed organization identity

E-B-U — Eco Business Unit
        Organizational / management / operational scope

E-B-P — Eco Business Project
        Project / programme / engagement / investment scope

For example:

ECO-NOR-000123
Viroway Ltd

EBU-NOR-000041
ZAYAZ Product Development

EBU-NOR-000042
Sales & Partnerships

EBP-NOR-000317
Pergamum Pulse v1 Launch

Critically, the identifier itself should not encode the parent hierarchy.

We avoid something like:

ECO-NOR-000123-BU-04-PROJ-008

because restructurings would make the identity wrong.

Instead:

EBU-196-000-000-041

remains immutable while the relationship is versioned:

relations:
  - type: owned_by
    target: ECO-196-000-000-123
    effective_from: 2026-01-01

That is much safer.

2.3.2. Why E-B-U is needed

SAP, Microsoft Business Central, NetSuite, Quickbooks, etc demonstrated the problem perfectly.

These source objects can all exist:

SAP Company Code
SAP Controlling Area
SAP Cost Center
SAP Profit Center
SAP Plant

Business Central Company
Business Central Dimension

NetSuite Subsidiary
NetSuite Department
NetSuite Class
NetSuite Location

QuickBooks Class
QuickBooks Department

e-conomic Department
e-conomic Project

They do not all mean legal entity.

Without a separate scope identity, we would eventually be forced to choose between two bad approaches:

A. Give everything an E-C-O Number
   → falsely implies legal/organizational independence

B. Leave them as ERP-specific codes
   → prevents cross-system identity and ESG lineage

E-B-U solves that.

So:

SAP Cost Center 4710
       ↓
source semantic resolution
       ↓
EBU-196-000-000-041
       ↓
"Operations"

could then be used consistently across SAP, HR, procurement, meter data and ESG reporting.

2.3.3. E-B-P is even more relevant

Projects are one of the most natural units for environmental accounting.

E.g.:

Construction project
Customer implementation project
Property development
Infrastructure project
Film production
R&D programme
Product launch
Consulting engagement
Investment project
Plant expansion
M&A integration

Each can have:

purchases;
travel;
employees/time;
suppliers;
assets;
energy;
logistics;
waste;
capital goods;
budgets;
targets;
emissions; and
evidence.

So:

           EBP-196-000-000-317
          Pergamum Pulse Launch
                    │
       ┌────────────┼─────────────┐
       │            │             │
   Procurement    Travel       Cloud
       │            │             │
       └────────────┼─────────────┘
                    ↓
                   GHG
                    ↓
              project footprint

becomes completely natural.

And accounting systems already give us project identifiers:

SAP WBS
Business Central Project
e-conomic Project
Fortnox Project
NetSuite Project / Job
Tripletex Project

ACF can resolve all of those into E-B-P.

That is much better than allowing every connector to carry its own incompatible project identity.

2.3.4. One crucial rule

Neither E-B-U nor E-B-P should automatically create additional emissions in consolidation.

They are attribution scopes, not necessarily independent inventory scopes.

Suppose:

ECO-196-000-000-123
Total Scope 1+2 = 1,000 tCO2e

and:

EBU-197-000-000-041
Operations = 600 tCO2e

EBU-196-000-000-042
Commercial = 400 tCO2e

Then:

1,000 + 600 + 400

obviously must not become:

2,000 tCO2e

The E-B-U figures are allocations of the parent inventory.

Similarly:

EBP-196-000-000-317
Project footprint = 80 tCO2e

may already be contained inside the owning company's 1,000 tCO2e.

So every calculation needs an explicit scope role:

inventory_role:
  type: attributed
  consolidation_behavior: included_in_parent

versus something genuinely independent:

inventory_role:
  type: primary_inventory
  consolidation_behavior: independently_consolidatable

That will save us enormous trouble later.

2.3.5. Projects can also span companies

This is why we don't want E-B-P encoded as a literal child number.

Imagine:

               EBP-EU-000812
            Wind Farm Project X
                    │
        ┌───────────┼────────────┐
        │           │            │
     ECO-DEU      ECO-DNK      ECO-NOR
    Contractor    Supplier      Owner

The project has one stable identity but multiple participating E-C-O Numbers.

We need relationships such as:

relationships:
  - type: project_owner
    target: ECO-196-000-000-123

  - type: project_participant
    target: ECO-086-000-000-421

  - type: project_participant
    target: ECO-056-000-000-219

And potentially allocations:

allocation:
  - eco_number: ECO-196-000-000-123
    share: 0.60

  - eco_number: ECO-086-000-000-421
    share: 0.25

  - eco_number: ECO-056-000-000-219
    share: 0.15

Think of this as an E-C-O identity graph, not a simple parent/child tree.

2.3.6. The resulting identity architecture

This goes beneath the Accounting Connectivity Framework (ACF):

                   E-C-O IDENTITY GRAPH
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
       ECO                EBU                EBP
   Organization      Business Unit         Project
        │                  │                  │
        └──────────────────┼──────────────────┘
                           │
                    governed relations
                           │
             ┌─────────────┼─────────────┐
             │             │             │
          owns          contains      participates
          reports_to    allocates     executes
          controls      operates      finances

The graph should carry:

identity:
  id: EBP-196-000-000-317
  type: project
  status: active

relationships:
  - type: owned_by
    target: ECO-196-00-000-123

effective:
  from: 2026-02-01
  to: null

provenance:
  source: ...
  verified_by: ...

This fits the ZAYAZ governance kernel beautifully.

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

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.

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.

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.

4. Simple SQL Example for user_id Generation in ZAYAZ

4.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})`

4.2. Users Table Structure (simplified)

users.sqlGitHub ↗
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)

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_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, 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)

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.

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. We define the identity family like this​

2.3.2. Why E-B-U is needed​

2.3.3. E-B-P is even more relevant​

2.3.4. One crucial rule​

2.3.5. Projects can also span companies​

2.3.6. The resulting identity 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​