Technical documentation

This document is a COMPLETE DRAFT and will be cleaned up later... I'm just putting down some unorganized notes for later.

Here is a first - always WIP - version of a technical documentation, written by chunks during the MVP development. Everything will be made nice after a first major version to facilitate contribution and long term maintenance.

#Technologies

Some choices are temporary because the MVP is a rush phase without much thinking about the tools, it should just work in the start, and we'll refactor or change later.

• Laravel
• VueJS
• TailwindCSS
• markdown-it: Markdown parser in JS
• highlight.js: code highlighting JS library (may change in the future)
• Pinia: state management system

TODO: add and fix code highlighter + markdown parser + mermaid support TODO: markdown styling + css classes and colors available for a future Delibay theme

#Database

#Testing data

You can seed your local development database with fake data. These data are defined in DatabaseSeeder.php and factories for each model class.

php artisan db:seed

#Strange things

Database tables and Laravel models sometimes have strange names, I chose a short version of the long names for simplicity and productivity.

Here is the equivalent:

• Exo: Exercise
• Org: Organization (school, university, ...)

#Register

The register process is divided in 4 steps:

• 1. The user give the server URL, the server is pinged to make sure this is a Delibay server
• 2. The user reads and accept the server rules
• 3. The user fills the form
  • The user clicks Submit
  • Some checks are made on the inputs and the data is sent
  • Delibay shows request errors or the server response
• 4. As the account has been created, Delibay shows the email validation page
  • The user enters the secret code received by email
  • If invalid let the user retry
  • If valid show a successful message and login the user

#Frontend

Here is all information related to the frontend app (the repos is delibay/frontend on Codeberg).

#Stack

The frontend is a VueJS SPA, with Vue 3 with TypeScript. The project has been scaffold with Vite. Here the different tools used for development.

• Pinia: the official state management system of the Vue ecosystem (its predecessor was Vuex)
• pinia-plugin-persistedstate: a NPM package to persist and rehydrate Pinia stores in localStorage easily
• DexieJS: an intuitive IndexedDB wrapper, provide a SQL-like interface to manage the local state.

#Testing

Having strong and well-written tests is very important to facilitate the maintenance, refactoring, contributions, and general quality. Every contribution touching the logic should add or change automated tests. Here are the tools currently used in the project:

• Cypress: the end-to-end testing framework

#Cypress

#Conventions

• Typescript: we use TypeScript everywhere.
• Vue Composition API: we use the Composition API instead of the Options API (to group things by feature and having the benefit of better type inference)
• Script setup syntax: inside our single file components, the script tag must be <script setup lang="ts">...</script>. Read more on the official documentation if needed.

#How to contribute

THIS IS A DRAFT... Before accepting contributions I need to choose some free licenses.

1. Choose a way you want to contribute
   1. Talk to your IT friends and IT teachers about the project
   2. (long term) Help to translate the project
   3. (coming soon, need some development) Report feedback during usage of the frontend, give feedback on the documentation, or the design document
   4. Report bugs via the issues
   5. Contribute to fix the existing issues with code
   6. Help us achieve a greater code quality level, by adding or fixing tests on the frontend and backend
   7. Contribute to the design

Contribute with code:

1. Setup a local installation (see README)
2. Configure your tools (linter)
3. Pick an issue
4. Fork and clone the repos of your choice