Paradicms Collections Management System

This monorepo contains mot of the code and data for the Paradicms Collections Management System.

Getting started

For documentation on how to use Paradicms, see the Paradicms website.

For developer documentation, read on.

Repository organization

Code

The code in this repository is organized into three areas:

• app/: Paradicms app implementations
• lib/py/: Python libraries, which are primarily used by Paradicms GitHub Actions
  • lib/py/etl: code for transforming data from various sources (Airtable, Omeka, spreadsheets, et al.) into one of the logical data models supported by Paradicms
  • lib/py/ssg: code for statically generating websites (apps) from data adhering to one of the logical data models
• lib/ts: TypeScript libraries used by app implementations

Data

The data/ directory contains synthetic data used in development and test data used in unit tests. It also contains generated Costume Core ontologies.

Scripts

There are standardized scripts for building and testing different parts of the code, following the Scripts to Rule Them All pattern. These scripts reside in (sub)directories named script/.

First-time setup

Python libraries

Dependencies

• Python 3.9+
• Poetry

Setup

script/py/bootstrap

TypeScript libraries and apps

Dependencies

• Node.js 16+
• Yarn 1.x

Setup

script/ts/bootstrap

Building

TypeScript libraries

yarn build-lib

TypeScript libraries and apps

export DATA_FILE_PATHS="$PWD/data/synthetic/synthetic_data_ts.trig"
yarn build

A single TypeScript app

export DATA_FILE_PATHS="$PWD/data/synthetic/synthetic_data_ts.trig"
cd app/work-search
yarn build

A single TypeScript library

cd lib/ts/models
yarn build

Running tests

Python libraries

script/py/test

TypeScript libraries and apps

script/ts/test

Debugging

Enabling source maps in TypeScript

Change inlineSourceMap to true in tsconfig.base.json, then yarn rebuild-lib.

URL source maps (sourceMap: true) don't currently work between Next.js and the TypeScript libraries.

Disable inlineSourceMap again before pushing to production.

Continuous Integration

This repository uses GitHub Actions for Continuous Integration and Deployment (CI/CD). See the .github/workflows directory for GitHub Actions workflow specifications.

Continuous Deployment

Merges to the default branch trigger a GitHub Actions workflow that:

• builds a single Docker image from the Dockerfile in the root of the repository and
• pushes the image to the GitHub Container registry for the organization

This Docker image is the working environment for the Paradicms GitHub Actions. It contains:

• Python libraries and their dependencies installed in the image's system Python interpreter
• TypeScript libraries and their dependencies
• Ready-to-build Paradicms apps

Coding conventions and tools

Python

The Python libraries use type annotations throughout, and mypy for type checking.

Python code is formatted with the Black code formatter.

Flake8 is used for additional linting.

TypeScript

TypeScript code is formatted with Prettier.

License

GNU General Public License version 3 (GPLv3)