sepehr/chartbastan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
chartbastan/_bmad-output/project-context.md
sepehr e02db93960 Initial commit
2026-02-01 09:31:38 +01:00

13 KiB
Raw Blame History

project_name user_name date communication_language document_output_language user_skill_level sections_completed
chartbastan Ramez 2026-01-15T22:00:00.000Z French French intermediate
technology_stack
implementation_patterns
architecture_decisions
project_structure

Contexte de Projet pour Agents AI

Ce fichier contient les règles, patterns et décisions critiques que les agents AI doivent suivre lors de l'implémentation de ce projet.

Stack Technologique

Frontend (Next.js 16)

  • Framework: Next.js 16.0.0 (latest)
  • Language: TypeScript avec strict mode activé
  • Styling: Tailwind CSS v4.0.0 + shadcn/ui (style "new-york")
  • UI Library: shadcn/ui v1.4.4 (canary pour Tailwind v4)
  • API Routes: Node.js (intégré à Next.js) pour APIs légères, authentification
  • Bundler: Turbopack (activé par défaut dans Next.js 16)
  • Port: 3000 (développement), production (Vercel)

Backend (Python FastAPI)

  • Framework: FastAPI 0.128.0 (latest stable)
  • Language: Python 3.10+
  • ORM Primaire: SQLAlchemy 2.0.45 (async support)
  • Documentation: OpenAPI 3.1 (Swagger UI + Redoc)
  • Migrations: Alembic pour les schémas SQLAlchemy
  • Port: 8000 (développement)

State Management

  • État UI Local: Zustand v5.0.9 avec unstable_ssrSafe
  • Données Serveur: React Query (TanStack Query)
  • Pattern: Séparation claire (Zustand pour UI, React Query pour API)

Base de Données

  • Phase 1: SQLite (fichier local, partagé entre FastAPI et Next.js)
  • ORM FastAPI: SQLAlchemy 2.0.45 avec migrations Alembic
  • ORM Next.js: Drizzle ORM v0.44.7 avec better-sqlite3 driver
  • Phase 2+: PostgreSQL (migration planifiée depuis SQLite)

Authentification & Sécurité

  • Solution: Better Auth v1.4.4 (compatible Next.js 16)
  • Authorization: RBAC (Gratuit vs Premium)
  • Session: JWT (stateless) + Secure cookies
  • HTTPS: TLS 1.3 obligatoire en production
  • Headers de Sécurité: CSP, X-Frame-Options, SameSite

Communication Asynchrone

  • Queue: RabbitMQ pour traitement asynchrone
  • Pattern: Producer/Consumer avec events JSON {event, version, timestamp, data, metadata}
  • Usage: Découplage scraping ↔ analyse, gestion des pics de charge

Infrastructure & Déploiement

  • Frontend: Vercel (auto-build, CDN intégré)
  • Backend: Railway ou Render (budget 10-20€/mois Phase 1)
  • CI/CD: GitHub Actions (lint + tests sur PR, auto-deploy)
  • Monitoring Phase 1: Sentry (erreurs), UptimeRobot (uptime)

API Externes

  • Twitter API: 1000 req/heure (gratuit, rate limiting critique)
  • Reddit API: Non limité (généreuse)
  • RSS Feeds: Diverses sources sportives

Décisions Architecturales Critiques

Architecture des Données

  • Database: SQLite Phase 1 → PostgreSQL Phase 2+ (migration planifiée)
  • Naming: snake_case pour tables et colonnes (cohérence SQLAlchemy/Drizzle)
  • Foreign Keys: Format {table}_id (ex: user_id, match_id)
  • Indexes: Format idx_{table}_{column} (ex: idx_users_email)

API & Communication

  • Pattern: RESTful avec OpenAPI 3.1
  • Response Wrapper: {data, meta} (succès) ou {error, meta} (erreur)
  • Date Format: ISO 8601 UTC (ex: "2026-01-15T10:30:00Z")
  • JSON Naming: snake_case dans les réponses API (cohérence avec DB)
  • Rate Limiting: 10 req/min (Gratuit), 100 req/min (Premium)

Frontend Architecture

  • Naming Python: snake_case (fichiers, fonctions, variables, classes PascalCase)
  • Naming TypeScript/JS: camelCase (fonctions, variables), PascalCase (composants, types), kebab-case.tsx (fichiers)
  • Hooks: Préfixe use (ex: useUser(), usePredictions())
  • Constants: UPPER_SNAKE_CASE (ex: MAX_PREDICTIONS_FREE)

