Crystal logo

FluxyCore

Système de traitement de données local (mini ETL)
Ruby orchestre, Crystal exécute les transformations lourdes à grande vitesse.

🚀 Présentation

FluxyCore est un mini‑ETL local conçu pour l’analyse de données et l’automatisation avancée.
Il tire parti de la simplicité de Ruby pour définir des pipelines de traitement (lecture → transformation → export) et de la performance de Crystal pour exécuter les opérations coûteuses (agrégations, parsing de logs, filtrage) de manière native et ultra‑rapide.

Cas d’usage typiques

Analyse de logs systèmes ou applicatifs (Apache, NGINX, custom)
Transformation de fichiers CSV volumineux (ventes, données IoT)
Extraction et mise en forme de données système
Automatisation de rapports locaux sans dépendance externe

🧱 Architecture

┌─────────────┐      pipeline Ruby       ┌────────────────────┐
│   Ruby      │──────────────────────────▶│  Pipeline Ruby     │
│ (orchestre) │                           │  - lit les sources │
└─────────────┘                           │  - génère config   │
                                          │  - lance Crystal   │
                                          └─────────┬──────────┘
                                                    │ stdin (JSON lines)
                                                    ▼
                                          ┌────────────────────┐
                                          │  Binary Crystal    │
                                          │  (transformateur)  │
                                          │  - streaming       │
                                          │  - batch (sort,    │
                                          │    aggregate)      │
                                          └─────────┬──────────┘
                                                    │ stdout (JSON lines)
                                                    ▼
                                          ┌────────────────────┐
                                          │       Ruby         │
                                          │  - écrit sink      │
                                          └────────────────────┘

Ruby : lit les fichiers sources (CSV, JSON, lignes de texte), sérialise les données en flux JSON, appelle le binaire Crystal avec la configuration souhaitée, puis récupère le résultat pour l’écrire dans la destination (CSV, JSON, stdout).
Crystal : reçoit les données ligne par ligne sur stdin, applique les transformations (agrégation, parsing de logs) et renvoie le résultat sur stdout, toujours en JSON lignes.

📦 Installation

Prérequis

Ruby ≥ 3.0 (avec Bundler)
Crystal ≥ 1.9 (installation officielle)

Cloner et compiler

git clone https://github.com/votre-compte/FluxyCore.git
cd FluxyCore
make build          # compile le binaire Crystal → bin/fluxy_transformer
bundle install      # installe les dépendances Ruby

Le binaire compilé bin/fluxy_transformer est indispensable pour les transformations accélérées.

⚡ Utilisation

1. Lancer un pipeline

bin/fluxycore examples/csv_aggregation.rb
bin/fluxycore examples/log_analysis.rb

2. Définir un pipeline (Ruby DSL)

require 'fluxycore'

FluxyCore.pipeline do
  source :file, path: 'data/ventes.csv', format: :csv
  transform :aggregate, group_by: 'produit', sum: 'montant', count: true
  sink :csv, path: 'output/resultat.csv'
end

3. Transformations disponibles

Transformation	Description
`aggregate`	Groupement + somme, moyenne, comptage (accéléré par Crystal)
`parse_logs`	Extraction de champs depuis des logs Apache combined (Regex)
Bloc Ruby custom	Transformations arbitraires via `transform {

4. Sources & sinks supportés

Sources :

:file (format :csv, :json, :lines)
:inline (tableau Ruby passé directement)

Sinks :

:csv, :json (écrit dans un fichier)
:stdout (affichage formaté)

🧪 Tests

Lancer tous les tests

make test

Ceci exécute :

Les tests Ruby (MiniTest) : bundle exec ruby test/test_pipeline.rb
Les tests Crystal (spec) : cd src/crystal && crystal spec

Tester individuellement

# Ruby
bundle exec ruby test/test_pipeline.rb

# Crystal
cd src/crystal && crystal spec

Linting

make lint

Vérifie le style Ruby via RuboCop et Crystal via Ameba.

🐳 Docker

Une image Docker prête à l’emploi est disponible.

Construire l’image

make docker-build

Exécuter un pipeline avec Docker

make docker-run

Par défaut, cela lance examples/csv_aggregation.rb.
Montez vos propres volumes pour traiter vos fichiers :

docker run --rm \
  -v $(pwd)/mes_données:/app/data \
  -v $(pwd)/mes_sorties:/app/output \
  fluxycore examples/mon_pipeline.rb

🔄 CI/CD

Un workflow GitHub Actions est fourni (.github/workflows/ci.yml).
Il exécute à chaque push et PR :

Installation de Ruby et Crystal
Linting (RuboCop + Ameba)
Compilation du binaire Crystal
Tests unitaires Ruby et Crystal

Les badges de statut peuvent être ajoutés dans ce README une fois le dépôt configuré.

📂 Structure du projet

FluxyCore/
├── bin/
│   ├── fluxycore              # Lanceur Ruby
│   └── fluxy_transformer      # Binaire Crystal (généré par la compilation)
├── lib/
│   └── fluxycore/             # Code source Ruby (pipeline, runner, source/sink/transform)
├── src/crystal/               # Code source Crystal (transformateurs + spec)
├── examples/                  # Pipelines d'exemple
├── test/                      # Tests Ruby
├── Makefile
├── Dockerfile
├── Gemfile
└── .github/workflows/ci.yml  # CI GitHub Actions