Architecture

Last modified by Vincent Massol on 2024/02/23 16:52

Initial Design Proposal

Proposed Architectural Decisions

  • 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
  • Should we support syntaxes other than Markdown in Cristal (client side)?
  • 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.
  • 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)

Agreed Architectural Decisions

Move items below once they're been agreed on the dev forum.

TODO: Move to ADR when available

  • Language selection: Typescript
  • 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
Tags:
    

Welcome

Welcome to this XWiki!

  • Powered by XWiki 14.10.18-node1. Hosted and managed by XWiki SAS

Get Connected