Skip to content

arch.md

Latest commit

 

History

History
140 lines (111 loc) · 10.3 KB

arch.md

File metadata and controls

140 lines (111 loc) · 10.3 KB

Le Lexique Libanais de Makki : note d'architecture

Cette note d'architecture décrit la structure du système et son fonctionnement global.

Historique

version date changements
1.0 23/02/2024 v. initiale
1.1 11/02/2025 modif scripts Extraction_Donnees

Fonctionnement général

Lorsqu'une requête est envoyée au serveur, celui-ci remonte le chemin de l'url. Si l'on a http://www.serveur.fr/makki/lexique?coverage=Nord+du+Liban, et que le dossier makki est là où se trouvent les fichiers du site, le serveur s'arrête là à la lecture de l'url car le fichier .htaccess définit une règle de réécriture qui renvoie toute requête lui parvenant au script php index.php.

Ce script récupère les principales informations de configuration de config et instancie un objet de la classe RequestHandler, qui effectue la majeure partie du travail et coordonne tout le traitement de la requête.

C'est ensuite le RequestParser qui s'occupe de découper l'url :

  • /lexique/bla donne alors {'collection' : 'lexique', 'target' : 'bla'}
  • /fr/lexique?coverage=Tripoli donne {'collection' : 'lexique', 'lang' : 'fr', 'query' : {'coverage' : 'Tripoli'}}
  • /images/logo.png donne {'collection' : 'images', 'target' : 'logo.png'}

Et ainsi de suite...

L'utilisateur est ensuite authentifié si un cookie de session est fourni, notamment en s'appuyant sur l'implémentation de signature, vérification, chiffrement et déchiffrement de tokens.

L'étape suivante est la négociation de langue : définir un ordre de priorité des langues disponibles en fonction des informations de l'utilisateur. L'idée est la suivante :

  • On récupère dans la base de données les langues d'interface disponibles
  • Si une langue est précisée dans l'url et qu'elle est disponible, on la considère comme étant la plus importante
  • Les langues définies à travers l'en-tête HTTP Accept-Language et disponibles sont classées selon l'ordre défini par le navigateur (grâce au coefficient q)
  • Toutes les autres langues disponibles sont ensuite ajoutées, avec la plus faible priorité.

Une fois cela fait, on passe au traitement de la requête proprement dit. Le système gère trois méthodes HTTP :

  • GET, qui permet de récupérer des informations du serveur sous la forme de documents (on parle de "représentation de ressource") ; il peut s'agir d'images, de scripts, d'html, de json, de xml... Le type de contenu (dit aussi type MIME, et défini dans la réponse par l'en-tête HTTP Content-Type) est défini de deux manières possibles : si la collection est images, scripts, styles ou fonts, il s'agit d'une ressource visuelle ou interactive, on détermine le type par rapport au fichier ciblé. Autrement, le type est défini via l'en-tête HTTP Accept.
  • POST, qui permet de transférer des données au serveur, soit pour se connecter, soit pour alimenter la base de données (contenu, traductions, etc.)
  • DELETE, qui supprime des données du serveur.

DELETE nécessite obligatoirement d'être authentifié, ce qui est aussi le cas de POST dans la majorité des cas (excepté l'authentification elle-même, évidemment).

Le système s'occupe après de récupérer ou de verser les données nécessaires depuis ou vers la base de données à travers DB. Si des fichiers sont à télécharger, ils sont temporairement stockés par FileUploader dans /uploads/<id_utilisateur> puis supprimés. Enfin, si une représentation doit être générée dynamiquement, cela se fait à travers le sérialiseur correspondant au type demandé (association définie dans mimes.json).

index.php envoit ensuite les en-tête de réponse nécessaires à partir du RequestHandler puis envoie le corps généré.

