Skip to content

Architecture

Jump to bottom
Lui-Instruct edited this page Jul 15, 2025 · 3 revisions

Architecture Overview

Overview

The fandanGO-aria plugin is designed to facilitate interaction with ARIA’s APIs, focusing on two main domains:

  • Data Management: Namely metadata, including Buckets, Records and Fields
  • Access: Relating to the current technical evaluation and feedback functionality.

User interaction is primarily through the AriaClient, which acts as the main entry point for authentication and data management. The DataManager class is responsible for handling all data-related operations (buckets, records, fields) for a given entity. For command-line users, the CLI provides a parallel interface to these operations.

Authentication

Authentication for ARIA API requests is managed via tokens. Tokens are retrieved by calling the login method on the AriaClient class, or by running the CLI command goaria login

Token Storage Methods

Tokens are stored using a multi-method approach, in the following order of preference:

  1. Keyring: Uses the system keyring (e.g., macOS Keychain, Windows Credential Locker, etc.).
  2. Encrypted File: Uses local encryption (with a password) to store the token securely on disk.
  3. JSON File: As a fallback, stores the token in a plain JSON file in the user's home directory.

The plugin will attempt to retrieve and store tokens using all available methods, and will fall back to the next method if one fails. This makes the system robust and cross-platform.

Token Refresh

Tokens are automatically refreshed when required. The user does not need to manage token expiry or refresh logic; this is handled internally by the plugin. If the token is beyond expiry refresh time too, re-login will be required.

Login Limitations

Currently, only ARIA username/password authentication is supported. If you use ORCID or institutional login, you will need to request a username/password from the ARIA team. Support for additional authentication methods is planned for future releases.

Plugin Structure

  • AriaClient:

    The main entry point for users. Handles authentication, token management, and provides methods to create and manage data managers for specific entities.

  • DataManager:

    Manages all data objects (buckets, records, fields) for a given entity (e.g., a visit or proposal). Handles creation, retrieval, and population of these objects from the database.

    • Instantiated with an entity_id and entity_type (e.g., visit or proposal).
    • The populate method loads all related data from the database.

  • DataManagerClient:

    Handles the actual API requests to ARIA, including GraphQL queries and mutations. Used internally by DataManager.

  • CLI (Command Line Interface):

    Provides interactive commands for logging in, creating and listing data, and performing technical evaluations. The CLI mirrors the functionality available in the Python API, and uses interactive prompts to guide the user.

  • OneDataClient:

    Handles file storage and retrieval with OneData, using environment variables for configuration.

Data Flow

  1. Authentication:

    The user logs in via the Python API or CLI, and a token is retrieved and stored using the most secure available method.

  2. Entity Selection:

    The user specifies an entity (e.g., a visit or proposal) by ID and type, either via the CLI or directly in code.

  3. Data Management:

    The user creates a DataManager for the entity, which can then create, retrieve, and manage buckets, records, and fields.

    • When data is created or retrieved, the relevant classes (Bucket, Record, Field) are populated using the .populate() method, which maps API/database responses to Python objects.

  4. CLI Operations:

    The CLI provides commands for all major operations, using interactive prompts to guide the user through entity and data management.

Caveats and Future Directions

  • entity_id and entity_type must be provided manually when creating a DataManager. Future releases may streamline this process.
  • Login is limited to ARIA username/password accounts; support for other authentication methods is planned.
  • If you require direct access to lower-level API clients or need custom functionality, please contact the development team.

Clone this wiki locally