Developer documentation

Welcome to the developer documentation of the Junqo-platform.
This documentation is intended for developers who want to contribute to the project.

If you are a new contributor, you should start by reading the getting started section.
If you need some precise information, see the following sections :

Getting started
Learn more

Getting started

Before you begin

Before you begin, you should have a basic understanding of the following:

Take a look at the contributing guidelines to understand how to contribute to the project.
Take a look at the code of conduct to understand how to behave in the project.
Take a look at the project structure to understand how the project is organized.

Prerequisites

Git
Docker (v20.10.7 or higher)
Docker Compose (v1.29.2 or higher)

Installation

Clone the repository

 git clone git@github.com:Junqo-org/junqo-platform.git

Move to the project directory
```
 cd junqo-platform
```
Deploy the project locally using Docker Compose
```
 docker-compose up --build
```

Usage

Notice, the following instructions are admitting that you are using the default configuration of the project.
Furthermore, the project is running in production mode.
You should replace localhost by the IP address of the machine running the project.

Access the web server at http://localhost:80 or https://localhost:443 if using TLS.
Access the back server at http://localhost:4200.
Access the database adminer at http://localhost:3000.

Learn more

Notice, the following sections are admitting that you are using the default configuration of the project.

Project structure

The project is structured as follows:

docker-compose.yml
├── /junqo_back
│   ├── Dockerfile
│   ├── Dockerfile.dev
│   ├── /src
│       ├── main.ts
├── /junqo_front
│   ├── Dockerfile
│   ├── Dockerfile.dev
│   ├── /lib
│       ├── main.dart
├── /docs
│   ├── developer_documentation/
│   ├── user_documentation/
│   ├── index.md
├── docker-compose.yml
├── docker-compose.dev.yml

Project structure diagram

back: Runs the REST API server to communicate with the database.
front: Runs the web server / Flutter app seen by the user.
docs: Contains the documentation of the project.
docker-compose.yml: The main file to deploy the project in production mode.
docker-compose.dev.yml: The main file to deploy the project in development mode.

Interactions

The following diagram shows the interactions between the different parts of the project:

+-----------+ +----------+ +------------+ | Front | <---> | Back | <---> | DataBase | +-----------+ +----------+ +------------+

Interactions diagram

The front communicates with the back using the REST API.
The back communicates with the database using the database driver.
The database stores the data.

Operation

The following diagram shows how the different programs are executed:

Operational diagram

Operational diagram

Networking

The following diagram shows the networking of the project:

External ports:   80/443              4200                5432                 3000
                     |                  |                   |                    |
               +-----------+       +----------+       +------------+       +-----------+
               |   Front   |       |   Back   |       |  DataBase  |       |  Adminer  |
               +-----------+       +----------+       +------------+       +-----------+

Networking diagram

The front is accessible on the World Wide Web at port 80/443. The back is accessible on the World Wide Web at port 4200. The database is accessible on the World Wide Web at port 5432 (admitting that you are using Postgresql). The adminer is accessible on the World Wide Web at port 3000.

API

The backend API uses GraphQL to communicate with the frontend.
A schema is available at /schemas/schema.graphqls. Yous can find the API documentation at http://doc.junqo.org/api/index.html.

Documentation Generation

The project uses Magidoc to generate the backend API documentation.
The documentation is available at http://doc.junqo.org/api/index.html.
The documentation is generated automatically when the project is deployed using Github Action.

If you want to generate the documentation manually, you can use the following command:

npx @magidoc/cli@latest generate

The rest of the documentation is written in Markdown and is available in the docs directory. It is automatically generated into a static website using Jekyll and is deployed using Github Pages. The documentation is available at http://doc.junqo.org/developer/index.html.

Install the dependencies by running the following command:

bundle install

Update the Gemfile.lock file by running the following command:

bundle update

To generate the documentation, run the following command:

bundle exec jekyll build

To serve the documentation locally, run the following command:

bundle exec jekyll serve --baseurl=""

For more information, see the the official github page documentation.

Technologies

The project uses the following technologies: