# socialgouv/cdtn-admin architecture

> Architecture diagram of the GitHub repository socialgouv/cdtn-admin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/socialgouv/cdtn-admin
- Repository: https://github.com/socialgouv/cdtn-admin

## Overview

The project is a full-stack, multi-service administration tool built as a monorepo using yarn workspaces. Its purpose is to manage and administer the “Code du travail numérique” content by ingesting data from multiple external sources into a central database (via Hasura), tracking changes between different releases (alert-cli), and then exporting that content to ElasticSearch for search capability, all while providing an administration UI via a Next.js frontend.

##### Main Components
- Hasura & Postgres Database: The core data layer that stores document content (and associated audit, migration, and configuration data). Hasura provides a GraphQL interface and integrates audit triggers.
- Ingester Service: A service that fetches data from various external sources (such as @SocialGouv/fiches-travail-data, @SocialGouv/legi-data, etc.) and injects the latest releases into the database via Hasura.
- Alert-CLI: A change-detection component. It compares current external content releases with previous versions and logs any differences (diffs) into the DB.
- Export-Elasticsearch: A service responsible for exporting data from Postgres/Hasura to an ElasticSearch instance. It exposes an API (and CLI triggers) for triggering those exports.
- Frontend (Administration UI): A Next.js based admin site that allows users to manage content, trigger exports, and update deployment environments.
- External Dependencies: Services for authentication (tiptap token integration), and third-party external sources for content.

##### Relationships and Interactions
- The Ingester Service retrieves external content packages (via JSON releases) and loads them into Hasura/Postgres. It runs as a CLI command in development mode.
- Alert-CLI continuously compares releases from external systems and registers any content diff into the DB.
- Export-Elasticsearch interacts with Postgres/Hasura (using environment-configured endpoints such as HASURA_GRAPHQL_ENDPOINT) to export data into ElasticSearch. The API can be triggered by both CLI and admin actions.
- The Frontend fetches data from Hasura’s GraphQL API (and potentially from ElasticSearch for search) and provides an interface to configure data, trigger exports, and link to various deployment environments.
- Docker Compose orchestrates many of these services (e.g., Hasura, Postgres, minio, ElasticSearch) along with the administrative containers.

##### Architectural Patterns and Design Principles
- Microservices / Modular Architecture: Each target (ingester, alert-cli, frontend, export-elasticsearch, hasura) is a self-contained service that communicates over APIs and through shared databases.
- Containerization: Docker Compose files and Dockerfiles indicate how individual components are packaged and deployed.
- GitHub-based versioning and monorepo organization: Each target is a yarn workspace within a monorepo with clearly separated codebases.
- Data Pipeline Flow: The ingestion pipeline (external sources → ingester → Hasura/Postgres → export-elasticsearch → ElasticSearch) should be highlighted, as well as the feedback/control loop from the frontend.

##### Relevant Technologies
- Languages/Frameworks: JavaScript/TypeScript, Next.js (frontend), Node.js services, Hasura GraphQL Engine.
- Infrastructure: Docker and Docker Compose orchestration, Kubernetes (indirectly for production management), and direnv for environment variable management.
- Tools: yarn workspaces, ESLint configurations, and automated CI workflows from GitHub Actions.

##### Detail and Clarity
- As many essential architectural components as possible: versioning, service dependencies, and environment configurations.
- Do not shy away from splitting the system into separate components if it aids clarity; each component (ingester, alert-cli, hasura, frontend, export-elasticsearch) is fundamental to the system’s operation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    ext["External Sources (fiches-travail-data, legi-data, etc.)"]:::external
    token["Tiptap Token Integration"]:::external

    %% Services
    subgraph "Services"
        ingester["Ingester Service"]:::service
        alert["Alert-CLI"]:::service
        export["Export-Elasticsearch"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        db["Hasura & Postgres Database"]:::database
        elastic["ElasticSearch"]:::database
    end

    %% UI Layer
    ui["Frontend (Administration UI)"]:::ui

    %% Orchestration & CI/CD
    dock["Docker Compose & CI/CD"]:::orchestration

    %% Data Flow Connections
    ext -->|"fetchData"| ingester
    token -->|"auth"| ingester
    ingester -->|"ingestData"| db
    alert -->|"compareReleases"| db
    db -->|"triggerExport"| export
    export -->|"exportData"| elastic
    ui -->|"fetchGraphQL"| db
    ui -->|"triggerExport"| export
    dock --> ingester
    dock --> alert
    dock --> export
    dock --> db
    dock --> elastic
    dock --> ui

    %% Click Events
    click db "https://github.com/socialgouv/cdtn-admin/tree/master/targets/hasura"
    click ingester "https://github.com/socialgouv/cdtn-admin/tree/master/targets/ingester"
    click alert "https://github.com/socialgouv/cdtn-admin/tree/master/targets/alert-cli"
    click export "https://github.com/socialgouv/cdtn-admin/tree/master/targets/export-elasticsearch"
    click ui "https://github.com/socialgouv/cdtn-admin/tree/master/targets/frontend"

    %% Class Definitions for Colors
    classDef external fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef service fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
    classDef database fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef ui fill:#F5CBA7,stroke:#7D6608,stroke-width:2px;
    classDef orchestration fill:#D7BDE2,stroke:#512E5F,stroke-width:2px;
```
