# snyk-labs/ai-promoter architecture

> Architecture diagram of the GitHub repository snyk-labs/ai-promoter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snyk-labs/ai-promoter
- Repository: https://github.com/snyk-labs/ai-promoter

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Browser["Browser / User"]:::frontend
        Templates["Jinja Templates"]:::frontend
        Static["Static Assets"]:::frontend
    end

    %% Application Layer
    subgraph "Web Application Layer"
        direction TB
        AppEntry["Flask Web Server<br/>(app.py)"]:::app
        CeleryFactory["Celery Setup<br/>(celery_app.py,<br/>make_celery.py)"]:::app
        Config["Configuration<br/>(config.py)"]:::app
        Extensions["Flask Extensions<br/>(extensions.py)"]:::app

        subgraph "Models"
            direction TB
            ContentModel["Content Model<br/>(models/content.py)"]:::app
            UserModel["User Model<br/>(models/user.py)"]:::app
            ShareModel["Share Model<br/>(models/share.py)"]:::app
        end

        subgraph "Views / Blueprints"
            direction TB
            MainView["Main Routes<br/>(views/main.py)"]:::app
            APIView["API Routes<br/>(views/api.py)"]:::app
            AuthView["Auth Routes<br/>(views/auth.py)"]:::app
            OktaAuthView["Okta Auth<br/>(views/okta_auth.py)"]:::app
            AdminView["Admin Routes<br/>(views/admin.py)"]:::app
            SlackView["Slack Routes<br/>(views/slack.py)"]:::app
        end

        subgraph "CLI Commands"
            direction TB
            InitDB["Init DB<br/>(cli/init_db.py)"]:::app
            CreateAdmin["Create Admin<br/>(cli/create_admin.py)"]:::app
            BeatCLI["Start Beat<br/>(cli/beat.py)"]:::app
            LintCLI["Lint<br/>(cli/lint.py)"]:::app
            TestCLI["Test<br/>(cli/test.py)"]:::app
        end

        subgraph "Helpers"
            direction TB
            ContentGen["Content Generator<br/>(helpers/content_generator.py)"]:::app
            Prompts["Prompts<br/>(helpers/prompts.py)"]:::app
            TemplateHelpers["Template Helpers<br/>(helpers/template_helpers.py)"]:::app
            subgraph "Platform Adapters"
                direction TB
                BasePlatform["Base Adapter<br/>(helpers/platforms/base.py)"]:::app
                LinkedInAdapter["LinkedIn Adapter<br/>(helpers/platforms/linkedin.py)"]:::app
            end
            OktaHelper["Okta Helper<br/>(helpers/okta.py)"]:::app
            LinkedInNative["LinkedIn Native<br/>(helpers/linkedin_native.py)"]:::app
            SlackHelper["Slack Helper<br/>(helpers/slack.py)"]:::app
        end

        subgraph "Service Wrappers"
            direction TB
            ContentProcessor["Content Processor<br/>(services/content_processor.py)"]:::app
            ContentService["Content Service<br/>(services/content_service.py)"]:::app
            SlackService["Slack Service<br/>(services/slack_service.py)"]:::app
        end
    end

    %% Celery Layer
    subgraph "Asynchronous Processing (Celery)" 
        direction TB
        BeatScheduler["Celery Beat Scheduler"]:::app
        Worker["Celery Worker"]:::app

        subgraph "Tasks Modules"
            direction TB
            FetchContent["Fetch Content<br/>(tasks/fetch_content.py)"]:::app
            ContentTask["Content Task<br/>(tasks/content.py)"]:::app
            PromoteTask["Promote Task<br/>(tasks/promote.py)"]:::app
            LinkedInTask["LinkedIn Tasks<br/>(tasks/linkedin_tasks.py)"]:::app
            SlackTask["Slack Tasks<br/>(tasks/slack_tasks.py)"]:::app
            NotificationsTask["Notifications<br/>(tasks/notifications.py)"]:::app
            SocialMediaTask["Social Media<br/>(tasks/social_media.py)"]:::app
        end
    end

    %% Data & Queue Layer
    subgraph "Data & Queue Layer"
        direction TB
        Database["Relational DB<br/>(PostgreSQL/SQLite)"]:::data
        Migrations["Alembic Migrations<br/>(migrations/)"]:::data
        RedisStore["Redis<br/>(Broker & Cache)"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GeminiAPI["Gemini AI API"]:::external
        FirecrawlAPI["Firecrawl API"]:::external
        LinkedInAPI["LinkedIn API"]:::external
        SlackAPI["Slack API"]:::external
        OktaAPI["Okta OIDC"]:::external
        SMTP["Email SMTP"]:::external
    end

    %% Connections
    Browser -->|"HTTP(S)"| AppEntry
    Browser --> Templates
    Browser --> Static

    AppEntry --> Config
    AppEntry --> Extensions
    AppEntry --> Models
    AppEntry --> Views
   
    AppEntry --> RedisStore
    AppEntry -->|Enqueue Task| RedisStore

    CeleryFactory --> RedisStore
    CeleryFactory --> Database

    RedisStore --> Worker
    BeatScheduler --> RedisStore
    Worker --> Database
    Worker --> ContentProcessor
    Worker --> ContentService
    Worker --> SlackService

    FetchContent -->|"uses"| FirecrawlAPI
    PromoteTask -->|Calls| GeminiAPI
    LinkedInTask -->|Posts to| LinkedInAPI
    SlackTask -->|Notifies via| SlackAPI
    NotificationsTask -->|Sends Email| SMTP
    NotificationsTask -->|Sends Slack| SlackAPI

    Worker --> FetchContent
    Worker --> ContentTask
    Worker --> PromoteTask
    Worker --> LinkedInTask
    Worker --> SlackTask
    Worker --> NotificationsTask
    Worker --> SocialMediaTask

    AppEntry -->|"DB Read/Write"| Database
    Migrations --> Database

    Views --> Extensions
    Views --> Models
    Views -->|Invoke| ContentProcessor
    Views -->|Invoke| SlackService

    Views -->|Redirect/OIDC| OktaAPI
    OktaHelper --> OktaAPI

    %% Click Events
    click Templates "https://github.com/snyk-labs/ai-promoter/tree/main/templates/"
    click Static "https://github.com/snyk-labs/ai-promoter/tree/main/static/"
    click AppEntry "https://github.com/snyk-labs/ai-promoter/blob/main/app.py"
    click CeleryFactory "https://github.com/snyk-labs/ai-promoter/blob/main/celery_app.py"
    click CeleryFactory "https://github.com/snyk-labs/ai-promoter/blob/main/make_celery.py"
    click Config "https://github.com/snyk-labs/ai-promoter/blob/main/config.py"
    click Extensions "https://github.com/snyk-labs/ai-promoter/blob/main/extensions.py"
    click ContentModel "https://github.com/snyk-labs/ai-promoter/blob/main/models/content.py"
    click UserModel "https://github.com/snyk-labs/ai-promoter/blob/main/models/user.py"
    click ShareModel "https://github.com/snyk-labs/ai-promoter/blob/main/models/share.py"
    click Migrations "https://github.com/snyk-labs/ai-promoter/tree/main/migrations/"
    click MainView "https://github.com/snyk-labs/ai-promoter/blob/main/views/main.py"
    click APIView "https://github.com/snyk-labs/ai-promoter/blob/main/views/api.py"
    click AuthView "https://github.com/snyk-labs/ai-promoter/blob/main/views/auth.py"
    click OktaAuthView "https://github.com/snyk-labs/ai-promoter/blob/main/views/okta_auth.py"
    click AdminView "https://github.com/snyk-labs/ai-promoter/blob/main/views/admin.py"
    click SlackView "https://github.com/snyk-labs/ai-promoter/blob/main/views/slack.py"
    click InitDB "https://github.com/snyk-labs/ai-promoter/blob/main/cli/init_db.py"
    click CreateAdmin "https://github.com/snyk-labs/ai-promoter/blob/main/cli/create_admin.py"
    click BeatCLI "https://github.com/snyk-labs/ai-promoter/blob/main/cli/beat.py"
    click LintCLI "https://github.com/snyk-labs/ai-promoter/blob/main/cli/lint.py"
    click TestCLI "https://github.com/snyk-labs/ai-promoter/blob/main/cli/test.py"
    click FetchContent "https://github.com/snyk-labs/ai-promoter/blob/main/tasks/fetch_content.py"
    click ContentTask "https://github.com/snyk-labs/ai-promoter/blob/main/tasks/content.py"
    click PromoteTask "https://github.com/snyk-labs/ai-promoter/blob/main/tasks/promote.py"
    click LinkedInTask "https://github.com/snyk-labs/ai-promoter/blob/main/tasks/linkedin_tasks.py"
    click SlackTask "https://github.com/snyk-labs/ai-promoter/blob/main/tasks/slack_tasks.py"
    click NotificationsTask "https://github.com/snyk-labs/ai-promoter/blob/main/tasks/notifications.py"
    click SocialMediaTask "https://github.com/snyk-labs/ai-promoter/blob/main/tasks/social_media.py"
    click ContentGen "https://github.com/snyk-labs/ai-promoter/blob/main/helpers/content_generator.py"
    click Prompts "https://github.com/snyk-labs/ai-promoter/blob/main/helpers/prompts.py"
    click TemplateHelpers "https://github.com/snyk-labs/ai-promoter/blob/main/helpers/template_helpers.py"
    click BasePlatform "https://github.com/snyk-labs/ai-promoter/blob/main/helpers/platforms/base.py"
    click LinkedInAdapter "https://github.com/snyk-labs/ai-promoter/blob/main/helpers/platforms/linkedin.py"
    click OktaHelper "https://github.com/snyk-labs/ai-promoter/blob/main/helpers/okta.py"
    click LinkedInNative "https://github.com/snyk-labs/ai-promoter/blob/main/helpers/linkedin_native.py"
    click SlackHelper "https://github.com/snyk-labs/ai-promoter/blob/main/helpers/slack.py"
    click ContentProcessor "https://github.com/snyk-labs/ai-promoter/blob/main/services/content_processor.py"
    click ContentService "https://github.com/snyk-labs/ai-promoter/blob/main/services/content_service.py"
    click SlackService "https://github.com/snyk-labs/ai-promoter/blob/main/services/slack_service.py"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef app fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef data fill:#FCF3CF,stroke:#7D6608,color:#6E2C00
    classDef external fill:#F2F4F4,stroke:#707B7C,color:#17202A
```
