TechradarDev/docs/app/architecture.md

Architecture du projet

Vue d'ensemble

Le projet AJR Technology Radar est une application web statique construite avec le framework aoe_technology_radar (basé sur Next.js), dont le code source est vendu dans le répertoire radar-app/. L'application génère un site web interactif à partir de fichiers Markdown organisés par dates de release.

Structure des répertoires

TechradarDev/
├── radar/                    # Contenu du radar principal organisé par dates (déprécié)
│   └── 2025-01-15/          # Release de janvier 2025
├── radar-business/          # Contenu du radar business (actif)
│   ├── 2025-01-15/          # Release business de janvier 2025
│   ├── config-business.json # Configuration du radar business
│   ├── FORMAT-BLIP.md       # Format des blips business
│   └── README.md            # Documentation du radar business
├── public/                   # Fichiers statiques publics
│   ├── images/              # Images utilisees dans les descriptions
│   ├── logo.svg             # Logo AJR
│   ├── favicon.ico          # Icone du site
│   ├── robots.txt           # Configuration pour les robots
│   ├── strategie-script.js  # Script pour les pages de strategie dynamiques
│   ├── strategie-link.js    # Script alternatif pour les liens strategie
│   ├── team-block-script.js # Script principal pour la page equipe (injection DOM)
│   ├── _team-content        # Contenu HTML de reference pour la page equipe
│   └── team-visualization-data.json  # Donnees JSON pour les visualisations
├── scripts/                  # Scripts utilitaires
│   ├── serve-business.sh    # Script pour servir le radar business en local
│   ├── start-business.sh    # Script de démarrage pour Docker
│   ├── extract-technologies.js  # Extraction des technologies depuis la doc
│   ├── analyze-business-metrics.js  # Analyse des métriques business
│   ├── generate-team-visualization-data.js  # Génération des données équipe
│   ├── create-team-page.sh  # Script pour créer la page équipe
│   └── patch-navigation.sh  # Script pour patcher Navigation.tsx
├── docker/                   # Configuration Docker pour le déploiement
│   ├── Dockerfile           # Image Docker de production
│   ├── docker-compose.yml   # Configuration Docker Compose
│   ├── docker-compose.labels.yml  # Labels pour le déploiement
│   └── docker-compose.local.yml   # Configuration locale
├── docs/                     # Documentation du projet
│   ├── app/                 # Documentation technique de l'application
│   └── data/                # Données métier et contenu
│       └── team/            # Profils individuels des membres de l'équipe
├── radar-app/               # Framework aoe_technology_radar (code vendu dans le repo)
│   ├── src/                 # Code source Next.js du framework
│   │   ├── pages/           # Pages Next.js (routes)
│   │   │   └── team.tsx     # Page /team générée par Dockerfile
│   │   └── components/      # Composants React
│   │       └── Navigation/ # Composant de navigation
│   │           └── Navigation.tsx  # Modifié par Dockerfile pour ajouter le lien Équipe
│   ├── data/                # Données du radar
│   │   ├── config.json      # Configuration (copiée depuis config-business.json)
│   │   └── radar/           # Blips organisés par release
│   │       └── 2025-01-15/  # Blips de la release actuelle
│   └── public/              # Fichiers statiques servis
│       ├── team.html        # Page équipe (copiée depuis public/)
│       └── team-visualization-data.json  # Données équipe (copiée depuis public/)
├── config.json              # Configuration principale du radar (déprécié)
├── custom.css               # Styles personnalisés
├── about.md                 # Page "À propos" du radar
├── package.json             # Dépendances Node.js
├── Dockerfile               # Dockerfile alternatif (racine)
├── Dockerfile.business      # Dockerfile pour le radar business
├── docker-compose.yml       # Docker Compose alternatif (racine)
├── docker-compose.business.yml  # Docker Compose pour le radar business
├── docker-entrypoint.sh     # Script d'entrée Docker
└── .drone.yml               # Configuration CI/CD Drone

Architecture technique

Framework de base

Le projet utilise le framework aoe_technology_radar qui est basé sur :

• Next.js : Framework React pour le rendu côté serveur et la génération statique
• React : Bibliothèque JavaScript pour l'interface utilisateur
• TypeScript : Typage statique pour JavaScript

Processus de build

