Projet 36 - "toggl-pg-mirror — Agréger mon historique de temps dans PostgreSQL"

Date de la création de cette note : 2026-04-27.

Quel est l'objectif de ce projet ?

Construire un proxy Toggl : un service Node.js (avec SvelteKit si une interface devient nécessaire) qui centralise mes données de time-tracking dans une base PostgreSQL que je contrôle.

Avoir une base de données PostgreSQL toujours à jour avec l'intégralité de mon historique Toggl, pour pouvoir l'utiliser comme source de vérité — notamment pour brancher un LLM dessus et générer des bilans temporels (par semaine, par mois, par activité).

Contrainte fondamentale : ne pas casser mon workflow de saisie actuel. Je continue à utiliser Toggl normalement.

Pourquoi je souhaite réaliser ce projet ?

J'utilise Toggl depuis trois ans pour tracker mon temps — via l'application desktop et surtout l'application mobile. Toggl est une solution propriétaire, et je veux pouvoir exploiter mes données de façon autonome : les enrichir, les corriger, les interroger avec un LLM, les conserver indépendamment de la plateforme.

Modèle de données

Deux tables principales :

time_entries (état courant)

  • id — identifiant interne
  • toggl_uid — identifiant source Toggl
  • started_at, ended_at — datetime de début et de fin
  • tags — liste de tags (état courant)
  • description — titre/description courte (état courant)

time_entry_audit_log (historique des modifications)

  • id — identifiant interne
  • entry_id — référence vers time_entries
  • source — origine de la modification (toggl, manual, llm)
  • field_changed — champ concerné
  • old_value, new_value — avant / après
  • changed_at — timestamp de la modification

Le principe clé : conserver la donnée brute intacte et tracer chaque modification avec sa source. Les données importées de Toggl sont marquées source: toggl, les corrections manuelles source: manual, et les corrections automatiques source: llm. Cela permet de ne jamais perdre ce qui a été saisi à la main, tout en gardant une traçabilité complète de l'évolution de chaque entrée. C'est le principe Bronze de l'Architecture à médaillon appliqué via un audit log : les événements source: toggl jouent le rôle du Bronze, les corrections celui de l'Argent.

Implémentation — Première itération

Deux fonctionnalités, dans cet ordre :

  • [ ] Import de l'historique — Une commande CLI qui lit un export Toggl (format JSON) et insère les données dans PostgreSQL. Cela inclut la modélisation du schéma et la mise en place des migrations.
  • [ ] Sync périodique par polling — Un scheduler qui interroge régulièrement l'API Toggl Track (ex: toutes les 10 min) pour récupérer les nouvelles entrées et combler d'éventuels événements manqués (notamment après un redémarrage du service). Cette approche est volontairement implémentée avant les webhooks : elle ne nécessite pas d'endpoint public et est plus simple à tester en local.

Pas d'API HTTP pour l'instant — accès direct SQL. Le schéma doit néanmoins être conçu pour accueillir une API REST dans le futur.

Contraintes liées au plan Free :

  • Quota API Track : 30 requêtes/heure par utilisateur (1 req/sec rate limit)
  • Webhooks : 1 webhook max, 3 types d'événements max
  • Le polling toutes les 10 min consomme ~6 req/h, ce qui laisse de la marge

Évolutions futures

  • Corrections automatiques via LLM (tags, descriptions) — en s'appuyant sur la séparation données brutes / données corrigées
  • Serveur MCP pour interroger les données depuis un agent IA
  • Interface web (SvelteKit)
  • API HTTP au-dessus de la base
  • Webhooks pour la synchronisation temps réel (en complément du polling comme filet de sécurité)
  • Édition bidirectionnelle optionnelle (proxy ⇄ Toggl)
  • Transition éventuelle vers une solution de saisie alternative à Toggl

Repository de ce projet :

Ressources :

Priorité immédiate : avoir le pipeline d'import + sync opérationnel. Tout le reste vient après.

Quitter le mode Zen