Patterns d'Implémentation

  • Organisation du Code: Feature-based avec co-location des tests et composants
  • Gestion d'État: Updates immutables uniquement (jamais mutation directe)
  • Gestion d'Erreurs: Format standardisé avec codes d'erreur et logging à Sentry
  • Server Components: Par défaut, use client uniquement si nécessaire (interactivité, hooks)
  • Async/Await: FastAPI async partout, Next.js Server Components pour réduction bundle

Structure du Projet

Organisation Globale

chartbastan/
├── frontend/          # Next.js 16 Application
├── backend/           # FastAPI Application
├── docs/              # Documentation projet
└── monitoring/         # Prometheus + Grafana (Phase 2+)

Frontend (Next.js)

  • Route: src/app/ (App Router)
  • Composants UI: src/components/ui/ (shadcn/ui copiés localement)
  • Features: src/components/features/ (organisés par domaine fonctionnel)
  • Stores: src/stores/ (Zustand)
  • Hooks: src/hooks/ (React hooks custom)
  • Utils: src/lib/ (helpers, API client, validations Zod)
  • API Routes: src/app/api/ (Next.js API routes pour auth légère)
  • Types: src/types/ (TypeScript types)
  • Tests: tests/ (co-locés ou séparé)

Backend (FastAPI)

  • Routes: app/api/v1/ (REST endpoints)
  • Models: app/models/ (SQLAlchemy)
  • Schemas: app/schemas/ (Pydantic pour validation)
  • Services: app/services/ (logique métier)
  • Repositories: app/repositories/ (couche d'accès aux données)
  • Scrapers: app/scrapers/ (modules de scraping)
  • Workers: app/workers/ (background workers)
  • Queues: app/queues/ (gestion RabbitMQ)
  • ML: app/ml/ (analyse de sentiment, calcul d'énergie)
  • Utils: app/utils/ (logger, validators, formatters)

Conventions de Code & Nommage

Python (FastAPI)

  • Fichiers: snake_case.py (ex: user_service.py, prediction_service.py)
  • Classes: PascalCase (ex: UserService, PredictionService)
  • Fonctions: snake_case (ex: get_user_by_id(), calculate_energy_score())
  • Variables: snake_case (ex: user_id, energy_score, is_premium)
  • Constantes: UPPER_SNAKE_CASE (ex: MAX_PREDICTIONS_FREE, API_RATE_LIMIT)

TypeScript/JavaScript (Next.js)

  • Fichiers Composants: PascalCase.tsx ou kebab-case.tsx (ex: UserCard.tsx, user-card.tsx)
  • Fichiers Utilitaires: camelCase.ts (ex: api.ts, utils.ts, constants.ts)
  • Composants UI: PascalCase (ex: Button, Card, Dialog)
  • Hooks: camelCase avec préfixe use (ex: useUser(), usePredictions())
  • Fonctions: camelCase (ex: getUserById(), calculateEnergyScore())
  • Variables: camelCase (ex: userId, energyScore, isPremium)
  • Constantes: UPPER_SNAKE_CASE (ex: MAX_PREDICTIONS_FREE, API_RATE_LIMIT)

Database (SQLite)

  • Tables: snake_case pluriel (ex: users, predictions, matches, energy_scores)
  • Colonnes: snake_case (ex: user_id, created_at, is_premium)
  • Foreign Keys: {table}_id (ex: user_id, match_id, prediction_id)
  • Indexes: idx_{table}_{column} (ex: idx_users_email, idx_predictions_match_id)

Formats Standards

API REST (FastAPI)

  • Endpoints: Pluriels, snake_case, /api/v1/ (ex: /api/v1/users, /api/v1/predictions)
  • Route Params: Format {id} (ex: /api/v1/users/{id})
  • Query Params: snake_case (ex: ?user_id=123&limit=10)
  • Headers: Préfixe X- pour customs (ex: X-API-Key, X-RateLimit-Remaining)
  • Success Response: 
    {
  "data": { ... },
  "meta": {
    "timestamp": "ISO_8601",
    "version": "v1"
  }
}
  • Error Response: 
    {
  "error": {
    "code": "ERROR_CODE",
    "message": "Message utilisateur-friendly",
    "details": { ... }
  },
  "meta": {
    "timestamp": "ISO_8601",
    "request_id": "id_unique"
  }
}

Events RabbitMQ

  • Event Naming: {entity}.{action} (ex: user.created, prediction.updated, match.analyzed)
  • Format: 
    {
  "event": "prediction.created",
  "version": "1.0",
  "timestamp": "ISO_8601",
  "data": { ... },
  "metadata": {
    "source": "api",
    "user_id": 123
  }
}

JSON dans Frontend/Backend

  • Backend → Frontend: snake_case (cohérence avec DB)
  • Frontend → Backend: camelCase (convertis en snake_case côté serveur)
  • Booléens: true/false (jamais 1/0)
  • Nulls: null (jamais undefined en JSON)
  • Dates: ISO 8601 UTC (ex: "2026-01-15T10:30:00Z")
  • Tableaux: Toujours des arrays (jamais d'objets pour listes)

Patterns de Qualité & Testing

Code Quality

  • Python: PEP 8 compliance, black formatting, type hints obligatoires
  • TypeScript: Strict mode activé, no implicit any
  • Linting:
    • Python: flake8/black
    • TypeScript/Next.js: ESLint avec règles Next.js
  • Testing:
    • Unit: pytest pour Python, Vitest + Testing Library pour React
    • Integration: Tests d'intégration entre services
    • E2E: Playwright pour scénarios utilisateur finaux

Gestion d'Erreurs

  • Logging: Logger structuré en JSON dans tous les services
  • Monitoring: Sentry pour tracking des erreurs en production
  • Error Boundary: React Error Boundaries pour erreurs de rendu
  • Try/Catch: Toujours logger avec contexte avant relancer

Anti-Patterns à Éviter

État

❌ Mutation directe: state.count++ (utiliser setCount(c => c + 1)) ❌ State dans composants: State local dans les composants (utiliser stores globaux)

Nommage

❌ Mixing conventions: user_id (Python) + userId (TypeScript) dans le même fichier ❌ Incohérence: Tables Users dans un endroit, users dans un autre (tout en snake_case pluriel)

API

❌ Response variable: Parfois {data} d'autres fois {error} (toujours wrapper standardisé) ❌ Magic numbers: 1000 dans le code sans constante (utiliser MAX_TWEETS_PER_HOUR) ❌ HTTP status codes: 200 pour succès, 404 pour "not found" (respecter les standards)

Testing

❌ Test manquants: Fonctions sans tests unitaires ❌ Mocks statiques: Données de test en dur dans le code (utiliser factories) ❌ Tests non isolés: Tests qui touchent la base de données ou APIs externes

Points d'Intégration Critiques

Frontend ↔ Backend

  • Communication: HTTP REST via lib/api.ts client
  • Cache: React Query pour synchronisation et cache client
  • Auth: JWT token dans header Authorization: Bearer {token}
  • Conversion: camelCase ↔ snake_case automatique côté frontend

FastAPI ↔ RabbitMQ

  • Pattern: Producer/Consumer avec events JSON
  • Tâches: Scraping, analysis, notifications
  • Workers: Consommateurs asynchrones des tâches RabbitMQ

Base de Données Partagée

  • FastAPI: SQLAlchemy sync sessions
  • Next.js: Drizzle sync queries
  • Partage: SQLite fichier partagé via filesystem (Phase 1)

APIs Externes

  • Twitter: Scraping avec rate limiting (1000 req/heure)
  • Reddit: Scraping sans limite stricte
  • RSS: Scraping de multiples sources sportives

Workflow de Développement

Configuration de l'Environnement

  • Développement: .env.local (jamais commité dans git)
  • Template: .env.example (valeurs placeholder)
  • Variables: Utiliser les variables d'environnement, jamais de secrets en dur

Branching Git

  • Conventions: feature/short-description pour nouvelles fonctionnalités
  • Main: main toujours stable et deployable
  • Release: Tags vX.Y.Z (ex: v1.0.0)

CI/CD (GitHub Actions)

  • On Pull Request: Lint + tests automatiques
  • On Merge: Build + auto-deploy
  • Environnements: Séparés dev/staging/production

Optimisations de Performance

Frontend (Next.js)

  • Server Components: Maximiser pour réduire le bundle client
  • Code Splitting: Par route automatique (App Router)
  • Lazy Loading: Composants lourds (D3.js) avec dynamic imports
  • Image Optimization: Next.js Image component
  • Font: next/font pour optimisation des polices

Backend (FastAPI)

  • Async: Toujours async/await pour I/O operations
  • Database: Requêtes optimisées, indexes appropriés
  • Cache: Phase 2+ : Redis pour données fréquemment accédées
  • Connection Pooling: SQLAlchemy connection pooling (Phase 2+)

Checklist d'Implémentation

Avant de Commiter

  • Code linté (ESLint/flake8)
  • Tests passants (pytest/Vitest)
  • Types corrects (no any implicites)
  • Documentation mise à jour si nécessaire
  • Secrets pas dans le code

Déploiement

  • Variables d'environnement configurées (Vercel/Railway)
  • Base de données attachée
  • Monitoring actif (Sentry)
  • HTTPS activé en production
  • Rate limiting configuré

Ce fichier est la source unique de vérité pour l'implémentation cohérente du projet chartbastan. Tous les agents AI doivent le lire avant d'implémenter du code.