Grabb.AI MVP

Architecture & Design

Plateforme moderne • Modulaire • Multi-tenant

Expérience autonome en moins de 10 minutes

Vision & Objectif MVP

10 minutes

De la connexion QuickBooks à des insights exploitables

Je me connecte

Un clic, autorisation QuickBooks, c'est fait

Mes données arrivent

36 mois d'historique importés automatiquement

J'obtiens des insights

RFM, Momentum, recommandations prêtes à utiliser

Je prends des décisions

Interface intuitive, données présentées selon mon intention

Pas juste des tables, mais des insights exploitables et actionnables

Principe clé : User-Intended Data

Notre frontend transforme les données brutes en informations exploitables, présentées selon l'intention utilisateur plutôt que sous forme de tables techniques

Zéro configuration • Zéro attente • Zéro intervention humaine

Architecture Globale

OAuth Broker

cldObd modifié

Backend API

FastAPI + JWT

Workers ETL

Python + Prefect

Frontend

React + MUI

Databases

grabb_etl + grabb_app

Prefect

Orchestration

Serveur

Infrastructure

Normes & Standards

Qualité de code

8 modules indépendants mais orchestrés ensemble

Module 1: OAuth Broker

Composant existant

cldObd modifié pour notre usage

Gère l'OAuth2 QuickBooks Online

Récupère refresh_token + realmId

Envoie événement au backend: /webhook/qbo-connected

Ne parle pas directement à la DB

Module 2: Backend API

Stack Technique

FastAPI Pydantic v2 SQLAlchemy 2.0 Alembic JWT stateless

Gère:

Auth: JWT Access + Refresh
utilisateurs, organisations
datasources, plans, subscriptions
statuts de jobs (backfill, sync)
Crée les jobs ETL
Déclenche Prefect pour backfill

Ne fait PAS:

Ingestion QBO
Normalisation
Enrichissement
Cron

UV - Gestionnaire de paquets Python

Performance ultra-rapide

Écrit en Rust, UV est 10-100x plus rapide que pip pour l'installation et la résolution de dépendances

Résolution de dépendances fiable

Résout les conflits de dépendances de manière déterministe, évite les problèmes de compatibilité

Gestion complète de l'environnement

Gère les environnements virtuels, les dépendances, et les lock files (pyproject.toml + uv.lock)

Compatible avec l'écosystème Python

Compatible avec pip, pip-tools, poetry. Utilise les mêmes formats standards (pyproject.toml)

Pourquoi UV ? Accélère le développement avec des installations instantanées et une meilleure gestion des dépendances pour un projet Python moderne.

Module 3: Workers ETL

Python + Prefect

Rôles:

Exécuter les jobs du backend
Ingestion QBO (backfill + delta)
Normalisation vers modèle canonique
Calcul RFM, Momentum, KPIs
Mise à jour cursors & logs

Structure:

worker/
  main.py
  flows/
    backfill_qbo.py
    sync_daily_qbo.py
  adapters/
    qbo_adapter.py
  engine/
    normalize.py
    enrich.py
    insights.py

Écriture dans: grabb_etl (raw) + grabb_app (canonique)

Architecture à Deux Bases

grabb_etl

Raw + ETL Admin

Schémas:

raw_qbo (raw customer, raw item, raw invoice)
etl_admin (job, sync_cursor, audit_log)

Structure flexible, JSON brut, ingestion rapide

grabb_app

Canonique + Analytics

Schémas:

core: app_user, org, org_user, datasource
billing: feature, plan, plan_feature, subscription
client: customer, rfm, momentum
product: item, category (à venir)
fx: kpi, insight, recommendation (à venir)
api: vues optimisées pour le backend

Tables propres, normalisées, partitionnées par org_id

Modèle Multi-Tenant

Clé: org_id (UUID)

Chaque table importante contient org_id

Backend

Filtre TOUJOURS par org_id dans toutes les requêtes

Workers

Écrivent toujours avec org_id + datasource_id

