# Lucarne : documentation technique

> **Une fenêtre ouverte sur les laboratoires : la promesse au visiteur.**

**Lucarne** (anciennement _Saclay Research_) est un socle open source de **vitrine publique de la recherche**, configurable par établissement (« marque blanche »). Il rend les laboratoires, les chercheurs, les projets et les expertises d'une université visibles et trouvables, à partir des **données ouvertes de la recherche**. Deux instances sont livrées : **Université Paris-Saclay**, commanditaire, et **Université Paris 1 Panthéon-Sorbonne**, pour éprouver la marque blanche.

Pas de base de données, pas de serveur applicatif : **tout est calculé au build**. Les pages lisent des JSON sur le disque, la recherche s'exécute chez le visiteur.

## 🪟 Les instances en ligne

<InstanceGrid />

Les établissements candidats et la façon d'en ajouter un : [Plan des instances](/plan).

---

## 🗺️ L'architecture en un schéma

Dix sources ouvertes sont moissonnées telles quelles, fusionnées par identifiant pérenne, publiées en JSON versionnés ; un site Next.js est généré statiquement à partir de ces fiches, indexé par Pagefind, et servi par Vercel ou en auto-hébergement. Une instance n'est qu'un fichier de configuration et deux logos.

<Mermaid
  title="Architecture de Lucarne : des sources ouvertes aux visiteurs"
  caption="Chaque flèche est une commande ou un fichier du dépôt. Les volumes sont ceux de l'instance Paris-Saclay, mesurés le 28/10/2026."
  chart={`flowchart TB
  subgraph SRC["Sources ouvertes de la recherche"]
    direction LR
    RNSR["RNSR · MESR<br/>référentiel des structures"]
    SCANR["scanR · MESR<br/>personnes, projets, descriptions"]
    HAL["HAL · CCSD<br/>publications, domaines, mots-clés"]
    ANN["Annuaire de l'établissement<br/>liste maître, présentations"]
    AUTRES["ROR · Wikidata · ORCID<br/>OpenAIRE · theses.fr · OpenAlex"]
  end

subgraph CFG["Instance (marque blanche)"]
CONF["instances/&lt;id&gt;/research.config.ts<br/>charte · périmètre · groupes · thématiques · sources"]
end

subgraph CHAIN["Chaîne de données · scripts/data"]
direction LR
EXT["pnpm data:extract<br/>moisson, ≈ 20 min"]
RAW[("data/raw/&lt;instance&gt;<br/>NDJSON bruts · 2,1 Go · non versionné")]
BUILD["pnpm data:build<br/>fusion par identifiant pérenne, ≈ 45 s"]
PUB[("data/public/&lt;instance&gt;<br/>JSON publiés · 18 Mo · versionné")]
FREEZE["pnpm data:freeze / data:verify<br/>référence figée dans tests/reference"]
end

subgraph SITE["Site statique · Next.js 16 · React 19 · Mantine"]
direction LR
NEXT["next build<br/>23 696 pages, fr et en"]
PF["Pagefind<br/>index de recherche, dans le navigateur"]
end

subgraph HOST["Hébergement"]
direction LR
VERCEL["Vercel<br/>un projet par instance, build &lt; 4 min"]
SELF["Auto-hébergement<br/>artefact standalone, Kubernetes"]
end

subgraph OPS["Exploitation"]
direction LR
PROM["Prometheus · Grafana · Blackbox<br/>/api/metrics, 3 tableaux, 10 alertes"]
MATOMO["Matomo<br/>audience sans cookie"]
end

VIS(("Visiteurs<br/>entreprises, presse,<br/>étudiants, financeurs"))

SRC --> EXT --> RAW --> BUILD --> PUB --> NEXT --> PF
PUB -.-> FREEZE
CONF --> EXT
CONF --> BUILD
CONF --> NEXT
NEXT --> VERCEL
NEXT --> SELF
VERCEL --> VIS
SELF --> VIS
SELF -.->|"/api/metrics + jeton"| PROM
VIS -.->|"pages vues, recherches"| MATOMO`}
/>

---

## 🧭 Explorer la documentation

