Architecture

Charly est construit autour d'une architecture monorepo, orchestrée par Turborepo, qui centralise toutes les applications, packages partagés, et outils dans un seul dépôt. Cette approche garantit une gestion cohérente des dépendances, des builds, et des déploiements, tout en facilitant la collaboration entre les différentes parties du projet.

Structure du projet

Le monorepo est organisé en plusieurs dossiers clés, chacun ayant un rôle spécifique :

• apps/
  Ce dossier contient les applications autonomes du projet, chacune avec ses propres dépendances, configurations, et scripts. Les sous-dossiers sont :

  • web/ : L'application web frontend, construite avec React, TypeScript, et Next.js. Elle offre une interface utilisateur moderne utilisant shadcn/ui. Le dossier inclut des composants UI réutilisables (dans components/), des hooks personnalisés (dans hooks/), et une configuration pour le déploiement sur Vercel (dans .vercel/). Les fichiers comme vite.config.ts et eslint.config.js assurent un développement rapide et une qualité de code élevée.
  • cli/ : Un module dédié à l'extraction de données d'événements depuis des plateformes comme Eventbrite. Il inclut des scripts comme fetch-eventbrite-events.ts et scrape-clutch-events.ts pour parser des pages HTML (ex. page1.html) et des utilitaires comme date-parser.ts pour normaliser les formats de date. Les données extraites sont stockées dans des fichiers CSV (ex. events.csv) ou envoyées à la base de données via publish-to-database.ts. Ce module utilise Jest pour les tests unitaires (voir jest.config.js).

• packages/
  Ce dossier regroupe les modules partagés et réutilisables, conçus pour éviter la duplication de code et assurer la cohérence entre les applications. Les sous-dossiers sont :

  • shared/ : Contient des types et utilitaires partagés, comme types.ts, qui exporte des définitions de types pour l'API (ex. le router oRPC). Ce package est importé par les applications web pour garantir une typisation cohérente de bout en bout.
  • db/ : Gère la configuration et les schémas de la base de données avec Drizzle ORM et Zod. Le dossier inclut des fichiers de schéma pour les tables (schema/*.ts) comme events.ts, locations.ts, organizers.ts, et categories.ts, ainsi que des validations Zod correspondantes (dans zod/*.ts). Le fichier drizzle.config.ts configure les migrations et la connexion à PostgreSQL. Des scripts comme db:push et db:migrate (définis dans package.json) facilitent la gestion de la base de données.

• docs/
  Ce dossier contient la documentation du projet, générée avec VitePress. Il inclut des fichiers Markdown comme index.md, introduction.md, et des guides techniques (ex. guide/monorepo.md, guide/api.md). Le fichier config.mts définit la structure de navigation et le thème de la documentation. Les scripts docs:dev et docs:build permettent de visualiser et de compiler la documentation localement. Ce dossier est essentiel pour guider les développeurs dans l'installation, la configuration, et l'utilisation du projet.

• Configuration centrale
  À la racine du monorepo, plusieurs fichiers orchestrent l'ensemble du projet :

  • turbo.json : Configure Turborepo pour gérer les tâches comme build, dev, test, et lint à travers les applications et packages. Il définit des pipelines pour optimiser les builds (ex. mise en cache des outputs dans dist/**) et des tâches spécifiques comme db:push pour les migrations de base de données.
  • package.json : Centralise les dépendances globales (ex. typescript, eslint, vitepress) et définit les scripts monorepo (ex. bun run dev, bun run build). Il spécifie également les workspaces (apps/*, packages/*) pour gérer les dépendances locales.
  • tsconfig.json : Fournit une configuration TypeScript globale, avec des options comme module: ESNext et strict: true pour garantir un code typé et robuste. Les sous-dossiers héritent de cette configuration via extends.
  • .dockerignore et .gitignore : Excluent les fichiers inutiles (ex. node_modules, dist) des builds Docker et des commits Git.
  • docker-compose.yml : Définit les services pour le frontend et le backend, avec des variables d'environnement comme DATABASE_URL et VITE_API_URL pour faciliter le déploiement local ou en production.
  • .github/workflows/docker-build-push.yml : Configure un pipeline CI/CD avec GitHub Actions pour construire et pousser des images Docker vers DockerHub (ex. ayoub981/charly_front, ayoub981/charly_back).

Interactions entre les composants

• L'application web consomme l'API fournie par le backend via des hooks comme use-events.ts et use-locations.ts, qui utilisent le router oRPC défini dans rpc/router.ts.
• Le module cli alimente la base de données (via packages/db) avec des données extraites, qui sont ensuite exposées par l'API du backend.
• Les types définis dans packages/shared et les schémas de packages/db garantissent une cohérence entre le frontend, le backend, et les outils de scraping.
• Turborepo orchestre les builds et les tests, en s'assurant que les dépendances inter-projets (ex. @charly/db, @charly/shared) sont correctement résolues.

Cette structure modulaire et centralisée permet à Charly d'être à la fois scalable et facile à maintenir, tout en offrant une expérience de développement fluide grâce à des outils comme Bun, TypeScript, et Drizzle.