Sécurité

Isolation complète entre organisations

Flow de Données

QBO API

raw_qbo

normalize

client.*
product.*
(données normalisées)

enrich
(calculs RFM, KPIs, etc.)

client.*
(RFM, momentum)

fx.*
(KPIs, insights)

api.*

backend

frontend

Pipeline complet de données brutes vers insights exploitables

Frontend - React

Stack

React 18 Vite TypeScript Material UI TanStack Query Zustand React Hook Form Zod i18next

Architecture Feature-Based:

Développement par fonctionnalités

Chaque feature (onboarding, insights, clients) contient ses propres composants, hooks et logique métier

Shared Components

Quand plusieurs features ont besoin du même composant, on le place dans components/shared/ pour la réutilisation

Avantage: Isolation des features, réutilisabilité des composants communs, maintenance facilitée

JWT:

Access token: 15 minutes
Refresh token: 7-30 jours
Middleware Axios pour refresh automatique

Cohérence des Types dans le Stack

Un seul point de vérité : Les schémas DB définissent les types pour tout le stack

PostgreSQL

Schémas DB définis

customer_id UUID
org_id UUID
created_at TIMESTAMP

SQLAlchemy

Modèles Python

customer_id: UUID
org_id: UUID
created_at: datetime

Pydantic

Schémas API

customer_id: UUID
org_id: UUID
created_at: datetime

Frontend

Types TypeScript

customerId: string
orgId: string
createdAt: Date

Avantages

Synchronisation

Types toujours à jour entre DB et Frontend

Moins d'erreurs

Validation automatique à chaque niveau

Développement

Autocomplétion et type-safety partout

Sécurité

Validation des données à l'entrée API

Implémentation

Backend

SQLAlchemy models → Tables DB
Pydantic schemas → Validation API
Auto-génération OpenAPI/Swagger

Frontend

Pull des types depuis l'API
Génération TypeScript depuis OpenAPI
Zod pour validation côté client

Résultat : Un changement dans la DB se propage automatiquement jusqu'au Frontend via les modèles SQLAlchemy et Pydantic

Normes & Standards

Qualité de code et cohérence : Règles et outils pour maintenir un code propre et standardisé

Frontend

ESLint

Linting et détection d'erreurs

Plugins React, TypeScript, Prettier
Règles strictes pour hooks React
Détection variables non utilisées
Interdiction console.log (sauf warn/error)

Prettier

Formatage automatique du code

Style uniforme (80 caractères, 2 espaces)
Double quotes, point-virgule obligatoire
Formatage automatique sur commit
Intégration avec ESLint

TypeScript Strict Mode

Vérification stricte des types

Mode strict activé (6 vérifications)
Interdiction du type any
Variables non utilisées = erreur
Imports de types explicites requis

Pre-commit Hooks

Validation automatique avant commit

Husky + lint-staged
ESLint + Prettier sur fichiers modifiés
Commit bloqué si erreurs critiques
Corrections automatiques quand possible

Règles Spécifiques

Pas de any : Typage explicite obligatoire
i18n obligatoire : Tous les textes utilisent les traductions
Variables non utilisées : Préfixe _ ou suppression
Conventions : camelCase (vars), PascalCase (composants), UPPER_SNAKE_CASE (constantes)

Récapitulatif

Avant commit

ESLint + Prettier + TypeScript vérifiés automatiquement

Interdit

any, texte en dur, variables non utilisées

Obligatoire

i18n pour tous les textes utilisateur

Automatique

Formatage et corrections sur commit

Backend

Ruff

Linting et formatage Python

Remplace Black, isort, flake8, pylint
Performance exceptionnelle (écrit en Rust)
Règles PEP 8, pyflakes, bugbear
Modernisation automatique du code

Pre-commit Hooks

Validation automatique avant commit

Ruff check + format sur fichiers modifiés
Corrections automatiques incluses
Commit bloqué si erreurs critiques
Formatage automatique dans VS Code

Règles Actives

PEP 8 : Style de code Python standard
pyflakes : Détection imports/variables non utilisés
bugbear : Détection de bugs potentiels
pyupgrade : Modernisation (typing.List → list)
isort : Tri automatique des imports

Récapitulatif

Ruff unique

Un seul outil pour linting + formatage

Avant commit

Ruff check + format automatiquement

Auto-correction

Modernisation et corrections automatiques

Formatage

100 caractères max, doubles quotes, PEP 8

Base de Données

Conventions de Nommage

Standards PostgreSQL

Tables : snake_case pluriel (ex: app_users)
Colonnes : snake_case (ex: org_id, created_at)
Schémas : par domaine (core, billing, client, etc.)
Contraintes : nommées explicitement

Types & Contraintes

Structure et intégrité

UUID pour les IDs primaires
Timestamps avec timezone (TIMESTAMPTZ)
Contraintes NOT NULL, UNIQUE, FOREIGN KEY
Index sur org_id pour multi-tenant

Alembic Migrations

Gestion des versions de schéma

Migrations versionnées et réversibles
Schémas synchronisés avec SQLAlchemy
Rollback possible en cas de problème
Cohérence entre environnements

Règles Spécifiques

org_id obligatoire : Toutes les tables importantes ont org_id
Timestamps standardisés : created_at et updated_at partout
Types appropriés : VARCHAR avec limite pour champs attendus (email, nom), TEXT pour contenu variable (descriptions, JSON brut)
Index stratégiques : Sur colonnes fréquemment filtrées (org_id, foreign keys)

Récapitulatif

Nommage

snake_case pour tables et colonnes

Multi-tenant

org_id + index sur toutes les tables importantes

Timestamps

created_at et updated_at standardisés

Migrations

Alembic pour versionner les changements

Résultat : Code cohérent, maintenable et de qualité professionnelle

Prefect

Pourquoi Prefect ?

Scheduler intégré

Planification automatique des jobs ETL (sync quotidiens, tâches récurrentes) sans avoir besoin de cron

Webhooks & API

Déclenchement de flows depuis le backend via API/webhooks. Le backend peut lancer des backfills à la demande

UI de monitoring

Interface web pour visualiser l'état des flows, les logs, les erreurs et l'historique d'exécution

Gestion d'erreurs robuste

Retry automatique, gestion des échecs, notifications et observabilité complète des workflows

Code Python pur

Définition des workflows en Python natif, pas de YAML complexe. Intégration naturelle avec notre stack Python

Open-source & scalable

Solution open-source, extensible et prête pour la production. Support de multiples workers et environnements

Prefect - Configuration

Prefect open-source sur serveur Ubuntu
UI accessible via reverse proxy (URL dédiée)
Workers Prefect sur le même serveur
Backfills → déclenchés par backend
Sync quotidiens → programmés dans Prefect

Serveur - Rôle & Architecture

Rôle du Serveur

Hébergement

Héberge tous les composants de l'application

Base de Données

PostgreSQL local pour grabb_etl et grabb_app

Workers ETL

Exécution des jobs Prefect et traitement des données

Orchestration

Prefect Server pour gérer les workflows ETL

Spécifications

Fournisseur: OVH Dedicated

OS: Ubuntu 22.04 LTS

Type: Serveur dédié

Composants sur le Serveur

Frontend

Application React servie via Nginx

Backend API

FastAPI avec gestion des processus via systemd

PostgreSQL

Deux bases: grabb_etl et grabb_app

Prefect Server

UI et API pour orchestration des workflows

Prefect Workers

Exécution des flows ETL (backfill, sync)

Nginx

Reverse proxy, SSL/TLS, routing

https://app.grabb.ai/

Sécurité & Configuration

Secrets: Stockés dans /etc/grabb/.env
Accès: Prefect UI accessible via reverse proxy Nginx (URL dédiée)
SSL: Let's Encrypt (certificats automatiques)
Firewall: Configuration réseau sécurisée
Monitoring: Logs système et application

