Annotations ‐ Final design - bounswe/bounswe2023group2 GitHub Wiki

Purpose

This document formulates our final decision about the use and implementation of annotations in our system.

Revision History

Name Date Reason for Change Version
The Version December 19th, 2023  A final design and implementation decision has been made 1.0

Use of Annotations

Where to use?

Annotations will be available for user entry on system entities.

  • Resource declarations
  • Need declarations. For this the UI elements (on both mobile and front end) will provide the necessary input functionality to the user.

How to use?

The annotation subsystem will be driven through a seperate Annotation Server implementation of us, which will be agnostic to our system, design or functionalities. The AS will provide the necessary annotation functionalities through API.

hypothes.is

hypothes.is is a public service providing

  • API functions to create, update, search and retriev annotatitons.
  • A Web interface to browse the annotations.
  • A "site-in-site" function to browse the urls (web pages, web application pages etc) together with the annotations on them. Click to check an example

Summary

A final formulation

Annotation Server will be a separate fastAPI application with no interference with DaRP database. In practice, effectively it will be more like a proxy for hypothes.is. Because the annotations will be stored on that frame. (Hypothes.is)

  1. The API calls to our annoserver will be unaware of the fact that the annotations are stored on hypothes.is. All calls to create, retrieve, update or delete annotations will be against annoserver (not h).

  2. The annotation related frontend calls (and calls FROM the backend code-if needed) will be to annoserver (not the regular backend).

  3. Our database will not store information about the annotations. All annotation info will be retrieved from annoserver providing specific URLs (representing the DaRP entities).

  4. Querying the annotation server will be application non-specific. The annotation server will not have any conceptual understanding of needs, resources etc. (Other than the limitations and amenities provided in the WADM standard.)

  5. The annotation server will not have access to DaRP database. (As any third party annotation server does not)

On the coding side

  1. To implement this a folder named annoserver is being created under our application code. (On the same level with backend and frontend)

  2. Annoserver will be serving on port 18000 and 18843

  3. The doocker compose configuration will be updated to include a new container.

  4. For local debugging one should run the annoserver:

uvicorn --port 18000 main:app --reload


  5. docker-compose.yaml file will be updated adding this service:

annoserver:
    build:
      context: ./annoserver
    container_name: annoserver
    hostname: annoserver
    ports:
      - "18443:8000"
      - "18000:8000"
    networks:
      - practice-network
    restart: on-failure