1. Injection des données : Le script scripts/build-radar.js copie :
   • radar-business/config-business.json → radar-app/data/config.json
   • radar-business/2025-01-15/ → radar-app/data/radar/2025-01-15/
   • public/* → radar-app/public/
   • Génère team-visualization-data.json et le copie dans radar-app/public/
2. Modifications personnalisées :
   • Création de radar-app/src/pages/team.tsx (page Next.js pour /team)
   • Modification de radar-app/src/components/Navigation/Navigation.tsx (ajout du lien Équipe)
   • Modification de radar-app/src/pages/_document.tsx (chargement du script team-block-script.js)
3. Build Next.js : cd radar-app && npm run build:data && npm run build génère les fichiers statiques
4. Output : Fichiers statiques dans radar-app/out/ copiés vers build/ à la racine

Modifications personnalisées

Le projet apporte plusieurs modifications au framework de base :

1. Page Equipe (/team)

• Script principal : public/team-block-script.js (injection du contenu et visualisations)
• Route Next.js : radar-app/src/pages/team.tsx (page vide, le script remplace le contenu)
• Chargement : Le script est charge via _document.tsx avec strategy="beforeInteractive"
• Bibliotheques : Cytoscape.js et ECharts charges depuis CDN
• Donnees : public/team-visualization-data.json genere par scripts/generate-team-visualization-data.js
• Layout : Utilise le layout cose integre a Cytoscape (pas de plugin externe)

2. Navigation modifiée

• Fichier modifié : radar-app/src/components/Navigation/Navigation.tsx
• Modification : Ajout du lien "👥 Équipe" vers /team
• Méthode : Script Python dans Dockerfile.business qui :
  • Supprime tous les liens Équipe existants (évite les doublons)
  • Ajoute un seul lien Équipe après le lien "Vue d'ensemble"

3. Scripts JavaScript désactivés

Les scripts suivants ont été désactivés pour éviter les doublons de liens :

• public/strategie-script.js : addLinksToHeader() désactivée
• public/strategie-link.js : addStrategyLinkToHeader() désactivée

Tous les liens de navigation sont maintenant gérés uniquement par Navigation.tsx.

Format des fichiers radar

Chaque technologie (blip) est définie dans un fichier Markdown avec un en-tête YAML front matter :

---
title: "Nom de la technologie"
ring: adopt|trial|assess|hold
quadrant: technologies-differentiantes|technologies-commodite|technologies-risque|technologies-emergentes
tags: [tag1, tag2]
businessImpact: high|medium|low
costToReplace: 0
revenueImpact: indirect
riskLevel: medium
competencyLevel: beginner
maintenanceCost: 0
differentiation: high
teamCoverage: 1
skillGap: high
---

Description de la technologie en Markdown.

Métadonnées

• title : Nom de la technologie
• ring : Anneau du radar (adopt, trial, assess, hold)
• quadrant : Quadrant du radar (business)
• tags : Tags pour le filtrage (optionnel)
• Métadonnées business : Voir guide-radar-business.md

Flux de traitement

1. Lecture des fichiers : Le framework lit tous les fichiers .md dans radar-business/2025-01-15/
2. Parsing : Extraction des métadonnées YAML et du contenu Markdown
3. Génération : Création d'une application React statique
4. Build : Compilation en fichiers HTML/CSS/JS statiques
5. Serve : Service via un serveur web statique (serve package)

Dépendances principales

• radar-app/ : Framework principal (code vendu dans le repo, basé sur aoe_technology_radar)
• Node.js : Runtime JavaScript (version 20+)
• npm : Gestionnaire de paquets
• gray-matter : Parsing YAML front matter
• postcss : Traitement CSS

Configuration

La configuration principale se trouve dans radar-business/config-business.json et définit :

• Les quadrants et leurs descriptions
• Les anneaux (rings) et leurs significations
• Les couleurs et le style
• Les options d'affichage
• Les métadonnées du site

Voir configuration.md pour plus de détails.

Radar Technologique Laplank

Le Radar Technologique Laplank est un tech radar classique avec :

• Configuration spécifique : radar-business/config-business.json
• Quadrants business : Technologies Différenciantes, Commodité, Risque, Émergentes
• Anneaux classiques : Hold, Assess, Trial, Adopt
• Historique par release : Organisation des technologies par date (radar-business/YYYY-MM-DD/)
• Pages de stratégie : Pages dynamiques générées via public/strategie-script.js
• Protection par mot de passe : Authentification client-side (mot de passe : laplank-radar)
• Base path : / (racine, pas de sous-chemin)
• Page Équipe : /team avec visualisations interactives

Scripts de stratégie

Le fichier public/strategie-script.js contient :

• La logique de protection par mot de passe
• La conversion Markdown vers HTML pour les pages de stratégie
• Le contenu des trois pages de stratégie :
  • Stratégie d'Évolution Technique
  • Stratégie Business
  • Opportunités DataViz Expert

Note : Les fonctions d'ajout de liens dans le header ont été désactivées pour éviter les doublons. Tous les liens sont maintenant gérés par Navigation.tsx.

Build et déploiement

Le projet utilise plusieurs commandes :

• npm run build : Génère les fichiers statiques du radar principal
• npm run serve : Lance un serveur de développement du radar principal (port 3000)
• npm run serve-business : Lance un serveur de développement du radar business (port 3006)
• npm run extract-tech : Extrait les technologies depuis la documentation
• npm run analyze-business : Analyse les métriques business

Le déploiement se fait via Docker avec plusieurs configurations selon l'environnement :

• Radar principal : Via docker/Dockerfile ou Dockerfile
• Radar Technologique Laplank : Via Dockerfile.business et docker-compose.business.yml (Portainer)

Voir deploiement.md pour plus de détails.

Génération des données équipe

Le script scripts/generate-team-visualization-data.js :

• Lit les profils d'équipe depuis docs/data/team/*.md
• Lit les technologies depuis radar-business/2025-01-15/*.md
• Génère public/team-visualization-data.json avec :
  • Données réseau (nodes/edges) pour Cytoscape.js
  • Matrice de congestion pour ECharts (technologies adopt uniquement - anciennement "core")
  • Équipe de genèse MVP avec statistiques (basée sur les technologies adopt)

Ce fichier est utilisé par public/team.html pour les visualisations interactives.

Structure des profils équipe

Les profils d'équipe sont stockés dans docs/data/team/*.md avec le format suivant :

---
name: "pseudo"
fullName: "Nom complet"
role: "Rôle"
availability: 50
seniorityLevel: expert
yearsExperience: 8
joinDate: "2016-01"
interests: ["Mobile", "Infrastructure"]
skills:
  - name: "Flutter"
    level: expert
    years: 4
    lastUsed: "2024-12"
softSkills:
  - "Autonomie"
projects:
  - "Projet1"
---

Voir guide-page-equipe.md pour plus de détails.