---
title: Fonctionnement
---
flowchart LR
    index[index.php]
    RequestHandler
    RequestParser
    Serializer
    DB[(DB)]
    JsonWebProcess
    FileUploader
    JWT -.->|isa| JsonWebProcess
    JWS -.->|isa| JsonWebProcess
    JWE -.->|isa| JsonWebProcess
    HTMLSerializer -.->|isa| Serializer
    TEISerializer -.->|isa| Serializer
    JSONSerializer -.->|isa| Serializer
    RDFSerializer -.->|isa| Serializer
    TTLSerializer -.->|isa| Serializer
    index -->|"Lance"| RequestHandler
    HTMLSerializer -->|"Récupère les traductions" | DB 
    RequestHandler -->|"Génère la représentation de ressource"| Serializer
    RequestHandler -->|"Découpe l'URL, les queries"| RequestParser
    RequestHandler -->|"Récupère les langues, les données"| DB
    RequestHandler -->|"Signe les tokens"| JWS
    RequestHandler -->|"Chiffre les tokens"| JWE
    RequestHandler -->|"Met en forme les tokens"| JWT
    RequestHandler -->|"Télécharge les fichiers temporaires"| FileUploader
Loading

Arborescence

Seuls les dossiers et fichiers directement impliqués dans le fonctionnement du système (en incluant l'extraction et pré-traitement des données) seront notés ici. Le présent fichier, .gitignore et consorts ne sont pas inclus.

. (racine)

Description
.htaccess Permet de définir index.php comme unique point d'entrée à partir de ce dossier.
index.php Point d'entrée du système. Récupère la configuration et lance le traitement de la requête utilisateur.
api Dossier contenant les fichiers PHP pour le traitement des requêtes, la génération des documents de sortie, l'interaction avec la base de données et la sécurisation des échanges.
config Contient les différents fichiers de configuration du système.
html Contient les ressources nécessaires à la génération des sorties, comme les patrons html, les feuilles de style, les scripts et les polices d'écriture.
traductions Contient les fichiers de traduction du site.
extract_data Scripts python destinés à extraire les donneés des fichiers .docx du lexique pour une conversion en fichier RDF. Ces scripts sont contenus dans un fichier Google Colab pour une utilisation, obligatoirement externe, plus simple pour les administrateurs.
uploads (à créer, voir la note de portabilité) Dossier accueillant des sous-dossiers pour chaque administrateur, stockant temporairement les fichiers téléversés.
secure (à créer, voir la note de portabilité) Dossier accueillant les fichiers de clés pour le chiffrement, déchiffrement et signature des tokens.

./api

Description
handler.php Coordonne le traitement des requêtes en mettant en oeuvre les différentes étapes de traitement.
parser.php Met à disposition des fonctions permettant d'extraire les informations des URI, des queries, et des headers Accept et Accept-Language.
db.php Permet d'interagir avec la base de données.
jwt.php Introduit des classes permettant de chiffrer, déchiffrer et signer des JSON Web Tokens, ainsi que de générer les clés nécessaires.
upload.php Classe permettant de gérer l'upload de fichiers.
tools.php Fichier fourre-tout permettant de stocker des fonctions diverses.
composer.json Fichier listant les dépendances du projet. Utilisé par Composer pour installer ces dépendances.
serializers Contient les classes de génération des documents de sortie.
simple_html_dom Dépendance externe indisponible avec Composer, et permettant de lire et modifier du HTML.

./api/serializers

Description
serializer.php Définit la classe abstraite pour tous les sérialiseurs (et donc un cadre commun).
*.php Permet de générer les sorties dans différents formats (en fonction de leur type MIME).

./config

Description
db.json (à créer, voir la note de portabilité) Permet de configurer l'accès à la base de données.
db.sql Script permettant de mettre en place la base de données à la première utilisation.
headers.json Définit les headers HTTP par défaut, à inclure dans chaque requête.
mimes.json Définit les types mimes acceptés pour les sorties, et les sérialiseurs associés.
pages.json Permet d'associer un patron HTML à une collection (premier élément de l'URI si pas de langue spécifiée).
prefixes.ttl Préfixes RDF à inclure dans chaque requête au TripleStore.
server.txt (à créer, voir la note de portabilité) Permet au système de connaître l'URL de base, sans le path. Cela est particulièrement nécessaire dans le cas où le site se trouve dans un sous-dossier de public_html.

./extract_data

Description
Extraction_de_donnees.ipynb Fichier Python Notebook (Google Colab) contenant les scripts permettant de convertir un fichier docx en un fichier JSON, puis un fichier JSON en un fichier rdf importable.

./html

Description
*.html Patrons de page HTML.
fonts Polices d'écritures du site.
images Images du site.
scripts Scripts Javascript.
styles Feuilles de style CSS.