---
stepsCompleted: [1, 2, 3, 4, 5]
inputDocuments:
  - README.md
  - frontend/README.md
date: 2026-02-18
author: Sepehr
---

# Product Brief: office_translator

<!-- Content will be appended sequentially through collaborative workflow steps -->

## Executive Summary

Office Translator doit faire l'objet d'une **refonte complète** pour aligner le produit sur les vrais besoins : une API et une interface de traduction de documents (Excel, Word, PowerPoint) **robustes**, **sécurisées** et **maintenables**. La vision porte sur une simplification du scope (abandon des LLMs, focus sur la traduction classique), une révision de l'UX, un backend épuré sans code mort ni fonctionnalités superflues, et une base technique solide pour la suite. L'application est destinée à être **déployée en production** avec un **système d'abonnement** (monétisation) ; le rôle **admin** est **essentiel** au bon fonctionnement et doit être inclus dans la refonte.

---

## Core Vision

### Problem Statement

L'état actuel du logiciel accumule de la dette technique, des fonctionnalités peu ou plus pertinentes (dont la gestion multi-LLMs) et une expérience utilisateur à revoir. Le backend et le frontend méritent une refonte pour atteindre un niveau de robustesse et de sécurité adapté à un usage sérieux (y compris SaaS), tout en réduisant la complexité pour les mainteneurs et les utilisateurs.

### Problem Impact

Sans refonte : maintenance coûteuse, risques de bugs et de failles, complexité inutile (ex. gestion des LLMs) qui distrait de la valeur principale (traduction fiable avec préservation du format). Les utilisateurs et les développeurs subissent une UX et une codebase en dessous des objectifs de qualité et de sécurité.

### Why Existing Solutions Fall Short

La solution actuelle mélange trop de fournisseurs (Google, Ollama, WebLLM, DeepL, LibreTranslate, OpenAI) et une couche LLM (prompts, glossaires, modèles vision) qui complique le cœur métier. Les parties « traduction classique » et « préservation du format » sont la vraie valeur ; le reste ajoute de la surface d'attaque et du code mort ou peu pertinent sans apport proportionnel.

### Proposed Solution

- **Refonte backend** : simplifier et sécuriser. Conserver et renforcer la traduction via fournisseurs classiques (Google, DeepL, LibreTranslate, etc.) et **retirer complètement la gestion des LLMs** (Ollama, WebLLM, OpenAI). Supprimer le code mort et les fonctionnalités non pertinentes.
- **Refonte frontend / UX** : revoir l’expérience utilisateur de bout en bout pour qu’elle soit claire, cohérente et orientée traduction de documents.
- **Robustesse et sécurité** : renforcer la validation, la gestion des erreurs, les en-têtes de sécurité, l’auth admin, et les bonnes pratiques (rate limiting, nettoyage des fichiers, logs).

### Key Differentiators

- **Focus traduction documentaire** : un produit centré sur la traduction de documents Office avec préservation du format, sans la complexité des LLMs.
- **Codebase épurée** : moins de surface d’attaque, moins de chemins de code inutiles, maintenance et évolution plus simples.
- **Robustesse et sécurité** : architecture et pratiques pensées pour la fiabilité et un déploiement SaaS serein.

---

## Target Users

### Primary Users

**Mainteneur / utilisateur principal (vous)**  
- Contexte : utilisation et maintenance du produit au quotidien.  
- Problème vécu : la logique de certains enchaînements est difficile à suivre ; des textes sont mal placés ou dupliqués (deux versions du même texte), ce qui nuit à la cohérence. Besoin de retrouver facilement les informations et de comprendre les flux.  
- Objectif de succès : une interface et une codebase où les parcours sont clairs, les textes sont unifiés et cohérents, et les informations sont faciles à trouver. Les performances doivent être améliorées **sans dégrader** la qualité actuelle (traduction correcte et préservation du format). Les prompts système liés à la traduction doivent être revus pour plus de pertinence et de cohérence.

**Utilisateur final (personne qui traduit des documents)**  
- Contexte : utilisation de l’API ou du frontend pour traduire des documents Office.  
- Besoin : trouver facilement les informations (options, statut, aide), comprendre les étapes sans ambiguïté, obtenir un résultat fiable et rapide.  
- Objectif de succès : une expérience fluide, des libellés et parcours cohérents, pas de doublons ni de textes contradictoires.

**Admin (rôle essentiel)**  
- Contexte : exploitation et pilotage de l’application en production ; rôle **indispensable** au bon fonctionnement du service.  
- Besoin : surveiller la santé du système (santé, disque, mémoire), gérer le nettoyage des fichiers, suivre les limites de débit et l’usage, et — dans le cadre d’un **modèle SaaS avec abonnements** — superviser ou gérer les abonnements et l’activité.  
- Objectif de succès : un tableau de bord admin robuste, sécurisé et cohérent avec le reste de l’UX, permettant de faire tourner l’application et le business sereinement. La refonte doit **inclure** l’admin, pas le traiter en option.

### Secondary Users

Aucun autre segment secondaire prioritaire pour cette refonte ; les trois rôles ci-dessus (mainteneur, utilisateur final, admin) couvrent le cœur du produit.

### User Journey

- **Découverte / prise en main** : comprendre rapidement à quoi sert le produit et comment lancer une traduction.  
- **Usage courant** : déposer un document, choisir la langue et les options (sans confusion entre plusieurs versions de texte), lancer la traduction, récupérer le fichier.  
- **Succès** : document traduit fidèlement (format préservé), sans se heurter à des incohérences de libellés ou à une logique d’enchaînement obscure.  
- **Contraintes à respecter** : améliorer les performances tout en conservant le comportement actuel qui « fonctionne bien et traduit bien les documents en gardant la forme initiale ». Revoir les prompts système pour la traduction.

---

## Deployment & Monetization (à ne pas oublier)

- **Déploiement** : l’application est destinée à être **déployée en production** ; la refonte doit tenir compte du déploiement (sécurité, config, monitoring, admin).  
- **Monétisation** : objectif de **gagner de l’argent** avec le produit ; un **système d’abonnement** existe ou est prévu. La refonte doit préserver ou renforcer la capacité à facturer (abonnements, limites, usage) et à faire fonctionner l’admin en support de ce modèle business.

---

## Success Metrics

### Succès côté utilisateur

L’application **réussit** pour un utilisateur quand :
- **Rapidité** : la traduction se fait rapidement (performance).
- **Qualité** : la personne obtient un document **très bien traduit**, au point de **ne pas avoir à faire de modifications elle-même** (qualité « prête à l’emploi »).
- **Recommandation** : l’utilisateur est **content au point de faire de la pub** pour l’application dans son entourage (bouche-à-oreille, recommandation).

En résumé : traduction rapide + qualité suffisante du premier coup + satisfaction qui pousse à recommander.

### Business Objectives

Les objectifs business précis (revenus, nombre d’abonnés, horizons 3 mois / 12 mois) ne sont pas fixés aujourd’hui et seront à affiner au fil du déploiement et des retours terrain (« pas de boule de cristal »). La refonte doit en revanche **rendre possible** la monétisation (abonnements) et un pilotage via l’admin, pour que ces métriques puissent être définies et suivies plus tard.

### Key Performance Indicators

- **Utilisateur** : temps de traduction (à améliorer vs. aujourd’hui), qualité perçue (pas / peu de retouches), intention de recommander ou retours qualitatifs du type « j’en ai parlé autour de moi ».
- **Business** : indicateurs à définir lorsque le déploiement et le modèle d’abonnement seront en place (ex. abonnés actifs, revenus récurrents, disponibilité).

---

## MVP Scope

### Objectif de cette version

**Refactoriser et améliorer le code actuel, puis déployer.** Une version V2 est envisagée plus tard ; pour l’instant, livrer cette version refondue, robuste et prête pour la production et les abonnements.

### Core Features (dans le MVP)

- **Backend** : code refactorisé et épuré (suppression du code mort, sortie des LLMs). Traduction via fournisseurs classiques (Google, DeepL, LibreTranslate, etc.) avec préservation du format. Performance améliorée sans régression sur la qualité de traduction. Configuration centralisée (ex. Pydantic BaseSettings), gestion d’erreurs et validation renforcées.
- **Frontend / UX** : parcours clairs, textes cohérents (une seule version par message), informations faciles à trouver. Alignement avec les bonnes pratiques Next.js (performance, Core Web Vitals).
- **Admin** : tableau de bord essentiel au bon fonctionnement (santé, disque, mémoire, rate limit, nettoyage, abonnements si déjà en place). Inclus dans la refonte, pas en option.
- **Sécurité & déploiement** : rate limiting adapté au SaaS, en-têtes de sécurité, auth admin robuste, logs structurés. Prêt pour un déploiement production et un modèle abonnements.

### Out of Scope for MVP

- **LLMs** : retirés complètement (Ollama, WebLLM, OpenAI) dans cette version.
- **V2** : nouvelles fonctionnalités majeures ou nouveaux marchés sont hors scope ; focus sur refonte + déploiement de l’existant amélioré.

### MVP Success Criteria

- Code actuel refactorisé et amélioré ; déploiement réussi.
- Traduction rapide et de qualité (document bien traduit, pas de retouches nécessaires), format préservé.
- Utilisateur et admin peuvent accomplir leurs tâches sans confusion (logique des flux, textes cohérents).
- Base solide pour activer / faire évoluer le système d’abonnement et mesurer les KPIs plus tard.

### Future Vision (V2 et au-delà)

- V2 : nouvelles capacités, nouveaux segments ou intégrations, selon les retours et les métriques post-déploiement.
- Évolution du produit guidée par l’usage réel et les objectifs business affinés progressivement.

---

## Propositions d'amélioration (à considérer)

Ces pistes s’appuient sur le brief, la structure actuelle du projet et des bonnes pratiques (FastAPI, Next.js, SaaS). À prioriser selon le temps et les objectifs.

### Backend (FastAPI)

- **Structure par domaine** : grouper par domaine métier (ex. `translation/`, `admin/`, `auth/`, `subscription/`) avec router, schemas, service, dépendances par domaine, plutôt que tout en `main.py`, pour une base plus lisible et évolutive.
- **Configuration** : centraliser la config dans un module Pydantic `BaseSettings` (`.env`, validation des types), et y déplacer les variables admin / Redis / rate limit pour éviter les `os.getenv` dispersés.
- **Async** : privilégier l’async de bout en bout (routes, services) et réserver le thread pool aux appels sync inévitables (ex. certaines libs de documents) pour de meilleures perfs sous charge.
- **Sécurité** : garder rate limiting (token bucket / sliding window), CORS strict en prod, secrets hors du code. Envisager des limites par abonnement (tier) et un circuit breaker en cas de surcharge ou timeout fournisseur de traduction.
- **Observabilité** : logs structurés (déjà en partie en place), métriques (ex. temps de traduction, erreurs par endpoint), et optionnellement health checks détaillés pour le déploiement.

### Frontend (Next.js)

- **Performance** : viser de bons Core Web Vitals (LCP &lt; 2,5 s, INP &lt; 200 ms, CLS &lt; 0,1). Utiliser `next/image` et `next/font`, Server Components par défaut, `'use client'` uniquement où nécessaire. Analyser le bundle avec `@next/bundle-analyzer` et réduire les dépendances lourdes ou dupliquées.
- **UX et cohérence** : un seul libellé par concept (plus de deux versions du même texte). Parcours clairs : upload → options → traduction → téléchargement. Placeholder et états de chargement explicites pour éviter les décalages de layout (CLS).
- **Admin** : même langage visuel et mêmes patterns que le reste de l’app ; navigation et hiérarchie d’information claires pour que l’admin trouve rapidement les infos (santé, usage, abonnements).

### SaaS & déploiement

- **Rate limiting / quotas** : distinguer limites court terme (burst) et quotas long terme (ex. traductions/mois par abonnement). Documenter les limites dans l’API et les refléter dans l’admin.
- **Abonnements** : s’assurer que le modèle abonnements (déjà présent en base) est bien branché à l’auth et aux limites d’usage, et que l’admin peut suivre l’activité et les comptes.
- **CI/CD et déploiement** : pipeline de build + tests + déploiement (ex. Docker, reverse proxy HTTPS). Checklist pré-déploiement : secrets, CORS, HSTS si HTTPS, rotation des logs.

Ces propositions peuvent alimenter un backlog de tâches techniques une fois le brief validé.