Évolution Future

Workers Prefect: Possibilité d'ajouter des workers Prefect sur d'autres serveurs au besoin facilement
Secrets: Migration vers 1Password/Doppler
Backup: Stratégie de sauvegarde automatisée

Datasources & Plans

Datasources

Table core.datasource (9 colonnes):

datasource_id

org_id

source_type (qbo, woo, amz, etc.)

status

display_name

external_ref

config_json (tokens + settings)

created_at

updated_at

Modèle scalable → possibilité d'extraire vers tables spécifiques plus tard

Plans & Subscriptions

Schéma billing avec 4 tables:

feature

Définition des fonctionnalités disponibles

plan

Plans disponibles (free, pro, premium, etc.)

plan_feature

Relation entre plans et fonctionnalités

subscription

Abonnements actifs des organisations

MVP: Un plan "free" pour tous les nouveaux comptes
Plus tard: Pro / Premium avec limites de features
Backend détermine plan depuis subscription active
Frontend montre/masque selon plan.access_json

Conclusion

Notre Vision

10 minutes de connexion QuickBooks à des insights exploitables

Données présentées selon l'intention utilisateur, pas juste des tables brutes

Stack Technique Moderne

UV pour gestion de dépendances ultra-rapide
Prefect : scheduler, webhooks, UI de monitoring
Architecture feature-based avec shared components
Cohérence des types DB → Backend → Frontend

Scalabilité & Flexibilité

Multi-tenant avec isolation par org_id
Workers Prefect distribuables sur plusieurs serveurs
Architecture modulaire pour nouveaux connecteurs
Deux bases : raw (ETL) + canonique (analytics)

Qualité & Maintenabilité

Standards de code (ESLint, Prettier, pre-commit)
Type-safety de bout en bout
8 modules indépendants mais orchestrés
Code propre et maintenable pour l'équipe

Collaboration Équipe

Chaque module indépendant → contribution sans conflits
Frontend, Backend, ETL peuvent travailler en parallèle
Architecture claire = rapidité de développement
Prêt pour l'expansion (WooCommerce, Amazon, etc.)

Objectif : Construire une plateforme moderne, scalable et maintenable, prête pour la production et l'expansion future

Merci !

Crédits

Fait par Félix...

OK non...

Pensé par Félix, fait par Cursor

Présentation PLG1

Présentation dans :

Grabb.AI MVP

Architecture & Design

Vision & Objectif MVP

Je me connecte

Mes données arrivent

J'obtiens des insights

Je prends des décisions

Principe clé : User-Intended Data

Architecture Globale

OAuth Broker

Backend API

Workers ETL

Frontend

Databases

Prefect

Serveur

Normes & Standards

Module 1: OAuth Broker

Composant existant

Module 2: Backend API

Stack Technique

Gère:

Ne fait PAS:

UV - Gestionnaire de paquets Python

Module 3: Workers ETL

Python + Prefect

Rôles:

Structure:

Architecture à Deux Bases

grabb_etl

Schémas:

grabb_app

Schémas:

Modèle Multi-Tenant

Clé: org_id (UUID)

Backend

Workers

Sécurité

Flow de Données

Frontend - React

Stack

Architecture Feature-Based:

JWT:

Cohérence des Types dans le Stack

PostgreSQL

SQLAlchemy

Pydantic

Frontend

Avantages

Synchronisation

Moins d'erreurs

Développement

Sécurité

Implémentation

Backend

Frontend

Normes & Standards

Frontend

ESLint

Prettier

TypeScript Strict Mode

Pre-commit Hooks

Règles Spécifiques

Récapitulatif

Backend

Ruff

Pre-commit Hooks

Règles Actives

Récapitulatif

Base de Données

Conventions de Nommage

Types & Contraintes

Alembic Migrations

Règles Spécifiques

Récapitulatif

Prefect

Pourquoi Prefect ?

Prefect - Configuration