Architecture - Jichio

Jichio repose sur une règle stricte : toute la logique de capture, de file, de batch et d’envoi vit dans @jichio/core. Chaque environnement d’exécution expose un adaptateur fin qui branche les hooks de la plateforme sans dupliquer le pipeline.

Vue d’ensemble

SDK JS (navigateur)                    App Android (Kotlin, natif — V3)
   │  batch + retry (file offline)          │  batch + retry (file offline, Room)
   ▼                                        ▼
            API d'ingestion (Python, FastAPI)
                   │  déduplication par UUID (ON CONFLICT DO NOTHING)
                   ├────────────────► Redis (cache lecture, rate limiting futur)
                   ├────────────────► Minio (stockage objets — exports, avatars, screenshots heatmap)
                   ▼
            ClickHouse (events bruts + agrégats)
                   │
                   ├────────────────► Postgres (métadonnées : projets, funnels, recommandations)
                   ├────────────────► Dashboard (Next.js + Shadcn/Tailwind)
                   └────────────────► Job digest IA (cron, appelle Claude) ──► recommandations (Postgres)

Core + adaptateurs

packages/sdk/
  core/         @jichio/core      — logique cœur (capture, file, envoi)
  react/        @jichio/react     — adaptateur React / Next.js
  wordpress/    @jichio/wordpress — plugin WordPress (bundle UMD)
  vanilla/      @jichio/vanilla   — (V2) script UMD / sites statiques
  angular/      @jichio/angular   — (V2+) adaptateur Angular

Package	Responsabilité	Dépend de
sdk-core	`track()` / `identify()` / `page()`, file offline, batch, retry, auto-capture DOM	`@jichio/shared-types`
sdk-react	`AnalyticsProvider`, pageviews SPA (App Router / React Router), réexport de l’API core	`sdk-core`, `react` (peer)
sdk-wordpress	Injection du script, page admin (clé, endpoint), auto-capture WP	`sdk-core` (UMD)

Règle stricte : aucune logique de file, de retry ou de format d’événement dans les adaptateurs — uniquement du wiring (lifecycle, routing, injection HTML). Toute évolution du pipeline passe par sdk-core.

Le pipeline d’un événement

Étape	Responsable	Règle
Capture	core (+ adaptateur pour la route SPA)	Manuel (`track`) ou auto (pageview, click)
Enrich	core `buildEvent()`	Profils de capture conditionnels
Persist	file IndexedDB (core)	Avant toute tentative réseau
Schedule	core `FlushScheduler`	Timer 5 s ou seuil 10 événements
Send	core `sendBatch()`	`POST /v1/events`
ACK	API → core	Purge uniquement les `eventIds` confirmés
Retry	core backoff	Stop sur 401/403, conserve la file

En savoir plus : Offline-first et Modèle d’événement.

Couche serveur

Composant	Choix	Rôle
API d’ingestion	Python / FastAPI	Ingestion (`X-API-Key`) + lecture dashboard (JWT)
Events bruts	ClickHouse (`MergeTree`)	Insertion en masse, agrégations (funnels, rétention)
Métadonnées	Postgres	Projets, funnels, recommandations, utilisateurs
Cache	Redis	Cache de lecture des agrégats dashboard
Stockage objets	Minio (S3-compatible)	Exports, avatars, screenshots privés de heatmap
Capture de page	Playwright / Chromium	Screenshot headless de `website_url + path` pour l’overlay heatmap
IA	Claude (Anthropic)	Digest périodique → recommandations

apps/web (dashboard) ne parle jamais directement à ClickHouse ou Postgres. Il passe toujours par l’API d’ingestion/lecture. Cela isole le moteur de stockage derrière une couche stable.

Enrichissement serveur

Certaines données ne sont jamais collectées côté client : elles sont injectées par l’API à l’ingestion dans properties.server (IP publique, hash d’IP, géolocalisation, ingestedAt, requestId). Voir Modèle d’événement.