Documentation Technique AMN

Bienvenue sur le portail documentaire de l’écosystème AMN. Ce hub centralise l’ensemble des connaissances techniques, guides d’architecture, modèles de données et protocoles d’intégration du projet.

1. Architecture Globale

Le projet repose sur une architecture moderne par couches (3-Tier Edge Architecture), garantissant une haute performance, une sécurité stricte et une observabilité complète :

graph TD
    subgraph L2 ["L2 : Présentation & Frontend"]
        Astro[Astro SSR sur Edge]
        Starlight[Documentation Starlight]
        Search[Algolia DocSearch Bimodal]
    end

    subgraph L1 ["L1 : Contenu & Médias"]
        Sanity[Sanity Studio Headless]
        VisualEditing[Visual Editing Stega]
        R2[Cloudflare R2 & Storage]
    end

    subgraph L3 ["L3 : Backend & Sécurité"]
        Workers[Cloudflare Workers API]
        Queues[Cloudflare Queues Submissions]
        Auth[Better Auth D1 & KV]
    end

    Astro --> Sanity
    Astro --> Workers
    Starlight --> Auth
    Workers --> Queues

2. Organisation par Couches

Couche L1 — Contenu & Gestion des Médias

Centralise la gouvernance et le stockage des données :

Sanity Studio v3 : Modèles de données, types de documents (page, post, author, category) et composants de mise en page.
Visual Editing & Stega : Édition visuelle en temps réel intégrée directement dans le frontend Astro via token sécurisé.
Stockage Cloudflare : Pipeline de téléchargement direct pour Cloudflare Images, R2 et Stream.

Couche L2 — Présentation & Frontend

Gère l’expérience utilisateur et le rendu dynamique :

Astro SSR sur Cloudflare Workers : Rendu serveur haute performance à l’edge.
PageBuilder Modulaire : Composants réutilisables (Hero, Features, Testimonials, CTA, RichText, ImageGallery).
Documentation Bimodale Starlight : Expérience adaptée selon l’état d’authentification avec séparation étanche des index Algolia DocSearch.

Couche L3 — Backend & Services Edge

Assure le traitement métier et la résilience :

Workers Spécialisés : form-handler (validation et producteur de messages) et submission-processor (consommateur asynchrone).
Asynchronisme résilient : Cloudflare Queues pour découpler les soumissions utilisateur de Sanity.
Identité & Sécurité : Better Auth avec persistance Cloudflare D1 et mise en cache Cloudflare KV.

3. Accès & Niveaux de Visibilité

La documentation propose deux niveaux de lecture selon votre profil :

Profil	Accès Visibles	Recherche DocSearch	Authentification
Visiteur Public	Guides d’ensemble, `.objectData`, `.template`	Index public épuré	Aucune (libre)
Membre Authentifié	Intégralité des documents, `SPEC`, `ADR` internes	Index complet étendu	Bouton Connexion (Header)

[!TIP] Vous êtes collaborateur du projet ?
Cliquez sur le bouton Connexion situé en haut à droite du bandeau de navigation pour révéler l’ensemble des spécifications et indicateurs avec le badge Privé.

4. Guides de Démarrage Rapide

Édition Visuelle Sanity : Visual Editing with Astro
Objets & Données Composants : Header Object Data
Configuration Cloudflare : Configuration Backend
Validation du Système : Guide de Test Navigation Bimodale