<FeatureGrid cols={4}>
  <FeatureCard
    icon="🧭"
    title="Projet"
    description="Origine, journal daté de ce qui a été fait et appris, plan d'action, questions ouvertes, validations à obtenir, méthode de travail."
    badge="Projet"
    href="/projet"
  />
  <FeatureCard
    icon="🛤️"
    title="Projection"
    description="La trajectoire des données : sources ouvertes récupérées à la main, branchement à CRISalid Paris-Saclay, prochain test sur ses données."
    badge="Projection"
    href="/projection"
  />
  <FeatureCard
    icon="🗺️"
    title="Plan"
    description="Une adresse par établissement sous lucarne.vicode.fr : les instances en service, les onze candidats du consortium CRISalid, la mise en ligne."
    badge="Plan"
    href="/plan"
  />
  <FeatureCard
    icon="🏗️"
    title="Architecture"
    description="Stack technique, chaîne de données, marque blanche, recherche : comment le socle est construit et pourquoi."
    badge="Technique"
    href="/architecture"
  />
  <FeatureCard
    icon="🗄️"
    title="Données"
    description="Les dix sources ouvertes, leurs identifiants et licences, la couverture mesurée, le rattachement aux Graduate Schools."
    badge="Technique"
    href="/donnees"
  />
  <FeatureCard
    icon="🎨"
    title="Interface"
    description="Charte en quatre couleurs et deux polices, jetons CSS, catalogue Storybook, audit UX et ce qu'il reste à reprendre."
    badge="Technique"
    href="/interface"
  />
  <FeatureCard
    icon="🚀"
    title="Exploitation"
    description="Déploiement Vercel (un projet par instance), observabilité Prometheus et Matomo, runbook."
    badge="Exploitation"
    href="/exploitation"
  />
  <FeatureCard
    icon="🛡️"
    title="Sécurité"
    description="Cartographie des surfaces réseau, politique de dépendances, inventaire SPDX des licences."
    badge="Exploitation"
    href="/securite"
  />
  <FeatureCard
    icon="📊"
    title="Analytics"
    description="POC de mesure d'audience et d'observabilité auto-hébergées : Umami, Matomo, Rybbit, OpenObserve."
    badge="Exploitation"
    href="/analytics"
  />
  <FeatureCard
    icon="⚖️"
    title="Décisions"
    description="Quatorze décisions d'architecture, numérotées et datées, avec leur statut : acceptée, provisoire, remplacée."
    badge="Décisions"
    href="/decisions"
  />
</FeatureGrid>

---

## ⚡ Trois entrées pour arriver vite

<FeatureGrid cols={3}>
  <FeatureCard
    icon="🧱"
    title="S'orienter dans le dépôt"
    description="La pile, les dossiers, les trois paquets autonomes et les commandes avec leurs durées mesurées."
    href="/architecture/stack-technique"
  />
  <FeatureCard
    icon="📓"
    title="Savoir ce qui a été fait"
    description="Le journal : chaque étape datée, les mesures, et surtout ce que chaque correctif a appris."
    href="/projet/journal"
  />
  <FeatureCard
    icon="⚠️"
    title="Voir ce qui bloque et ce qui mord"
    description="Blocages qui ne dépendent pas de nous, blocages à nous, et les pièges par domaine."
    href="/projet/points-d-attention"
  />
</FeatureGrid>

---

## 🔁 Les workflows, du poste de travail au déploiement

<Mermaid
  title="Cycle de vie d'une mise à jour des données"
  caption="La moisson n'est jamais dans le chemin d'un déploiement : Vercel construit le site à partir des JSON versionnés."
  chart={`sequenceDiagram
  autonumber
  participant Dev as Poste de travail
  participant Src as Sources ouvertes
  participant Git as Dépôt Git
  participant Hook as Lefthook (pre-push)
  participant Vercel as Vercel

Dev->>Src: pnpm data:extract (≈ 20 min, 11 sources)
Src-->>Dev: data/raw/«instance» (NDJSON, manifest.json)
Dev->>Dev: pnpm data:links, puis pnpm data:build (≈ 45 s)
Dev->>Dev: pnpm data:freeze (référence figée)
Dev->>Git: commit data/public + tests/reference
Dev->>Hook: git push
Hook->>Hook: données déployables ? référence respectée ? make check
Hook-->>Git: push accepté
Git->>Vercel: webhook
Vercel->>Vercel: node scripts/vercel-build.mjs (next build, index Pagefind ajouté par l'adaptateur)
Vercel-->>Dev: déploiement, moins de 4 min`}
/>

---

## 🔒 Principes

- **Sources ouvertes, brut conservé.** Chaque source est copiée telle quelle avant toute fusion ; on peut toujours remonter à ce qu'elle a dit ([ADR 008](/decisions/chaine-de-donnees-ouvertes)).
- **Corriger dans la source, jamais localement.** La vitrine ne porte aucune donnée saisie à la main ; une erreur se corrige chez celui qui la publie ([ADR 001](/decisions/source-de-verite)).
- **Mesurer avant d'affirmer.** Chaque chiffre de cette documentation est mesuré, et dit quand il ne l'est pas ([méthodologie](/projet/methodologie)).
- **Aucune donnée personnelle ne sort vers un tiers.** Matomo sans cookie, métriques fermées par jeton, termes de recherche nettoyés ([observabilité](/exploitation/observabilite)).
- **Licence MIT**, à confirmer par l'établissement avant toute reprise externe ([ADR 014](/decisions/licence)).