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:

Prerequisites

Installation

  1. Clone the repository

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

  2. Move to the project directory

     cd junqo-platform

  3. 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.

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:

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

Project structure diagram

  • back: Runs the Graphql 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.yaml: The main file to deploy the project in production mode.
  • docker-compose.dev.yaml: 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 Graphql 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  |
               +-----------+       +----------+       +------------+       +-----------+

---
title: Networking
---
flowchart BT
%% External ports
    A("**Front**") --> P1;
    B("**Back**") --> P2;
    C("**Database**") --> P3;
    D("**Adminer**
    (*development only*)") --> P4;
    P1[[80/443]];
    P2[[4200]];
    P3[[5432]];
    P4[[3000]];
    linkStyle 0,1,2,3 stroke-dasharray: 4 3

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.graphql. Yous can find the API documentation at http://doc.junqo.fr/api/index.html.

Sequence Diagram

The following diagram shows the sequence of the project:

User SignUp 

sequenceDiagram
  participant U as User
  participant LS as Register Screen
  participant FAS as Frontend AuthService
  participant GC as GraphQL Client
  participant AR as AuthResolver (Backend)
  participant BAS as Backend AuthService
  participant DB as Database

  U->>LS: Enter credentials
  LS->>FAS: Call signUp(type, name, email, password)
  FAS->>GC: Send signUp mutation
  GC->>AR: Relay signUp request
  AR->>BAS: Invoke signUp method
  BAS->>DB: Create user record
  DB-->>BAS: Return user data/error
  BAS-->>AR: Return AuthPayload or error
  AR-->>GC: Return response
  GC-->>FAS: Deliver auth result
  FAS-->>LS: Return token and user details

User SignIn 

sequenceDiagram
  participant U as User
  participant LS as Login Screen
  participant FAS as Frontend AuthService
  participant GC as GraphQL Client
  participant AR as AuthResolver (Backend)
  participant BAS as Backend AuthService
  participant DB as Database

  U->>LS: Enter credentials
  LS->>FAS: Call signIn(email, password)
  FAS->>GC: Send signIn mutation
  GC->>AR: Relay signIn request
  AR->>BAS: Invoke signIn method
  BAS->>DB: Query user record by email
  DB-->>BAS: Return user data/error
  BAS-->>AR: Return AuthPayload or error
  AR-->>GC: Return response
  GC-->>FAS: Deliver auth result
  FAS-->>LS: Return token and user details

User login status check 

sequenceDiagram
  participant U as User
  participant FE as Frontend Component
  participant FAS as Frontend AuthService
  participant GC as GraphQL Client
  participant AR as AuthResolver (Backend)

  U->>FE: Request login status check
  FE->>FAS: Call isLoggedIn()
  FAS->>GC: Send isLoggedIn query
  GC->>AR: Request login status
  AR-->>GC: Return true
  GC-->>FAS: Deliver status
  FAS-->>FE: Confirm logged in state

CI/CD

For the continuous integration and continuous deployment, the project uses Github Actions and Docker Compose. The CI/CD pipeline is defined in the .github/workflows directory.

You can find the CI/CD documentation at here.

Technologies

The project uses the following technologies: