Socialflow/_bmad-output/planning-artifacts/architecture.md

stepsCompleted, inputDocuments, workflowType, project_name, user_name, date

stepsCompleted	inputDocuments	workflowType	project_name	user_name	date
1 2 3 4 5 6	_bmad-output/planning-artifacts/prd.md package.json shared/schema.ts	architecture	Socialflow	Michael	2026-01-20

Architecture Decision Document

This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together.

Project Context Analysis

Requirements Overview

Functional Requirements: Le système doit évoluer pour intégrer deux modules critiques :

1. Gestion des Tokens (Critique) : Un système robuste de renouvellement automatique des tokens Facebook Page est nécessaire pour éviter les interruptions de service (expiration ~60 jours).
2. Analytics & Recommandations : Un nouveau sous-système pour ingérer, stocker et analyser les métriques Facebook (Insights API) et fournir des recommandations simples (règles métier).

Non-Functional Requirements:

• Fiabilité : Le job de renouvellement de token est le point de défaillance unique (SPOF) à sécuriser absolument.
• Isolation des données : L'architecture multi-tenant actuelle doit être strictement appliquée aux nouvelles données analytiques.
• Performance : Les dashboards doivent rester rapides (<2s) malgré l'historisation croissante des données.

Scale & Complexity:

• Primary domain: Web App B2B (Social Media Management)
• Complexity level: Moyenne (L'authentification OAuth et les APIs tierces ajoutent de la complexité accidentelle).
• Estimated architectural components: 3 majeurs (TokenManager, AnalyticsIngestor, RecommendationEngine).

Technical Constraints & Dependencies

• Facebook Graph API : Dépendance forte. Besoin de gérer les rate limits et les erreurs transitoires.
• Drizzle ORM : Le schéma doit être étendu pour supporter les nouvelles métriques sans casser l'existant.
• Architecture existante : On ne réécrit pas, on étend. Les nouveaux services doivent s'intégrer dans le pattern Service/Controller existant.

Cross-Cutting Concerns Identified

• Gestion des erreurs et Retries : Critique pour les appels API Facebook.
• Logging & Monitoring : Essentiel pour savoir si le renouvellement de token a échoué silencieusement.
• Sécurité des Credentials : Stockage sécurisé des tokens (chiffrement au repos recommandé par NFRs).

Starter Template Evaluation (Brownfield Context)

Project Status: Brownfield (Existing Codebase) Decision: Keep existing stack. No new starter template needed.

Existing Architecture Stack

Primary Technology Domain: Full-Stack Web Application (Node.js/React)

Architectural Decisions Already in Place:

Language & Runtime:

• Runtime: Node.js
• Language: TypeScript (Strict mode)

Frontend Stack:

• Framework: React 18
• Build Tool: Vite
• Routing: Wouter (Client-side)
• State Management: TanStack Query (React Query)
• Styling: Radix UI + Tailwind CSS

Backend Stack:

• Server: Express.js
• Database: PostgreSQL
• ORM: Drizzle ORM
• Auth: Passport.js (Session based)

Infrastructure:

• Deployment: Docker (Containerized)
• Media Storage: Cloudinary

Decision: The new features (Analytics, Token Automations) will simply extend this existing mature architecture. No migration required.

Core Architectural Decisions

Decision Priority Analysis

Critical Decisions (Block Implementation):

1. Token Refresh Strategy: Must be automated and robust (SPOF).
2. Analytics Schema Design: Must support efficiently querying historical data.
3. Job Scheduling: How to reliable trigger daily tasks in this stack.

Important Decisions (Shape Architecture):

1. Facebook Service Refactoring: Split monolithic service vs maintain as is.
2. Recommendation Engine Logic: Hardcoded heuristics vs External AI.

Data Architecture

Schema Extensions (Drizzle ORM):

• New Tables:
  • postAnalytics: Stockage des snapshots de métriques (impressions, clicks, etc.) liés à posts.
  • pageAnalyticsHistory: Snapshots journaliers des followers par page.
• Modifications:
  • socialPages: Ajout de champs de statut (tokenStatus, lastTokenCheck).
• Migration Strategy: Drizzle Kit (drizzle-kit push ou migration files).

Authentication & Security

Token Management:

• Encryption: Les tokens sont sensibles.
  • Décision: Chiffrement au repos via une utilité encrypt/decrypt (AES-256) avant insertion en DB, transparent pour le service applicatif.
• Refresh Mechanism:
  • Décision: Utilisation d'un endpoint API dédié sécurisé (/api/cron/refresh-tokens) appelé par un CRON externe (type GitHub Actions ou service d'hébergement) ou un scheduler in-process (type node-cron) si déploiement persistant.
  • Choix Brownfield: node-cron pour simplicité du déploiement Docker unique actuel.

API & Communication Patterns

Facebook Integration:

• Service Layer:
  • Création de AnalyticsService.ts séparé de FacebookService.ts pour éviter le God Object.
  • Abstraction commune GraphAPIClient pour gérer les appels HTTP, rate limits et erreurs.
• Frontend-Backend:
  • Nouveau routeur analytics.routes.ts.
  • Cache: React Query sur le frontend (staleTime 5min) pour éviter le spam F5 sur les analytics.

Infrastructure & Deployment

Job Scheduling (CRON):

• Pattern: In-process scheduling via node-cron.
  • Avantage: Pas de nouvelle infrastructure requise.
  • Inconvénient: Si le serveur redémarre, le job peut sauter un tour (acceptable pour un refresh journalier avec marge de 7 jours).

Decision Impact Analysis

Implementation Sequence:

1. Schema Update: Créer les tables Analytics et mettre à jour SocialPages.
2. Token Manager: Implémenter le chiffrement et le service de renouvellement.
3. Cron Job: Configurer node-cron pour le check quotidien.
4. Analytics Ingestion: Service pour puller les data de FB vers DB.
5. Analytics API: Exposer les données au front.
6. UI: Dashboard Analytics.

Implementation Patterns & Consistency Rules

Pattern Categories Defined

Critical Conflict Points Identified:

• Naming: Drizzle (snake_case DB) vs API (camelCase JSON).
• Service Structure: Business Logic placement (Controller vs Service).
• Error Handling: Silent fails in Cron Jobs vs User Feedback in UI.

Naming Patterns

Database Naming Conventions (Drizzle):

• Tables: snake_case plural (ex: post_analytics)
• Columns: snake_case (ex: followers_count)
• Foreign Keys: snake_case ending with _id (ex: page_id)

API Naming Conventions (REST):

• Endpoints: Kebab-case plural resources (ex: /api/analytics/posts-insights)
• JSON Props: camelCase (ex: followersCount - necessitates transformation from DB snake_case)

Code Naming Conventions:

• Services: TopicService.ts containing class TopicService
• Interfaces: PascalCase, generally not prefixed with 'I' in TS modern patterns (ex: FacebookInsight)

Structure Patterns

Project Organization:

• Services: server/services/*.ts - Business logic enabling re-use.
• Routes: server/routes.ts - HTTP handlers, params validation, calling services.
• Schema: shared/schema.ts - Centralized Drizzle schema & Zod types.

Communication Patterns

Async Jobs (Cron):

• Logging: All cron jobs MUST log start/finish/error with timestamp.
• State: Jobs extending socialPages status must update last_token_check timestamp.

Process Patterns

Error Handling:

• External APIs (FB/IG):
  • Never crash the server on API failure.
  • Wrap calls in try/catch.
  • Throw typed application errors (FacebookApiError) for upstream handling.

Enforcement Guidelines:

All AI Agents MUST:

1. Use db.insert(...).returning() pattern for creations.
2. Use Zod schemas from shared/schema.ts for validation.
3. Encrypt sensitive tokens before saving using encrypt() utility.

Project Structure & Boundaries

Complete Project Directory Structure

Socialflow/
├── package.json
├── tsconfig.json
├── server/
│   ├── index.ts                # App entry point
│   ├── routes.ts               # Main router (delegates to sub-routers)
│   ├── services/
│   │   ├── facebook.ts         # Legacy Facebook service
│   │   ├── analytics.ts        # [NEW] Analytics logic (fetch insights)
│   │   ├── token_manager.ts    # [NEW] Token encryption & refresh logic
│   │   └── recommendation.ts   # [NEW] Recommendation engine
│   └── routes/
│       └── analytics.routes.ts # [NEW] Analytics specific endpoints
├── client/src/
│   ├── App.tsx                 # Main frontend component
│   ├── pages/
│   │   ├── Dashboard.tsx       # Existing Dashboard
│   │   └── analytics/          # [NEW] Analytics Section
│   │       └── AnalyticsPage.tsx
│   ├── components/
│   │   ├── analytics/          # [NEW] Shared Analytics Components
│   │   │   ├── StatCard.tsx
│   │   │   ├── FollowersChart.tsx
│   │   │   └── PostsTable.tsx
│   │   └── ui/                 # Existing UI components (Radix)
│   └── lib/
│       ├── api.ts              # API client
│       └── queryClient.ts      # React Query config
├── shared/
│   └── schema.ts               # Drizzle Schema & Zod Types
└── migrations/                 # Drizzle migrations

Architectural Boundaries

API Boundaries:

• Endpoints: /api/analytics/* (Protected by requireAuth)
• Internal Services: Services communicate securely; AnalyticsService calls FacebookService only if necessary, prefers direct API calls via GraphClient.

Component Boundaries:

• Frontend: AnalyticsPage is the orchestrator. Contains StatCard, Charts.
• State: React Query manages server state (caching insights). Local state for UI filters (date range).

Requirements to Structure Mapping

Feature/Epic Mapping: Analytics Module:

• Backend: server/services/analytics.ts + server/routes/analytics.routes.ts
• Frontend: client/src/pages/analytics/
• Data: post_analytics, page_analytics_history (in schema.ts)

Token Management Module:

• Service: server/services/token_manager.ts
• Job: server/jobs/token_refresh_job.ts (Scheduled via node-cron in server/index.ts)
• Data: social_pages (extended fields)

Integration Points

External Integrations:

• Facebook Graph API: Accessed via server/utils/graph_client.ts (to be created for standardized access).
• Cron System: node-cron initialized in server/index.ts triggers TokenManager.checkAndRefreshTokens().

Architecture Validation Results

Coherence Validation ✅

• Pattern Consistency: The service-based architecture aligns with the existing Express/Drizzle stack.
• Structure Alignment: New analytics.ts and token_manager.ts fit naturally into server/services.

Requirements Coverage Validation ✅

• Critical (Token Refresh): Covered by TokenManager.checkAndRefreshTokens() + encryption.
• Critical (Analytics): Covered by new schema + AnalyticsService.
• Security: Encryption at rest addresses strict NFRs.

Architecture Readiness Assessment

Overall Status: READY FOR IMPLEMENTATION Confidence Level: High

Implementation Handoff

AI Agent Guidelines:

• Strictly follow camelCase for JSON and snake_case for DB.
• Use Zod schemas for all validation.
• Do not bypass the encryption utility for token storage.

First Implementation Priority: Initialize modules: npx drizzle-kit push (after schema update) -> TokenManager setup.