Architecture

• Architecture Summary
• Design Proposal
• Architectural Proposal to make
• Architectural Decision Records

Architecture Summary

Cristal is a generic wiki UI that is able to connect to various back-ends (e.g., a XWiki instance, or a local folder).

The UI adapt itself to the capabilities of the backend. For instance, when using a local folder back-end, the login action is proposed as it is not required in such context.

The protocol to communicate between with a back-end is not formalized, but Cristal provide APIs to be implemented by back-end connectors.

Design Proposal

• Main Design page
• Individual proposals

Architectural Proposal to make

• Architecture must be offline-compliant
  • Important to justify javascript/typescript as the main coding language of Cristal
• Represent documents internally using JSON-LD
  • Javascript allows storing JSON-LD in memory directly
  • Decide if using JSON-LD internally in memory is a performant format or if we need another structure (like some class). We could imagine using JSON-LD only for external access to XWiki page data.
  • See https://jira.xwiki.org/browse/CRISTAL-37
• Use Markdown as the default syntax for documents
  • See https://jira.xwiki.org/browse/CRISTAL-39
• Should we support syntaxes other than Markdown in Cristal (client side)?
  • See https://jira.xwiki.org/browse/CRISTAL-41
• Decide if we implement the concept of XDOM client-side or not
  • If don't implement XDOM client-side, it's hard to implement a powerful client-side macro feature
  • No jira issue created yet
• Propose a Capability API
• Propose a UI Extension mechanism (e.g. for comments, ability for an extension to decide how to display them - and for the XWiki adapter, which can be a set of extensions)
• Decide of the versioning mechanism between backend-specific clientside code in Cristal and backend versions
• Propose using a Design System (forum proposal sent but not solved yet)
• Propose Component-based development.
  • Current discussion: https://forum.xwiki.org/t/choice-of-javascript-dependency-injection-library/13303
  • Remaining work:
    • Agree on using Inversify
    • Our own API vs Inversify
    • How to implement namespaces
    • Document the API with examples on cristal.xwiki.org
• Propose a functional test framework: playwright - https://jira.xwiki.org/browse/CRISTAL-11
• Propose a solution in the build for testing accessibility - https://jira.xwiki.org/browse/CRISTAL-12
• Propose the concept of backend adapter and the fact that a backend adapter is a set of local Extensions
  • Propose that cristal backend adapters have the concept of supported backend versions (posibly feature by feature), so that the adapter knows the way to call the backend depending in its version. If the backend doesn't provide an api to get its version, provide a config setting to manually set it in Cristal.
• Propose a configuration API
• Propose that when developing a feature/module, the best practice is to review the following aspects: architecture, performance, security, configurability, accessibility, internationalization, realtime/usability, logging/manageability (JMX), extensibility
  • Idea 1: propose a design template (for design.xwiki.org) and the owner of the feature must prove that he has thought of all the aspects
  • Idea 2: link it to the idea of ADR
• Agree that backends shouldn't provide their own front end resources to Cristal (but they could provide Cristal-specific resources)
• Discuss protection of local data in Cristal (e.g. you connect to an XWiki backend with an auth, then go offline, how do you protect local data?)
• Propose a simple way to develop and deploy Cristal extensions
• Propose "Do not show features if the user does not have the right on that feature" as a design best practice (https://jira.xwiki.org/browse/CRISTAL-122)
• Decide if we use a SPA architecture (Single Page Application) and SFC, and Composition API or Options API
• Should we think about using https://blockprotocol.org/ ?

Architectural Decision Records

All the items below have been agreed on the dev forum. We use an ADR system to record them. To add a new ADR, go the ADR Application and create a new page of type "ADR".

TODO: Move the following as ADR records:

• Vue 3 as the front-end framework
• The Vue Components will be published as Web Components
• It is possible to use Web Components as part of the Vue templates
• Dependency injection framework selected: Inversify
• Build tool: pnpm
• Cristal must be extensible and based on Extensions
  • Ability to add or remove all features by installing or uninstalling Extensions