Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
144 lines (97 loc) · 4.43 KB

ARCHITECTURE.md

File metadata and controls

144 lines (97 loc) · 4.43 KB

Architecture

This is a Vue 3 app using the Vite build tool.

Contents:

  1. System
  2. Layout
  3. Helper subsystems
  4. Testing

System

The Mink system consists of:

  • Mink frontend runs in the user's web browser and presents a graphical user interface (GUI) to the services of the backend
  • Mink backend runs on a server where it manages stored data and executes data processing operations

The frontend communicates with the backend using the Mink API. The API can also be used directly from command-line or scripts.

The Mink system is connected to these other systems:

  • Sparv is a corpus processing pipeline operated by the Mink backend
  • Språkbanken Text Metadata API provides information about Sparv analyses
  • SB-Auth provides user authentication with eduGAIN to Mink and a few other services of Språkbanken Text
  • Analysed results can be installed from Mink into:
    • Korp, Språkbanken's word research platform
    • Strix, Språkbanken's text research platform
  • Newsdesk is a simple news feed storage
  • Matomo records anonymized visitor statistics

Layout

Source code

Source code lives in src/.

Code files are largely ordered into folders by topic:

APIs:
src/api/ - Mink API, Sparv, Metadata API
src/auth/ - authentication flow, SB-Auth API

UI components:
src/components/ - reusable elements like boxes and buttons
src/page/ - site-wide singular elements (header etc)

Resources:
src/corpus/ - corpus-related pages and logic
src/metadata/ - metadata-related pages and logic
src/resource/ - logic common to all resource types
src/sources/ - related to source files
src/job/ - related to running processing/installation jobs
src/exports/ - related to export files

Non-resource pages:
src/home/ - home page
src/library/ - overview of user's resources
src/user/ - user page, admin mode
src/tools/ - features not related to user's resources

Plugins:
src/i18n/ - (internationalization) translations, language switcher
src/router/ - config for vue-router
src/store/ - Pinia stores for cached backend data and app state

Helper subsystems:
src/alert/ - showing alerts and other feedback messages
src/spin/ - UI feedback about pending API requests

Directly under src/ there is:

  • Entrypoint (main.ts)
  • Vue root component (App.vue)
  • Vue plugin config
  • Reusable utility functions and types
  • General CSS rules

Developer documentation

You are reading some of it now. See README.md for a documentation table of contents.

Also see STYLE.md: User documentation.

Assets

  • Files in src/assets/ are renamed by the build process to contain content-based hashes for caching purposes
  • Files in public/ are copied directly to the build output, retaining a persistent filename

See Vite docs on Assets.

GitHub action

There is a GitHub action in .github/workflows/ci.yaml that will trigger on each push and check that the code builds. It also runs tests, see Testing below

Helper subsystems

These utilities are complex enough that they cannot each be contained in a single file.

Spin (src/spin/)

Wrap an async request with:

spin(promise, token);

Show loading animation on top of related UI elements with:

<PendingContent :on="token">[dependent content here]</PendingContent>

Alert (src/alert/)

Show an alert:

showAlert("There is no coffee");

It handles Mink backend errors specially:

api.runJob("corpus", id).catch(showAlert);

Testing

Test files should be named after the files they test, so HomeView.vue is tested by HomeView.test.ts.

Tests are run with yarn test

⚠️ Coverage is currently tiny, partly because most features require authentication. We need some kind of mock authentication.

Read more about testing for Vue at: