docs/architecture.md

Lin - LinkedIn Community Manager Brownfield Enhancement Architecture

Change Log

Change	Date	Version	Description	Author
Initial Draft	2025-10-20	1.0	Initial architecture document for UI/UX improvements, keyword analysis, and FLUX.1-dev image generation enhancements	Architect

1. Introduction

This document outlines the architectural approach for enhancing Lin with UI/UX improvements, keyword relevance analysis, and upgraded image generation capabilities. Its primary goal is to serve as the guiding architectural blueprint for AI-driven development of new features while ensuring seamless integration with the existing system.

Relationship to Existing Architecture: This document supplements existing project architecture by defining how new components will integrate with current systems. Where conflicts arise between new and existing patterns, this document provides guidance on maintaining consistency while implementing enhancements.

1.1 Existing Project Analysis

Based on my analysis of your project, I've identified the following about your existing system:

• The application is a LinkedIn community management tool with React frontend and Flask backend
• Uses Supabase for authentication and database
• Has established AI content generation using Gradio client
• Current image generation uses Qwen/Qwen-Image model
• Well-structured with clear separation of concerns between frontend and backend
• Has established API patterns and Redux state management

Please confirm these observations are accurate before I proceed with architectural recommendations.

Current Project State

• Primary Purpose: LinkedIn community management tool with AI-powered content generation
• Current Tech Stack: React (frontend), Flask (backend), Supabase (database/auth), Gradio client (AI integration)
• Architecture Style: Microservices-like with clear separation between frontend and backend
• Deployment Method: Docker with docker-compose, with Nginx reverse proxy

Available Documentation

• README.md: Complete project documentation with setup instructions
• Backend README.md: Detailed backend API documentation
• Frontend README.md: Frontend development guide
• docs/prd.md: Product requirements document

Identified Constraints

• Must maintain backward compatibility with existing user workflows
• Authentication system is based on JWT tokens and Supabase
• Image generation currently uses Qwen model through Gradio client
• Existing API patterns must be preserved

2. Enhancement Scope and Integration Strategy

2.1 Enhancement Overview

Enhancement Type: UI/UX Overhaul, New Feature Addition, Integration with New Systems Scope: UI/UX improvements to the dashboard, keyword relevance analysis feature, replacement of current image generation with FLUX.1-dev Integration Impact: Medium Impact (requires changes to existing code but maintains compatibility)

2.2 Integration Approach

Code Integration Strategy: Follow existing patterns and conventions in the codebase Database Integration: No schema changes required, leveraging existing tables API Integration: Extend existing API endpoints while maintaining compatibility UI Integration: Enhance existing UI components following established design patterns

2.3 Compatibility Requirements

• Existing API Compatibility: All new endpoints must follow existing authentication patterns
• Database Schema Compatibility: No schema changes required, using existing tables
• UI/UX Consistency: Follow existing design system and component patterns
• Performance Impact: Maintain current performance characteristics

3. Tech Stack

3.1 Existing Technology Stack

Category	Current Technology	Version	Usage in Enhancement	Notes
Frontend Framework	React	18.2.0	UI components for new features	Continue using existing patterns
Build Tool	Vite	-	Build process for enhanced UI	Continue using existing configuration
State Management	Redux Toolkit	-	State management for new features	Continue using existing patterns
Styling	Tailwind CSS	-	Styling for new components	Follow existing design system
Backend Framework	Flask	3.1.1	API endpoints for new features	Extend existing API structure
Database	Supabase (PostgreSQL)	-	Data storage for new features	Use existing tables and auth
Authentication	JWT + Supabase	-	Authentication for new features	Use existing auth patterns
AI Integration	Gradio Client	-	Image generation replacement	Replace Qwen with FLUX.1-dev
Task Queue	Celery + Redis	-	Async processing for image generation	Continue using existing setup

3.2 New Technology Additions

No new major technologies are being introduced. The enhancement involves replacing the current Qwen image generation with FLUX.1-dev while maintaining all other existing technologies.

4. Data Models and Schema Changes

4.1 Schema Integration Strategy

Database Changes Required:

• New Tables: None
• Modified Tables: None
• New Indexes: None
• Migration Strategy: None required

Backward Compatibility:

• No changes to existing data models
• All existing functionality remains intact
• New features use existing database structure

5. Component Architecture

5.1 New Components

KeywordAnalysisService

Responsibility: Handle keyword frequency analysis for content planning Integration Points: Integrated with existing content service and API endpoints

Key Interfaces:

• analyze_keyword_frequency(keywords: List[str]) -> Dict[str, str]

Dependencies:

• Existing Components: Uses existing database connection and authentication
• New Components: None

Technology Stack: Python, existing Flask framework

ImageGenerationService (Updated)

Responsibility: Handle image generation using FLUX.1-dev instead of Qwen Integration Points: Integrated with existing content service and AI workflow

Key Interfaces:

• generate_flux_image(prompt: str, seed: int, dimensions: tuple, guidance_scale: float, inference_steps: int) -> str

Dependencies:

• Existing Components: Uses existing gradio_client and authentication
• New Components: None

Technology Stack: Python, gradio_client, existing Flask framework

5.2 Component Interaction Diagram

graph TB
    subgraph "Frontend"
        A[Posts Page] --> B[KeywordAnalysisPanel]
        A --> C[ImageGenerationPanel]
        B --> D[KeywordAnalysisService]
        C --> E[ImageGenerationService]
    end
    
    subgraph "Backend API"
        F[app.py] --> G[posts_bp]
        G --> H[content_service]
        G --> I[keyword_analysis_service]
    end
    
    subgraph "AI Services"
        H --> J[FLUX.1-dev via gradio_client]
        I --> K[Existing RSS/Post Data]
    end
    
    subgraph "Database"
        L[Supabase] --> H
        L --> I
    end
    
    D -.-> G
    E -.-> G
    B -.-> D
    C -.-> E

6. API Design and Integration

6.1 API Integration Strategy

API Integration Strategy: Extend existing /api/posts endpoints while maintaining compatibility Authentication: Use existing JWT token authentication Versioning: No versioning needed, following existing API patterns

6.2 New API Endpoints

POST /api/posts/keyword-analysis

Method: POST Endpoint: /api/posts/keyword-analysis Purpose: Analyze keyword frequency and relevance Integration: With existing posts API and authentication

Request:

{
  "keywords": ["keyword1", "keyword2"]
}

Response:

{
  "results": {
    "keyword1": "daily",
    "keyword2": "weekly"
  },
  "status": "success"
}

7. External API Integration

7.1 FLUX.1-dev API

Purpose: High-quality image generation to replace current Qwen implementation Documentation: Available through Hugging Face Spaces Base URL: Hugging Face Space for FLUX.1-dev Authentication: Using existing HUGGING_KEY environment variable

Key Endpoints Used:

• POST /infer - Image generation with parameters

Error Handling: Fallback to existing functionality if FLUX.1-dev fails

8. Source Tree

8.1 Existing Project Structure

Lin/
├── .env.hf
├── .gitattributes
├── .gitignore
├── .kilocodemodes
├── app.py
├── docker-compose.yml
├── Dockerfile
├── nginx.conf
├── package-lock.json
├── package.json
├── README.md
├── requirements.txt
├── SETUP_GUIDE.md
├── simple_timezone_test.py
├── start_app.py
├── start_celery.py
├── start-dev.js
├── starty.py
├── test_apscheduler.py
├── test_imports.py
├── test_scheduler_integration.py
├── test_scheduler_visibility.py
├── test_timezone_functionality.py
├── .qwen/
├── backend/
│   ├── __init__.py
│   ├── .env.example
│   ├── app.py
│   ├── config.py
│   ├── Dockerfile
│   ├── README.md
│   ├── requirements.txt
│   ├── test_database_connection.py
│   ├── test_oauth_callback.py
│   ├── test_oauth_flow.py
│   ├── TESTING_GUIDE.md
│   ├── api/
│   │   ├── __init__.py
│   │   ├── accounts.py
│   │   ├── auth.py
│   │   ├── posts.py
│   │   ├── schedules.py
│   │   └── sources.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── schedule.py
│   │   └── user.py
│   ├── scheduler/
│   │   ├── __init__.py
│   │   └── apscheduler_service.py
│   ├── services/
│   │   ├── __init__.py
│   │   ├── auth_service.py
│   │   ├── content_service.py
│   │   ├── linkedin_service.py
│   │   └── schedule_service.py
│   ├── tests/
│   │   ├── test_frontend_integration.py
│   │   └── test_scheduler_image_integration.py
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── cookies.py
│   │   ├── database.py
│   │   ├── image_utils.py
│   │   └── timezone_utils.py
│   └── .gitignore
├── docu_code/
│   ├── My_data_base_schema_.txt
│   └── supabase.txt
├── fav/
│   └── Capture d'écran 2025-08-16 223532.png
├── frontend/
│   ├── .env.development
│   ├── .env.example
│   ├── .env.production
│   ├── .eslintrc.cjs
│   ├── DESIGN_SYSTEM.md
│   ├── Dockerfile
│   ├── index.html
│   ├── package-lock.json
│   ├── package.json
│   ├── postcss.config.js
│   ├── README.md
│   ├── RESPONSIVE_DESIGN_VALIDATION.md
│   ├── tailwind.config.js
│   ├── test-auth-fix.js
│   ├── tsconfig.json
│   ├── tsconfig.node.json
│   ├── vite.config.js
│   ├── public/
│   │   ├── favicon.ico
│   │   ├── favicon.png
│   │   ├── index.html
│   │   └── manifest.json
│   ├── scripts/
│   │   └── build-env.js
│   ├── src/
│   │   ├── App.css
│   │   ├── App.jsx
│   │   ├── index.css
│   │   ├── index.jsx
│   │   ├── layout-test.js
│   │   ├── responsive-design-test.js
│   │   ├── responsive.css
│   │   ├── components/
│   │   │   ├── FeatureCard.jsx
│   │   │   ├── TestimonialCard.jsx
│   │   │   ├── Header/
│   │   │   │   ├── Header.css
│   │   │   │   └── Header.jsx
│   │   │   ├── LinkedInAccount/
│   │   │   │   ├── LinkedInAccountCard.jsx
│   │   │   │   ├── LinkedInAccountsManager.jsx
│   │   │   │   └── LinkedInCallbackHandler.jsx
│   │   │   └── Sidebar/
│   │   │       └── Sidebar.jsx
│   │   ├── css/
│   │   │   ├── base.css
│   │   │   ├── components.css.bak
│   │   │   ├── main.css
│   │   │   ├── responsive.css
│   │   │   ├── typography.css
│   │   │   ├── variables.css
│   │   │   ├── components/
│   │   │   ├── buttons.css
│   │   │   │   ├── cards.css
│   │   │   │   ├── forms.css
│   │   │   │   ├── grid.css
│   │   │   │   ├── header.css
│   │   │   │   ├── linkedin.css
│   │   │   │   ├── modal.css
│   │   │   │   ├── navigation.css
│   │   │   │   ├── sidebar.css
│   │   │   │   ├── table.css
│   │   │   │   └── utilities.css
│   │   │   └── responsive/
│   │   │       ├── accessibility.css
│   │   │       ├── base.css
│   │   │       ├── mobile-nav.css
│   │   │       ├── performance.css
│   │   │       └── performance/
│   │   │           ├── lazy-loading.css
│   │   │           └── mobile-optimization.css
│   │   ├── debug/
│   │   │   ├── testApi.js
│   │   │   └── testApiIntegration.js
│   │   ├── pages/
│   │   │   ├── Accounts.jsx
│   │   │   ├── Dashboard.jsx
│   │   │   ├── ForgotPassword.jsx
│   │   │   ├── Home.jsx
│   │   │   ├── Login.jsx
│   │   │   ├── Posts.jsx
│   │   │   ├── Register.jsx
│   │   │   ├── ResetPassword.jsx
│   │   │   ├── Schedule.jsx
│   │   │   └── Sources.jsx
│   │   ├── services/
│   │   │   ├── accountService.js
│   │   │   ├── api.js
│   │   │   ├── apiClient.js
│   │   │   ├── authService.js
│   │   │   ├── cacheService.js
│   │   │   ├── cookieService.js
│   │   │   ├── linkedinAuthService.js
│   │   │   ├── postService.js
│   │   │   ├── scheduleService.js
│   │   │   ├── securityService.js
│   │   │   ├── sourceService.js
│   │   │   └── supabaseClient.js
│   │   ├── store/
│   │   │   ├── index.js
│   │   │   └── reducers/
│   │   │       ├── accountsSlice.js
│   │   │       ├── authSlice.js
│   │   │       ├── linkedinAccountsSlice.js
│   │   │       ├── postsSlice.js
│   │   │       ├── schedulesSlice.js
│   │   │       └── sourcesSlice.js
│   │   └── utils/
│   │       └── timezoneUtils.js
│   └── .gitignore
├── Linkedin_poster_dev/
│   ├── .gitattributes
│   ├── ai_agent.py
│   ├── app.py
│   ├── README.md
│   └── requirements.txt
└── docs/
    └── architecture.md

8.2 New File Organization

Lin/
├── frontend/
│   └── src/
│       ├── components/
│       │   └── KeywordAnalysis/     # New keyword analysis components
│       │       ├── KeywordAnalysisPanel.jsx
│       │       └── index.js
│       └── services/
│           └── keywordAnalysisService.js
├── backend/
│   ├── services/
│   │   ├── keyword_analysis_service.py # New service
│   │   └── content_service.py           # Updated with FLUX.1-dev
│   └── api/
│       └── posts.py                     # Extended with new endpoints
└── Linkedin_poster_dev/
    └── ai_agent.py                      # Updated with FLUX.1-dev

8.3 Integration Guidelines

• File Naming: Follow existing snake_case for Python and camelCase for JavaScript
• Folder Organization: Place new components in appropriate existing directories
• Import/Export Patterns: Maintain existing patterns in the codebase

9. Infrastructure and Deployment Integration

9.1 Existing Infrastructure

Current Deployment: Docker with docker-compose and Nginx reverse proxy Infrastructure Tools: Docker, docker-compose, Nginx, Redis for Celery Environments: Development and production configurations available

9.2 Enhancement Deployment Strategy

Deployment Approach: No infrastructure changes required, using existing setup Infrastructure Changes: None Pipeline Integration: No changes to existing deployment pipeline

9.3 Rollback Strategy

Rollback Method: Revert changes to ai_agent.py to restore Qwen functionality Risk Mitigation: Thorough testing before deployment Monitoring: Monitor API response times and error rates

10. Coding Standards

10.1 Existing Standards Compliance

Code Style: Follow existing Python (PEP 8) and JavaScript (ESLint) standards Linting Rules: Use existing linting configurations Testing Patterns: Follow existing pytest and React testing patterns Documentation Style: Follow existing docstring and JSDoc patterns

10.2 Critical Integration Rules

• Existing API Compatibility: New endpoints must follow existing authentication patterns
• Database Integration: Use existing Supabase connection and query patterns
• Error Handling: Follow existing error response format
• Logging Consistency: Use existing logging patterns

11. Testing Strategy

11.1 Integration with Existing Tests

Existing Test Framework: pytest for backend, Jest/React Testing Library for frontend Test Organization: Follow existing test directory structure Coverage Requirements: Maintain existing coverage thresholds

11.2 New Testing Requirements

Unit Tests for New Components

Framework: pytest for backend, React Testing Library for frontend Location: backend/tests/ and frontend/src/tests/ Coverage Target: 80%+ for new code Integration with Existing: Follow existing test patterns

Integration Tests

Scope: Test new API endpoints with authentication Existing System Verification: Ensure existing functionality remains intact New Feature Testing: Validate keyword analysis and image generation

Regression Testing

Existing Feature Verification: Run all existing tests to ensure no regressions Automated Regression Suite: Use existing CI pipeline Manual Testing Requirements: Test end-to-end workflows manually

12. Security Integration

12.1 Existing Security Measures

Authentication: JWT token-based authentication Authorization: Role-based access control Data Protection: Supabase security and encryption Security Tools: Built-in Flask security features

12.2 Enhancement Security Requirements

New Security Measures: Input validation for new API endpoints Integration Points: Use existing authentication for all new endpoints Compliance Requirements: Maintain existing data privacy standards

12.3 Security Testing

Existing Security Tests: Continue running existing security tests New Security Test Requirements: Validate input sanitization for new endpoints Penetration Testing: None specifically required for these enhancements

13. Next Steps

13.1 Story Manager Handoff

The architecture document provides a clear roadmap for implementing the UI/UX improvements, keyword analysis feature, and FLUX.1-dev image generation. The key integration requirements have been validated with the existing system. Begin with implementing the keyword analysis feature, followed by the FLUX.1-dev integration, and finally the UI/UX enhancements. Emphasis should be placed on maintaining existing system integrity throughout implementation.

13.2 Developer Handoff

Developers should reference this architecture document and existing coding standards when starting implementation. The integration requirements with the existing codebase have been validated. Key technical decisions are based on real project constraints, and existing system compatibility requirements include specific verification steps for API compatibility. The implementation should follow a clear sequence to minimize risk to existing functionality: keyword analysis service first, then FLUX.1-dev integration, and finally UI enhancements.