How socialgouv/cdtn-admin works
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.