02 Architecture

Architecture

The System architecture is built on principles borrowed from object-oriented programming (classes, methods, inheritance).

Data in the System is represented as objects and has an abstraction layer described below.

Abstraction Layer

• The unit of data storage in the system is not a row in a table, but an object. The concept of a table is replaced by an entity.

• Objects in the system are classified -- that is, distributed among classes within a given entity.

Object Definition

• An object is a physical or logical entity that can be represented as a single whole. For example: a client, an employee, a contract, an invoice, an order, a service, a transaction -- all of these are separate entities whose data is stored in the system as objects.

• An object possesses a set of characteristics: class, type, and state.

• The system's built-in access control mechanism applies to objects.

• An object is divided into two base classes -- document and reference.

• The document class has a property (field) area (organizational unit), which restricts the "document visibility scope". The reference class does not have this property, so reference objects are accessible to everyone (subject to access permissions).

  The "document visibility scope" allows data access to be segregated by departments, branches, geographic regions, or other criteria. It has a hierarchical structure where all higher-level elements can access data from lower-level elements, but not the reverse.

• Actions can be performed on an object, which trigger events in the system, which in turn can lead to changes in the object's state. All of this is part of the system's Workflow.

• An object inherits all properties and methods from its parent classes.

• The following data can be associated with an object:

  • Address -- postal/physical address information
  • Data -- arbitrary key-value data (text, JSON, XML, Base64)
  • Coordinates -- geolocation (latitude, longitude, accuracy)
  • Files -- file attachments (stored in DB, filesystem, or S3)

• Objects can be organized into:

  • Groups -- named collections of objects per owner

Entity -> Class -> Type

Entity (e.g., "object")
  +-- Class tree (inheritance, can be abstract)
        +-- "object" (abstract root)
        |   +-- "document" (abstract)
        |   |   +-- "client" (concrete)
        |   |   +-- "station" (concrete)
        |   +-- "reference" (abstract)
        |       +-- "region" (concrete)
        |       +-- "currency" (concrete)
        +-- Types per class (e.g., client has "individual", "legal")

• Entity: top-level business concept (developer-defined, immutable). Examples: object, document, reference, message, job.
• Class: hierarchical classification with inheritance (class_tree). A parent class's ACU permissions and events propagate to children. Classes marked abstract = true cannot have objects instantiated directly.
• Type: concrete subtypes within a class (e.g., class station has types base, rover). Types can be created by system users.

Platform Class Tree

The platform registers the following class hierarchy via InitEntity():

object (abstract root)
+-- reference (abstract)
|     +-- agent          -- message delivery channels (system, api, email, stream)
|     +-- form           -- dynamic forms (with field sub-table)
|     +-- program        -- PL/pgSQL stored programs
|     +-- scheduler      -- periodic job schedulers
|     +-- vendor         -- suppliers/manufacturers (service, device, car)
|     +-- version        -- API versions
|     +-- report_tree    -- report section hierarchy
|     +-- report_form    -- report input forms
|     +-- report_routine -- report generation routines
|     +-- report         -- report definitions
+-- document (abstract)
      +-- job            -- scheduled/one-time tasks (periodic, disposable)
      +-- message (abstract)
      |     +-- inbox    -- incoming messages
      |     +-- outbox   -- outgoing messages
      +-- report_ready   -- generated report outputs

Configuration projects extend this tree with their own classes. For example, a GNSS project might add client, device/station, subscription, tariff, payment, and order under the appropriate parent classes.

Object Associations

Every object in the system can have associated data stored in dedicated tables:

Association	Table	Key Fields	Purpose
Address	db.object_coordinates (for geo), external address tables	object, code, latitude, longitude	Physical/postal address and geolocation
Data	db.object_data	object, type, code	Arbitrary key-value storage (text/JSON/XML/Base64)
Coordinates	db.object_coordinates	object, code, latitude, longitude, accuracy	Geolocation with temporal validity
Files	db.object_file	object, file	File attachments with metadata (size, MIME, path)
Groups	db.object_group, db.object_group_member	group, object	Named collections for organizing objects
Links	db.object_link	object, linked, key	Object-to-object relationships with temporal validity
References	db.object_reference	object, key, reference	External string references with temporal validity

Three-Layer Access Control

The system implements three complementary access control layers:

Layer	Table	Scope	Bits	Description
ACU (Access Control by Class)	db.acu	Class + User/Group	5-bit: {a,c,s,u,d} (access, create, select, update, delete)	Controls which classes a user can see and operate on
AMU (Access Control by Method)	db.amu	Method + User/Group	3-bit: {x,v,e} (execute, visible, enable)	Controls which workflow methods a user can invoke
AOU (Access Control by Object)	db.aou	Object + User	3-bit: {s,u,d} (select, update, delete)	Controls per-object permissions for individual users

Additionally, AOM (db.aom) provides UNIX-style default masks (user/group/other) for objects, and OMA (db.oma) provides per-object method-level overrides.

Database Schemas

Schema	Purpose
db	All tables (always use db. prefix)
kernel	Core business logic functions (in search_path, no prefix needed)
api	API-facing views and CRUD functions
rest	REST endpoint dispatcher functions
oauth2	OAuth 2.0 authentication
daemon	Daemon-specific functions
report	Report generation functions