apxtri/GEMINI.md

Instructions pour Gemini sur le projet APXTRi

Ce fichier contient les règles et conventions spécifiques à ce projet.

• Documentation API : Chaque nouvelle route d'API ou modification de route doit être systématiquement documentée en utilisant le format apiDoc.

• Fichiers de Langue : Pour chaque nouvelle chaîne de texte visible par l'utilisateur (par exemple, les messages d'erreur ou de succès), les clés de traduction correspondantes doivent être ajoutées dans les fichiers models/tplstrings/*_fr.json et models/tplstrings/*_en.json.

• Validation Visuelle : Avant d'utiliser un outil pour modifier un fichier (replace ou write_file), afficher le code exact qui sera modifié (l'ancien et le nouveau) dans la console. Attendre ma confirmation visuelle avant de procéder à la modification.

• Architecture du projet : Un fichier .env qui indique ou se trouve le projet express NODEPATH, les data se trouvent dans DATAPATH et les log dans LOGPATH. CADDY est utilisé comme reverse proxy pour express et comme serveur de page web statique. apXtri dont le point d'entrée est apxtri.js est organisé en mode API restfull (CRUD) autour de gestion d'objets sous le controle de la routes/odmdb.js et /models/Odmdb.js qui s'appuie sur un schema/nom_objet.json qui decrit les propriétés (format schema-JSON 12-2020) et qui contient un identifieant unique apxid, des droits (accessrights) organisés autour de profil avec des droits C create, R read, U update, D delete basé sur l'appartenance du demandeur (via un header) à un profil particulier. Ce schema contient aussi une liste d'index permettant de trier, lister, classifier des identifiants. apXtri est une tribu qui permet à d'autres tribus de faire fonctionner de façon commune des objets privées à la tribu. Les objets sont stockés par nom de tribu puis par nom d'objet puis dans un repertoire itm chaque objet est enregistré dans un json nommé par la valeur de son apxid .json, chaque index est stocké avec son name.json dans le repertoire idx au même niveau que itm. Dans le cas ou des besoins de gestion des objets necessitent de contourner des droits ou de declencher des actions specifiques. Une tribu se trouve dans le repertoire NODEPATH avec son non unique et respecte la même logique de routes models que apxtri. Les data sont organisées de la même façon avec un repertoire nommé avec le nom de la tribu. Ces routes sont activées au moment du lancement d'apxtri.js. Pour eviter de t'alimenter avec trop de données GEMINI est lancé sur apxtowns/apxtri, un repertoire tmp/data/tribename/objects/wco et wwws va te permettre de pouvoir analyser et modifier ces fichiers html js css.

-Specificité des objets wco et wwws : Des fichiers statiques servis par Caddy sont stockés dans l'objet wwws, on trouve dans wwws/itm/appname.json la configuration de la webapp. Les fichiers de la web app de travail sont stockés dans wwws/appname/src et les fichiers optimisés sous le contrôle du models apxtri/models/Wwws.js sont stockés dans wwws/appname/dist. Caddy permet de rendre accessible sur le web /src/ et /dist/. Core Philosophy: Dynamic, Config-Driven UIs The apXtri frontend architecture is not built like a traditional, static Single Page Application (SPA). Instead, it's a dynamic, configuration-driven system. The server assembles the entire context for a web page—including data, templates, and component logic—based on a series of JSON configuration files.

This approach allows for:

Extreme Reusability: wco components are self-contained and can be dropped into any wwws application. Dynamic Page Composition: The layout and content of a page can be altered without deploying new code, simply by changing the JSON configuration. Data-Centric Design: The system is centered around well-defined data models (schema) and local data instances (tpldata). The Building Blocks: Key Files and Directories wwws (Web Application)

Definition (/tmp/data/objects/wwws/itm/{appname}/{appname}.json): This is the manifest for a web application. Its most important property is pages, which defines the structure and component makeup of each page in the app. Source Files (/tmp/data/objects/wwws/itm/{appname}/src/): This directory contains the application's "host" pages (like apxid_fr.html), which are simple HTML shells. It also contains the local data instances (tpldata) that customize wco components for this specific app. wco (Web Component Object)

Definition (/tmp/data/objects/wco/itm/{wconame}.json): The manifest for a reusable component. It declares the component's templates (tpl), data models (tpldatamodel), and other metadata. Business Logic (/tmp/data/objects/wco/itm/{wconame}/{wconame}.js): A server-side JavaScript file that can contain logic associated with the component. Base Logic (/tmp/data/objects/wco/itm/apx/apx.js): A foundational JavaScript library that provides common functionalities (like data fetching, rendering, event handling) to all wco components, acting as a mini-framework. Models and Routes

models/Wwws.js: The server-side NodeJS model responsible for interpreting the wwws and wco configurations. It's the brain of the operation. routes/wwws.js: The Express.js router that exposes the functionality of Wwws.js as a set of API endpoints. The End-to-End Workflow: From Request to Render Let's trace the journey of a user requesting the apxid_fr.html page from the admin application.

Step 1: The "Installation" of a Component (A Developer Task)

This is a one-time setup action performed by a developer.

Developer Action: A developer decides to add the apxauth component to the admin app's apxid page. API Call: They trigger a call to the /getwco/apxauth endpoint, providing the tribe, xapp=admin, and pagename=apxid in the query. Wwws.getwco Execution: The getwco function in models/Wwws.js is executed. It reads the component's manifest (apxauth.json). It reads the application's manifest (admin.json). It merges the component's configuration (its templates, schemas, etc.) into the pages.apxid section of admin.json. Crucially, it looks at the tpldatamodel defined in apxauth.json. For each data model, it creates a corresponding local data file in the application's directory (e.g., admin/src/tpldata/apxid_the-tag-id_apxauth.json). This file is a copy of the component's template data, ready for app-specific customization. Result: The admin.json file is now updated. The apxauth component is officially "installed" on the apxid page. Step 2: The User Page Load (A User Action)

Browser Request: The user navigates to https://admin.apxtri.farm.ants/src/apxid_fr.html. The browser loads this simple HTML file.

Initial JavaScript Execution: The apxid_fr.html file contains <script> tags. The core script, apx.js, is loaded. This script acts as the bootstrapper.

Bootstrapper Action: The apx.js script immediately makes an API call to fetch its configuration and data. It calls one of the updatelocaldb endpoints in routes/wwws.js (e.g., /updatelocaldb/the-tribe/admin/apxid/0).

Wwws.initlocaldata Execution:

The initlocaldata function in models/Wwws.js runs. It reads the now-updated admin.json to understand the structure of the apxid page. It sees that this page requires templates, data, and schemas from the apxauth component (and potentially others). It proceeds to read all the required files from the disk in parallel: Mustache templates (.mustache) Customized local data (admin/src/tpldata/.json) Schema definitions (schema/.json) And other referenced data (itms, options, etc.) It bundles all of this content into a single, large JSON object. Data Payload Returned: The server responds to the updatelocaldb call with this large JSON object, which we'll call localData.

Frontend Rendering:

The apx.js script receives the localData object. It now has everything it needs to render the page: localData.tpl contains the Mustache template strings. localData.tpldata contains the data to populate the templates. localData.schema provides validation rules. apx.js uses a Mustache rendering library to combine the templates and data, generating HTML. This newly generated HTML is then injected into the DOM of the apxid_fr.html shell page, bringing the application to life.