ARMO project framework

Copyright © 2021 Olexandr (Alex) Troyanovs'kyy. All Rights Reserved

Description below reflects a very practical approach to the development of the project. Its critical point is to guarantee that receivables and payables of Programme participants are synchronized on every Operation Period (OP)--as stated in paragraph A.5. of the Concept--regardless of the number of participants. So it was decided that ARMO system itself must perform all ARMO transactions and provide all participants with their updated balances of obligations.

Programme Calendar

An ARMO programme lifespan comprises one or more Programme runs, and the Programme Calendar (PC) must be properly set up for the run. A run is started by the Programme Admin and is stopped when PC generates OP record with zero T2 field. Admin must be able to adjust PC to stop the run at specified OP. It seems reasonable to have lexicographical order of OPs' Labels corresponded to chronological order of OPs.

System patrs

Every ARMO system running on some computer or computer cluster (CC) should consist of Programme Engine (PE) and optional Recognition System (RS). For every ARMO programme supported by any ARMO system its PE must provide functionality described in paragraphs B.1. - B.5. of the Concept and its RS must provide functionality described in paragraph B.6. (more details are provided here).

Program Modes

PE must support any Programme running in one of two possible modes denoted as B and D. Mode B requires all the Programme Participants to report their Balances of obligations accrued by the end of current OP at the predefined moment of time (specifically, CurrentOP.T2 - dT2 where dT2 is expected delay of Participants' data arrival to the System). Mode D allows all the Programme Participants to post their Deals to the System at any time so that PE itself will take care about assigning posted deals to proper OP.

Communication between a Participant and the System

Data exchange between a Programme participant and the System may be provided either by asynchronous messages or during an online session. Messages must be digitally signed automatically before sending and verified automatically upon receiving. If validation fails then message must be ignored by the recipient. A session must be protected by TLS protocol. These requirements mean that every ARMO system must obtain its Digital Certificate (DS). A Participant relying on sending messages to the System may also need DS (what does not preclude that Participant from communicating with the System via TLS session). Content of some messages or data transmitted during an online session is described here. An ARMO system must be setup with one or more URI so that each URI's scheme (enabled by CC's infrastructure) will tell the way of communication between the System and a Participant of a Programme supported by the System. All the System's URI must have the same host in their authority component.

Unified Programme support

ARMO system functionality (presented on the Use Case diagram and related Activity diagrams) should be the same for any Programme running on corresponding CC so that PE (and RS, if any) processes/uses Programme's data located in the corresponding repository and invokes corresponding PC. It is implied that time required to compute ARMO-results for any Programme running on the CC is less than duration of the shortest OP of that Programme. A Participant may also take part in several Programmes provided that Participant System (PS) runs on the computer [cluster] containing Programmes' data in their corresponding repositories. PS functionality is presented on the Use Case diagram and related Activity diagrams. Programme name must be passed along with other data travelling between PS and ARMO system. This diagram illustrates such multi-System/Programme environment.

ARMO realm

A set of one or more ARMO programmes supported by one or more ARMO systems allowing people, businesses and other entities to participate in any suitable Programme (one or more) in accordance to the ARMO concept may be considered as an ARMO realm specified by its name. For a realm to exist some designated computer [cluster] should have the Registry named after the realm and enable registration of ARMO systems, ARMO programmes, Recognition Parameters (RP) for a given Programme (if necessary), and Comparison Modes (CM) which characterize functionality of Recognition Systems in the realm. All the information in the Registry should be available for existing and potential participants of any registered Programme. It seems reasonable to have only one ARMO realm (named ARMOLAND) to avoid taking care about yet another registry for different realms.

Common pieces of software

Theoretically it's possible to develop one adjustable PC which will generate OPs based on the set of data or metadata created for the specific Programme run. That PC's distribution packages for popular computing platforms should contain manuals and may be uploaded to ARMOLAND for use in any Programme after downloading and installing in the Programme's repository on an ARMO system's CC. Similarly, it may be possible to develop one widely accepted PE, one widely accepted RS (which may use implemented CMs as plugins), and have their distribution packages on ARMOLAND. This Use Case diagram outlines how ARMOLAND may facilitate participation in any Programme which participants' geography is broad enough.

