How snyk-labs/ai-promoter works
Project type and purpose
• This is a full-stack web application (Flask MVT pattern) with asynchronous background processing (Celery).
• Purpose: Automate social media promotion by syncing RSS feeds (podcast, blog, YouTube), generating posts via AI (Gemini), and posting to platforms (LinkedIn, Slack), with optional Okta SSO.
File structure
• Top-level:
• app.py, celery_app.py, make_celery.py – application and Celery factory
• config.py – centralized settings
• extensions.py – Flask extensions (SQLAlchemy, Login, Migrate, Mail, Redis)
• models/ – data models (User, Content, Share)
• views/ – HTTP routes grouped by feature (main, api, auth, okta_auth, admin)
• templates/ & static/ – UI layer (HTML, JS)
• cli/ – custom Flask CLI commands for DB init, admin creation, Celery beat, lint, tests
• helpers/ – utility modules (content generation, platform adapters, prompts, template helpers)
• services/ – integration wrappers (content_processor, LinkedIn, Slack)
• tasks/ – Celery tasks (fetching content, content processing, posting, notifications)
• migrations/ – Alembic database migrations
• tests/ – unit and integration tests
Key insights from README
• Uses Model-View-Template architecture.
• Celery beat for scheduled tasks (RSS sync hourly, auto-posting on schedule).
• Integrations: Okta SSO, Redis (broker/cache), SQL database, external APIs (Gemini AI, LinkedIn, Firecrawl, Slack, Email).
Components
a. Frontend:
• Browser / User Interface
– Static assets (JS, CSS) & Jinja templates served by Flask
b. Backend / Web Application:
• Flask app (app.py) with Blueprints (views package)
• Flask extensions (db, login, migrate, mail, redis_client)
• CLI interface (for DB init, admin user, trigger Celery beat)
c. Data Layer:
• Relational database (SQLite dev / PostgreSQL prod)
• Alembic migrations
d. Caching & Messaging:
• Redis – Celery broker & result backend; optional cache
e. Asynchronous Processing:
• Celery worker processes
• Celery beat scheduler
• Task modules (tasks.fetch_content, tasks.promote, tasks.slack_tasks, etc.)
f. External Services:
• Gemini AI API (content generation)
• Firecrawl API (RSS scraping)
• LinkedIn API (posting, token refresh)
• Slack API (notifications)
• Okta (OIDC SSO)
• Email SMTP provider
g. CLI & Scheduler:
• Flask CLI commands to start worker, beat, trigger tasks
Relationships and interactions
• User → HTTP(S) → Flask Web Server → Views → Models → Database
• Views (especially API routes) invoke services or enqueue Celery tasks
• Celery beat → schedules periodic tasks → Celery worker → executes tasks in tasks/ modules
• Tasks interact with Models (db), Services (LinkedIn, Slack, Firecrawl), and external APIs (Gemini)
• Redis mediates between Web app and Celery workers (broker/results)
• Okta auth flow: Browser ↔ Flask Okta routes ↔ Okta OIDC endpoints
• Email & Slack notifications triggered by tasks.notifications
• Content generation: tasks.promote calls helpers.prompts + Gemini API
Architectural patterns & principles
• MVT (Model-View-Template) for clear separation of concerns
• Modular packaging (helpers, services, tasks) for extensibility
• Asynchronous job queue (Celery) for scalability and decoupling
• Single codebase monolith with external dependencies abstracted behind service modules
• Configuration via environment variables (twelve-factor app)
• Clear component boundaries (Web App, Data Layer, Job Queue, External Services)
• User interaction flow
• Data flow between components
• Task scheduling and execution flow
• Footnote or sidebar listing key technologies: Flask, SQLAlchemy, Alembic, Redis, Celery, Jinja2, Gunicorn