Architecture Design

Overview

Social Publisher follows a microservice-like architecture, decoupling the "publishing" logic from the main application. It uses a producer-consumer model for handling tasks.

graph TD
    Client[Web/Main App] -->|HTTP POST| API[FastAPI Server]
    API -->|Insert| DB[(MySQL Database)]
    API -->|Response| Client
    
    Worker[Background Worker] -->|Poll| DB
    Worker -->|Execute| Publisher[Publisher Service]
    
    Publisher -->|Control| Playwright[Playwright Browser]
    Playwright -->|Interact| Douyin[Douyin Web Creator]

Components

1. API Server (app.py)

• Framework: FastAPI.
• Role: Receives requests, validates input, creates task records in the database, and queries task status.
• Endpoints: /publish, /accounts, etc.

2. Database (database.py)

• ORM: SQLModel (SQLAlchemy wrapper).
• Storage: MySQL.
• Model: PublishTask stores task parameters, status, and results.

3. Background Worker (worker.py)

• Role: Continuously polls the database for tasks with status="pending".
• Concurrency: Processes one task at a time (per worker instance) to ensure browser stability and avoid resource contention.
• Logic:
  1. Fetch pending task.
  2. Update status to running.
  3. Invoke PublisherService.
  4. Update status to success or failed based on outcome.

4. Publisher Service (service/publisher_service.py)

• Role: Orchestrates the publishing flow.
• Responsibilities:
  • Resource resolution: Downloads files from URLs to local temp storage.
  • Browser management: Initializes BrowserEngine via AccountManager.
  • Platform delegation: Calls specific platform publishers (e.g., DouyinPublisher).

5. Platform Implementation (platforms/douyin/publisher.py)

• Role: Implements the actual automation steps for Douyin.
• Steps:
  1. Login Check: Verifies session validty. If invalid, waits for QR scan.
  2. Navigation: Goes to the upload page.
  3. Upload: Interacts with the file input to upload the video.
  4. Form Filling: Fills title, description, tags.
  5. Settings: Configures cover, schedule time, declarations.
  6. Submission: Clicks the publish button and verifies success.

6. Account Manager (core/account.py)

• Role: Manages browser contexts and user data.
• Data: Stores browser profiles (cookies, local storage) in data/{account_name}.
• Persistence: Ensures that once a user logs in, the session is preserved across service restarts.

Key Design Decisions

• Playwright over Selenium: Chosen for better performance, stability, and native support for modern web features (like shadow DOM and handling multiple contexts).
• Playwright Stealth: Essential for bypassing bot detection mechanisms on Douyin.
• Synchronous Polling Worker: Chosen for simplicity and reliability over complex message queues (like Redis/RabbitMQ) for this scale. MySQL serves as the queue.