Local Programmes

On the other hand, there may be local Programmes running on local Systems beyond ARMOLAND. Any local PS exchanging data with local PE should enable a Teller to work on behalf of Programme participants. Registration of a Participant to a local Programme with the PS should be similar to opening a bank account. As a result a Participant should get its PPID (to be used in every Programme's deal--what means no RS needed for any local System) and possibly the credentials to access the Programme resources remotely. Also, the record LocalParticipant in the P_name repository should be populated. Any local Programme should be running in D mode. Potential participants of any local Programme should get known about it from local sources. At the same time, an Admin of any local System/Programme may get necessary installation packagers (if any) from ARMOLAND. If a PE conducting a local Programme and a PS supporting the Programme run on the same CC (what means that PE and PS reside in the same ARMOLAND repository) then both systems can access the same collection of records (specifically: Deal, Deals_Journal, ARMO_Journal, and Run_Ledger) in the Programme repository. In this situation messages DEALS, RESULTS, and PENDING_DEALS may contain P_name only and may not be digitally signed.


Certainly, every System name and every Programme name within an ARMO realm must be unique. Neither local Programmes nor local Systems supporting those programs should be registered with any ARMO realm, and their names must also be unique within their scope. So, following some naming conventions (e.g. suggested below) may be of use.

Partners Recognition

When participants of some Programme know only their own PPIDs and local IDs of their partners it is necessary to recognize those partners as other participants of the same Programme and map those partners' local IDs to corresponding participants' PPIDs. It is feasible based on the following assumptions: In this scenario every Participant should register to the Programme with the data about Participant's own common attributes and later post to the corresponding RS the same data about all non-recognized partners along with their local IDs. All the data about every Participant and all its partners should be recorded in the way which enables comparison of the same attributes' data.

Comparison Modes

Different Comparison Modes (CM) may be implemented and applied to different pieces of data represented as strings of symbols. An algorithm of every Mode must tell how to compute distance (float number) between two strings so that the more similar those strings are the lower that distance is. An implementation of a Mode's algorithm may be delivered either as a source code or as a compiled code ready to run in the corresponding environment. Fulfillments' registration is optional. Every Mode must be specified and may be implemented within any RS which declares support of the Mode in P_Setup.List_of_CMs. If the sum D of all distances computed for every pair of common attributes' data does not exceed some threshold D0 then two entities with those sets of attributes may be considered the same. So, if some Participant's partner with local ID1 appears to be another registered Participant PPID2 (with the tolerance D0) then that partner gets recognized and mapped as (ID1, PPID2). Certainly, it is necessary to define the amount and order of partners' attributes for every Programme (where partners recognition is necessary) and make that information available to any potential Participant of such Programme--what is provided in Registry's RP table.

Compound Local ID

One more point to consider with regard to partners' recognition is specifics of participants' [accounting] systems. Some of them may have multidimensional local ID. For example, in Sage 50 Accounting (2013's version) tables tCustomr and tVendor store data about two types of partners. Every table has primary key (first field LId which the same particular values may occur in both tables) and several other fields describing the same sets of partners' attributes (Name, Street address1, Street address2, City, Province/State, Country, Postal/Zip Code). In this scenario every partner's unique local ID is a pair (partner type, partner LId) what may not be the case with regard to another accounting system. So it seems reasonable to introduce a universal form of any local ID--compound local ID (CLID) as a concatenation of all key components in order of their dimensions. In this case a Participant System (PS) should generate/parse CLID values based on the KeyFields_List field of the Programme setup record.

Registration with ARMO system

Participant System (PS) must submit the following data to register a Participant's to a particular Programme: Registration procedure must check that PPID is unique (or generate such PPID if necessary) and send confirmed PPID along with CurrentOP data to the Participant. PPID of PS running any local Programme must be empty (such PS must register local participants itself). Also, the following records in the P_name repository must be populated as a result of registration: Participant (always) and Self-Partner--for any non-local Programme where partners' recognition is required. If so then ARMO system should try to recognize new Participant as local Partner of already registered Participants.

Update of participants' data

Besides, the System should enable update of a Participant registration record(s) so that a Participant may add/change its URI and PWD and modify its attributes (if any). Modified attributes should be updated in the Self-Partner record with PPID_self and all the other records with PPID_partner equal to PPID_self.

Messages description

Message Sender Recipient Message content Comment
START PE PS P_Name Programme name
CurrentOP data
EOM End of Message
NextOP data
(mode D only) Collection of Deal records
(mode B only) Collection of Run_Ledger records with OP_Label = CurrentOP.Label
Collections of the following records with their
OP_Label=CurrentOP.Label: Deals_Journal (in mode D only), ARMO_Journal, and Run_Ledger
OR notification "NoResults"
mode D only Collection of Deal_Journal records with empty OP_Label OR "NoPending"
Collection of Partner records: PPID_partner is empty & CLID is not empty
Collection of pairs (PPID, CLID)

OP data

Name Description/Comment
Records CurrentOP, NextOP Generated by Programme Calendar
Field Label Unique string within a Programme lifespan
Field T2 UTC (time to close OP). Must be converted to/from a Participant's local time
EOR End of Record

System setup data

Name Description/Comment
Record S_Setup For ARMO System on CC
Field S_name Must be unique for non-local System
Field IsLocal Yes | No
Field PE_URI_List Must be posted to ARMOLAND during registration of non-local System
Field RS_URI_List Similar to above, empty if partners' recognition is not required

Programme data on the System's site

Name Description/Comment
Record P_Setup In the System's P_name repository (for non local Programme only)
Field P_mode B | D
Field D0 Float >=0; field present only when partners' recognition is required
Field List_of_CMs List of Comparison Modes corresponding to the AttrData_List for the Programme; present only with D0 field
Record Participant In the System's P_name repository
Field PPID PK for non-local; Empty for local with only one record in the collection
Field PS_URI For sending messages to PS
Field PWD Encrypted Participant's password (Empty if not used);
List of Teller's passwords for local PS
Record Self-Partner In addition to Participant record--when partners' recognition is required
Field PPID_self Self
Field PPID_partner Empty if Partner is not recognized; always Empty for Self
Field CLID Of the Partner; Empty for Self
Field AttrData_List List of corresponding fields' data in the order described in the Registry's RP table
Record Deal Posted by PPID_self or by Teller on behalf of PPID_self
Field PPID_self Self
Field PPID_partner Partner
Field DT_amount Positive if partner is debtor, zero if partner is creditor
Field CR_amount Zero if partner is debtor, positive if partner is creditor
Field Explanation Deal's comment or Reference number
Record Deals_Journal In the System's P_name repository
Field OP_Label Empty for pending deal
Field PPID_self
Field PPID_partner
Field DT_amount To increase AR balance of Self
Field CR_amount To increase AP balance of Self
Field Explanation Deal's comment or Reference number
Record Run_Ledger In the System's P_name repository
Field OP_Label Enables history of balances
Field PPID_self
Field PPID_partner
Field AR_balance Receivables: to be paid by Partner to Self
Field AP_balance Payables: to be paid by Self to Partner
Record ARMO_Journal In the System's P_name repository
Field OP_Label Of ARMO-results computed
Field PPID_self
Field PPID_partner
Field DT_amount To decrease AP balance of Self
Field CR_amount To decrease AR balance of Self
Field Explanation List of reduced cycles' numbers in order of reductions
Record ARMO-results Generated in the System's P_name repository based on ReducedCycle data
Field PPID_self
Field PPID_partner
Field DT_amount To decrease AP balance of Self
Field CR_amount To decrease AR balance of Self
Field Explanation List of reduced cycles' numbers in order of reductions
Record GraphEdge Corresponds to Run_Ledger record with positive Self's Payable
Field Obligor Debtor' PPID, i.e. Run_Ledger.PPID_self
Field Obligee Creditor' PPID, i.e. Run_Ledger.PPID_partner
Field Amount Run_Ledger.AP_balance of the OP being closed
[Other fields] Depending on implementation of algorithm generating ReducedCycle records
Record ReducedCycle Generated in the System's P_name repository
Field CycleNumber Number in order of cycles' reductions
Field Node PPID of the cycle's node
Field AmountReduced For any edge in the cycle

Programme data on the Participant's site

Name Description/Comment
Record PS_Setup In P_name repository on PS
Field PPID Filled when registered; empty for local Programme
Field dT2 milliseconds (expected delay of Balances' arrival to the System);
>=0 for mode B, <0 for mode D (in particular for local)
Field PE_URI_List To communicate with the Programme Engine
Field RS_URI_List Empty if partners' recognition is not required
Field KeyFields_List In order used for generating/parsing CLID (present when RS_URI_List is not empty)
Field AttrFields_List Correspons Attributes_List in the Registry's RP table (present when RS_URI_List is not empty)
Record PS_Partner Present in P_name repository on PS only when partners' recognition is required
Field PPID_partner Empty if Partner is not recognized
Field CLID Of the Partner, not empty
Field AttrData_List List of corresponding fields' data in the order described in the Registry's RP table
Record LocalParticipant Present in P_name repository on PS for local Programme only
Field PPID Of local Participant
Field URI For sending messages to Participant (Empty if not used)
Field PWD Encrypted Participant's password (Empty if not used)
Field AttrData_List In predefined order--to verify a Participant by a Teller
Records Deal, Deals_Journal, ARMO_Journal, and Run_Ledger are the same as on PE site

ARMO system Use Case diagram

ARMO system setup diagram

ARMO programme Use Case diagram

ARMO programme setup diagram

Start ARMO programme

Get posted Deals/Balances

Close OP by PE

Recognize new Participant

Memorize Partners and Recognize Participants

PS Use Case diagram with regard to some Programme

Setup and Register PS to the Programme

Process Participants' deals

PS: Close OP and Process messages from PE

Process Pending Deals


ARMOLAND Use Case diagram

A hypothetical fragment of ARMOLAND

Multi System/Programme/Participation

Naming conventions and names examples

Any ARMO programme's name within ARMOLAND may have the following syntax:
<Type>_<Region>[_<suffix>] where Type reflects application domain, Region describes Programme's participants' geography, and optional suffix assures the Programme name is unique. Each part of a name better not to contain underscore symbol. Below are some possible names of ARMO Programmes. An ARMO system's name may reflect the computer cluster the System runs on.

Prototyping and implementation considerations

The MS Access application was created to prototype some ARMO system functionality (as of August 2016) on a hypothetical Programme with partners' recognition based on seven common attributes. Two simple comparison modes were implemented. In the first one the distance between to equal strings is set to 0, otherwise to 1. The second mode calculates distance as number of different strings' symbols divided by the lenght of the shorter string. Certainly, more sophisticated comparison algorithms exist and may be used (e.g. Levenshtein distance). Prototype's VBA code doesn’t depend on the number and names of attributes' fields. This example demonstrates ARMO result computed by the System prototype on some test graph.

It seems reasonable to have repositories as file folders so that every Programme's folder P_name resides within [root] folder ARMOLAND. Setup records may be just text files in the corresponding folders. Handles to DS may be included into setup files if needed. Some fields in the records/tables described above should be considered as meta-fields requiring further specification. Relational database model seems to be optimal for participants' and accounting data and for the Registry. On the other hand, utilizing a graph database (e.g. Neo4J) may be more efficient for processing graph of obligations. All files and record collections involved in the computation of ARMO results may be locked exclusively during batch processing.

Requests from PS (including those about history of reductions) should be specified and corresponding functionality should be implemented on both PE and PS.