From 8a7ea7d91e056a2b4a4223eb13743cc8a0dacec6 Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Sat, 8 Feb 2025 07:33:35 +0100 Subject: [PATCH] Lets add docusaurus --- .github/workflows/documentation.yml | 59 +++++++++++ README.md | 8 +- docs/data-extension.md | 103 +++++++++++++++++-- docs/storing-objects.md | 148 ++++++++++++++++++++++++++++ website/docusaurus.config.js | 105 ++++++++++++++++++++ website/package.json | 43 ++++++++ 6 files changed, 455 insertions(+), 11 deletions(-) create mode 100644 .github/workflows/documentation.yml create mode 100644 docs/storing-objects.md create mode 100644 website/docusaurus.config.js create mode 100644 website/package.json diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..2470059 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,59 @@ +name: Documentation + +on: + push: + branches: + - documentation + pull_request: + branches: + - documentation + +jobs: + deploy: + name: Deploy Documentation + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: 18 + cache: npm + + - name: Install dependencies + run: | + cd website + npm ci + + - name: Build website + run: | + cd website + npm run build + + # Deploy to GitHub Pages + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + if: github.ref == 'refs/heads/documentation' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./website/build + user_name: github-actions[bot] + user_email: 41898282+github-actions[bot]@users.noreply.github.com + + # Notify on failure + - name: Notify on failure + if: failure() + uses: actions/github-script@v6 + with: + script: | + github.rest.issues.create({ + owner: context.repo.owner, + repo: context.repo.repo, + title: 'Documentation build failed', + body: 'The documentation build failed. Please check the workflow logs.' + }) \ No newline at end of file diff --git a/README.md b/README.md index 0d09062..f563056 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Open Registers -Open Registers provides the ability to work with objects based on [`schema.json`](https://json-schema.org/). +Open Registers provides a way to quicly build and deploy standardized registers based on [NLGov REST API Design Rules](https://logius-standaarden.github.io/API-Design-Rules/) and [Common Ground Principles](https://common-ground.nl/common-ground-principes/). It is based on based on the concepts of defining object types in [`schema.json`](https://json-schema.org/) and storing objects in configurable source. ## What is Open Registers? @@ -12,7 +12,7 @@ Registers provide APIs for consumption. Registers can also apply additional logic to objects, such as validation that is not applicable through the [`schema.json`](https://json-schema.org/) format. -## Features +## Key Features - 📦 **Object Management**: Work with objects based on [`schema.json`](https://json-schema.org/). - 🗂️ **Register System**: Manage collections of object types. @@ -60,7 +60,7 @@ Open Register makes these principles accessible to any organization by providing | Feature | Description | Benefits | |---------|-------------|-----------| -| 💾 [Object Storage](docs/object-storage.md) | Flexible storage backend selection per register | Storage flexibility, system integration, scalability | +| 💾 [Storing Objects](docs/storing-objects.md) | Configure how and where register data is stored | Storage flexibility, system integration, scalability | | 📝 [Audit Trails](docs/audit-trails.md) | Complete history of all object changes | Compliance, accountability, change tracking | | ⏰ [Time Travel](docs/time-travel.md) | View and restore previous object states | Data recovery, historical analysis, version control | | 🔒 [Object Locking](docs/object-locking.md) | Prevent concurrent modifications | Data integrity, process management, conflict prevention | @@ -75,7 +75,7 @@ Open Register makes these principles accessible to any organization by providing | ⚡ [Elasticsearch](docs/elasticsearch.md) | Advanced search and analytics capabilities | Performance, insights, complex queries | | 📋 [Schema Import & Sharing](docs/schema-import.md) | Import schemas from Schema.org, OAS, GGM, and share via Open Catalogi | Standards compliance, reuse, collaboration | | 🔔 [Events & Webhooks](docs/events.md) | React to object changes with events and webhooks | Integration, automation, real-time updates | -| 🔄 [Data Extension](docs/data-extension.md) | Automatically include related entities in responses | Efficient data retrieval, reduced API calls, complete context | +| 🔄 [Data Extension](docs/data-extension.md) | Include related entities in responses using _extend | Reduced API calls, complete context, efficient data retrieval | | ✂️ [Data Filtering](docs/data-filtering.md) | Select specific properties to return | Data minimalization, GDPR compliance, efficient responses | | 🔍 [Advanced Search](docs/advanced-search.md) | Filter objects using flexible property-based queries | Precise filtering, complex conditions, efficient results | | 🗑️ [Object Deletion](docs/object-deletion.md) | Soft deletion with retention and recovery | Data safety, compliance, lifecycle management | diff --git a/docs/data-extension.md b/docs/data-extension.md index e79a9d8..1fddd3c 100644 --- a/docs/data-extension.md +++ b/docs/data-extension.md @@ -1,15 +1,104 @@ # Data Extension (_extend) -Data Extension allows you to automatically include related entities in API responses, reducing the need for multiple API calls and providing complete context in a single request. +Data Extension allows you to automatically include related entities in API responses, reducing the need for multiple API calls and providing complete context in a single request. This is useful when you need to retrieve related data for a specific object or collection an lowers the number of API calls needed therby reducing the load on the server and improving performence client side. + +The extend patern is based was orginally developed for the [Open Catalogi](https://opencatalogi.org) project and is now available in the ObjectStore API. Its baed on the extend functionality of [Zaak gericht werken] but brought in line with p[NLGov REST API Design Rules](https://logius-standaarden.github.io/API-Design-Rules/) by adding a _ prefix to the parameter + ## Overview -The _extend parameter provides: -- Automatic inclusion of related entities -- Support for nested relations -- Resolution of both ID and URL references -- Configurable depth limits -- Circular reference handling +The extension system provides: +- Automatic inclusion of related objects +- Nested object resolution +- Circular reference protection +- Depth limiting +- Performance optimization + +## Extension Patterns + +### Basic Extension +Extend a single property: +- `?_extend=author` - Include full author object +- `?_extend=category` - Include full category object +- `?_extend=files` - Include file metadata + +### Nested Extension +Extend nested properties: +- `?_extend=author.organization` - Include author with their organization +- `?_extend=department.employees` - Include department with all employees +- `?_extend=project.tasks.assignee` - Include project with tasks and their assignees + +### Multiple Extensions +Combine multiple extensions: +- `?_extend=author,category,comments` - Include multiple related objects +- `?_extend=files,metadata,relations` - Include all related data +- `?_extend=all` - Include all possible relations on the root object + +## Extension Logic + +1. **Depth Control** + - Maximum depth of 3 levels + - Prevents infinite recursion + - Optimizes response size + - Manages performance + +2. **Circular Detection** + - Identifies circular references + - Prevents infinite loops + - Maintains data integrity + - Optimizes response + +3. **Type Handling** + - Single object relations + - Array of objects + - File references + - External references + +## Performance Considerations + +1. **Query Optimization** + - Efficient database queries + - Batch loading + - Cache utilization + - Resource management + +2. **Response Size** + - Selective extension + - Depth limiting + - Data filtering + - Compression + +3. **Caching** + - Response caching + - Relation caching + - Cache invalidation + - Cache optimization + +## Best Practices + +1. **Extension Selection** + - Request only needed relations + - Consider response size + - Use appropriate depth + - Plan for performance + +2. **Query Design** + - Use specific extensions + - Combine related requests + - Optimize query patterns + - Consider caching + +3. **Error Handling** + - Handle missing relations + - Validate extension paths + - Manage timeouts + - Provide fallbacks + +## Related Features + +- [Object Relations](object-relations.md) - Base for extensions +- [Data Selection](data-selection.md) - Combine with property selection +- [Content Search](content-search.md) - Search within extended data ## Extension Types diff --git a/docs/storing-objects.md b/docs/storing-objects.md new file mode 100644 index 0000000..88a30d2 --- /dev/null +++ b/docs/storing-objects.md @@ -0,0 +1,148 @@ +# Storing Objects + +Open Register provides flexible storage options for objects, allowing organizations to store their data in various backends while maintaining a consistent interface. + +## Overview + +The storage system supports: +- Multiple storage backends +- Transparent data access +- Unified querying interface +- Consistent audit logging +- Schema validation across stores + +## Storage Options + +### Nextcloud Internal Store (Default) +Default storage using Nextcloud's database: +- Objects stored as JSON in MariaDB/MySQL +- Full CRUD operations +- Built-in versioning +- Automatic audit trails +- Integrated with Nextcloud permissions + +### Relational Databases +Traditional SQL databases: +- MariaDB/MySQL +- PostgreSQL +- JSON column types +- SQL query optimization +- Transaction support + +### Document Stores +NoSQL databases optimized for JSON documents: +- MongoDB support +- Native JSON storage +- Schema-less flexibility +- High performance queries +- Scalable architecture + +### EAV (Entity-Attribute-Value) +Integration with systems like "Uit Betrouwbare Bron": +- Dynamic attribute storage +- Flexible schema support +- Legacy system compatibility +- Custom attribute mapping +- Historical data support + +## Storage Configuration + +Each register defines: +- Storage backend type +- Connection details +- Schema mapping +- Query optimization +- Cache settings + +## Implementation Details + +### Internal Store +```sql +CREATE TABLE objects ( + id INT PRIMARY KEY, + uuid VARCHAR(255), + object JSON, + metadata JSON +) +``` + +### Document Store +```json +{ + "_id": "object_id", + "uuid": "unique_id", + "object": { + "property": "value" + }, + "metadata": { + "created": "timestamp" + } +} +``` + +### Relational Store +```sql +CREATE TABLE objects ( + id INT PRIMARY KEY, + uuid VARCHAR(255), + data JSONB, + created_at TIMESTAMP +) +``` + +### EAV Store +```sql +CREATE TABLE object_values ( + object_id INT, + attribute VARCHAR(255), + value TEXT, + PRIMARY KEY (object_id, attribute) +) +``` + +## Key Benefits + +1. **Flexibility** + - Choose optimal storage per register + - Match existing infrastructure + - Scale independently + - Custom implementations + +2. **Integration** + - Legacy system support + - Multiple databases + - External systems + - Distributed storage + +3. **Performance** + - Storage optimization + - Query efficiency + - Caching strategies + - Scalability options + +## Best Practices + +1. **Storage Selection** + - Consider data structure + - Evaluate query patterns + - Assess volume requirements + - Plan for growth + +2. **Configuration** + - Optimize connections + - Set up caching + - Configure backups + - Monitor performance + +3. **Management** + - Regular maintenance + - Performance monitoring + - Security updates + - Backup verification + +## Related Features + +- [Schema Validation](schema-validation.md) - Validate across storage types +- [Audit Trails](audit-trails.md) - Track changes in all stores +- [Content Search](content-search.md) - Search across stores +- [Object Relations](object-relations.md) - Relations across stores \ No newline at end of file diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js new file mode 100644 index 0000000..a8ab674 --- /dev/null +++ b/website/docusaurus.config.js @@ -0,0 +1,105 @@ +// @ts-check +// Note: type annotations allow type checking and IDEs autocompletion + +const lightCodeTheme = require('prism-react-renderer/themes/github'); +const darkCodeTheme = require('prism-react-renderer/themes/dracula'); + +/** @type {import('@docusaurus/types').Config} */ +const config = { + title: 'Open Register', + tagline: 'Flexible object management for Nextcloud', + favicon: 'img/favicon.ico', + + // Set the production url of your site here + url: 'https://your-org.github.io', + // Set the // pathname under which your site is served + baseUrl: '/open-register/', + + // GitHub pages deployment config + organizationName: 'your-org', + projectName: 'open-register', + + onBrokenLinks: 'throw', + onBrokenMarkdownLinks: 'warn', + + // Even if you don't use internalization, you can use this field to set useful + // metadata like html lang. For example, if your site is Chinese, you may want + // to replace "en" with "zh-Hans". + i18n: { + defaultLocale: 'en', + locales: ['en'], + }, + + presets: [ + [ + 'classic', + /** @type {import('@docusaurus/preset-classic').Options} */ + ({ + docs: { + sidebarPath: require.resolve('./sidebars.js'), + editUrl: + 'https://github.com/your-org/open-register/tree/main/website/', + }, + blog: false, + theme: { + customCss: require.resolve('./src/css/custom.css'), + }, + }), + ], + ], + + themeConfig: + /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ + ({ + navbar: { + title: 'Open Register', + logo: { + alt: 'Open Register Logo', + src: 'img/logo.svg', + }, + items: [ + { + type: 'docSidebar', + sidebarId: 'tutorialSidebar', + position: 'left', + label: 'Documentation', + }, + { + href: 'https://github.com/your-org/open-register', + label: 'GitHub', + position: 'right', + }, + ], + }, + footer: { + style: 'dark', + links: [ + { + title: 'Docs', + items: [ + { + label: 'Documentation', + to: '/docs/intro', + }, + ], + }, + { + title: 'Community', + items: [ + { + label: 'GitHub', + href: 'https://github.com/your-org/open-register', + }, + ], + }, + ], + copyright: `Copyright © ${new Date().getFullYear()} Open Register. Built with Docusaurus.`, + }, + prism: { + theme: lightCodeTheme, + darkTheme: darkCodeTheme, + }, + }), +}; + +module.exports = config; \ No newline at end of file diff --git a/website/package.json b/website/package.json new file mode 100644 index 0000000..5e07c0f --- /dev/null +++ b/website/package.json @@ -0,0 +1,43 @@ +{ + "name": "open-register-docs", + "version": "0.0.0", + "private": true, + "scripts": { + "docusaurus": "docusaurus", + "start": "docusaurus start", + "build": "docusaurus build", + "swizzle": "docusaurus swizzle", + "deploy": "docusaurus deploy", + "clear": "docusaurus clear", + "serve": "docusaurus serve", + "write-translations": "docusaurus write-translations", + "write-heading-ids": "docusaurus write-heading-ids" + }, + "dependencies": { + "@docusaurus/core": "2.4.3", + "@docusaurus/preset-classic": "2.4.3", + "@mdx-js/react": "^1.6.22", + "clsx": "^1.2.1", + "prism-react-renderer": "^1.3.5", + "react": "^17.0.2", + "react-dom": "^17.0.2" + }, + "devDependencies": { + "@docusaurus/module-type-aliases": "2.4.3" + }, + "browserslist": { + "production": [ + ">0.5%", + "not dead", + "not op_mini all" + ], + "development": [ + "last 1 chrome version", + "last 1 firefox version", + "last 1 safari version" + ] + }, + "engines": { + "node": ">=16.14" + } +} \ No newline at end of file