Architecture

Overview

RaspboCrate is built as a set of Docker containers orchestrated with Docker Compose. This architecture ensures easy deployment, updates, and maintenance while running on resource-constrained hardware like the Raspberry Pi.

Components

raspbocrate (Admin Interface)

The admin interface is a React application that provides a web-based UI for managing the RaspboCrate system. It allows users to:

• Configure system settings
• Import collections from USB drives
• Manage installed applications
• Monitor system status

Built with React, TypeScript, and Tailwind CSS, it communicates with the API via REST endpoints.

raspbocapi (API Server)

The API server is a Fastify-based Node.js application that handles:

• RO-Crate data processing and indexing
• USB drive detection and data import
• Configuration management
• Communication between the admin UI and backend services

It uses Prisma as an ORM for database operations and provides a RESTful API for the admin interface.

oni-ui (Catalogue Browser)

Oni UI is a Vue.js application for browsing and searching RO-Crate catalogues. It provides:

• Full-text search across all indexed content
• Faceted filtering by collection, language, and other metadata
• Detailed views of collections, items, and files
• Responsive design for various screen sizes

OpenSearch

OpenSearch (a fork of Elasticsearch) provides the search functionality for the system. It:

• Indexes RO-Crate metadata for fast retrieval
• Supports full-text search with relevance ranking
• Enables faceted navigation and filtering
• Handles aggregations for statistics and visualisations

MariaDB

MariaDB serves as the relational database for storing:

• System configuration
• User preferences
• Import history and status
• Application state

Data Flow

USB Import Process

1. User inserts a USB drive containing RO-Crate data
2. The API server detects the USB drive and scans for RO-Crate metadata
3. User selects collections to import via the admin interface
4. The API server copies data to local storage
5. RO-Crate metadata is parsed and indexed into OpenSearch
6. Import status is recorded in MariaDB
7. Collections become searchable in Oni UI

Search Request Flow

1. User enters a search query in Oni UI
2. Oni UI sends the query to the API server
3. The API server constructs an OpenSearch query
4. OpenSearch returns matching documents
5. Results are formatted and returned to Oni UI
6. Oni UI displays the search results with facets

Networking

All containers communicate over a Docker bridge network. The nginx reverse proxy routes external requests to the appropriate service:

• / → Oni UI (catalogue browser)
• /admin → raspbocrate (admin interface)
• /api → raspbocapi (API server)

This allows the entire system to be accessed through a single hostname and port.

Resource Considerations

RaspboCrate is designed to run efficiently on Raspberry Pi hardware:

• Memory: OpenSearch is configured with reduced heap size suitable for 4GB+ RAM systems
• Storage: Data is stored on the SD card by default, but can be configured to use external storage
• CPU: Multi-architecture images (amd64/arm64) ensure native performance on Pi hardware

Development

For development setup and contributing to RaspboCrate, see the GitHub repository .