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 :
Table of contents
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:
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
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: