# Understanding the social-auto-upload Project Architecture: Flask, Vue, and CLI Integration

> Explore the social-auto-upload architecture. Learn how Flask, Vue, and CLI integrate for automated social media publishing with file management and a web dashboard.

- Repository: [Alleria/social-auto-upload](https://github.com/dreammis/social-auto-upload)
- Tags: architecture
- Published: 2026-05-31

---

**TLDR:** The social-auto-upload project implements a three-layer architecture where a Flask backend manages file storage and Playwright automation, a Vue.js frontend provides a web dashboard, and a Python CLI enables terminal-based publishing, all synchronized through a shared SQLite database and configuration file.

The dreammis/social-auto-upload repository automates video publishing across multiple Chinese and international social media platforms through a modular system. Its architecture cleanly separates web API concerns, user interface interactions, and command-line automation into distinct layers that share common data stores and configuration constants.

## Three-Layer Architecture Overview

The system is organized into backend, CLI, and frontend components that converge on shared resources.

### Backend Layer: Flask REST API

The backend is implemented in [`sau_backend.py`](https://github.com/dreammis/social-auto-upload/blob/main/sau_backend.py), which instantiates a Flask application and exposes RESTful endpoints for file management and publishing orchestration. It registers critical routes including `/upload`, `/uploadSave`, `/getFiles`, and `/getAccounts` to handle video ingestion and account management.

The configuration enforces a **160 MiB upload limit** via `app.config['MAX_CONTENT_LENGTH']` and uses **Flask-CORS** to enable cross-origin requests from the Vue UI. Files are stored under `BASE_DIR/videoFile` while metadata persists in a SQLite database at `db/database.db`. The backend also serves static assets via `/assets/*` routes to support the frontend interface.

### CLI Layer: Terminal Automation

The command-line interface in [`sau_cli.py`](https://github.com/dreammis/social-auto-upload/blob/main/sau_cli.py) provides power users with direct access to upload functionality without launching the web server. It uses `argparse` to parse subcommands and constructs **dataclasses** such as `DouyinVideoUploadRequest` (defined around lines 48‑60) to represent upload jobs.

The CLI drives **Playwright** browsers in headless mode (`headless=True`) using **asyncio** for asynchronous execution. It resolves platform-specific cookie files from the `cookies/` directory via `resolve_account_file` and forwards requests to dedicated uploader modules like `uploader/douyin_uploader`.

### Frontend Layer: Vue 3 Dashboard

The graphical interface resides in `sau_frontend/` and bootstraps from [`src/main.js`](https://github.com/dreammis/social-auto-upload/blob/main/src/main.js), which registers the Vue router ([`router/index.js`](https://github.com/dreammis/social-auto-upload/blob/main/router/index.js)), Pinia state management stores, and Element Plus UI components. The application consists of five core views: [`Dashboard.vue`](https://github.com/dreammis/social-auto-upload/blob/main/Dashboard.vue), [`AccountManagement.vue`](https://github.com/dreammis/social-auto-upload/blob/main/AccountManagement.vue), [`MaterialManagement.vue`](https://github.com/dreammis/social-auto-upload/blob/main/MaterialManagement.vue), [`PublishCenter.vue`](https://github.com/dreammis/social-auto-upload/blob/main/PublishCenter.vue), and [`About.vue`](https://github.com/dreammis/social-auto-upload/blob/main/About.vue).

All API communication flows through [`src/utils/request.js`](https://github.com/dreammis/social-auto-upload/blob/main/src/utils/request.js) (lines 1‑10), which configures an **axios** instance with a base URL of `http://localhost:5409` and interceptors for token handling. This abstraction ensures consistent HTTP semantics across the UI components.

## Data Flow and Component Integration

The architecture supports two primary interaction patterns that share the same underlying storage and automation engines.

### Web UI Upload Workflow

When users upload via the dashboard, the frontend sends a `multipart/form-data` POST request to `/uploadSave` using the axios wrapper. The Flask backend receives the payload, writes the video to `videoFile/`, and inserts a record into the `file_records` table. The UI then refreshes its file list by calling `/getFiles`, which queries the SQLite database and returns JSON arrays containing `filename`, `filesize`, and `uuid` fields (implemented around lines 153‑185 in [`sau_backend.py`](https://github.com/dreammis/social-auto-upload/blob/main/sau_backend.py)).

### CLI Direct Execution

Alternatively, users invoke [`sau_cli.py`](https://github.com/dreammis/social-auto-upload/blob/main/sau_cli.py) with platform-specific arguments. The CLI constructs request objects, validates cookie files in `cookies/douyin_<account>.json` (or equivalent for other platforms), and instantiates uploader classes directly. For example, `DouYinVideo(...).publish()` executes Playwright automation without requiring the Flask server to be running, though both methods ultimately write to the same database and filesystem locations.

## Configuration and Shared Resources

All three layers rely on [`conf.py`](https://github.com/dreammis/social-auto-upload/blob/main/conf.py) (copied from [`conf.example.py`](https://github.com/dreammis/social-auto-upload/blob/main/conf.example.py)) which defines the **BASE_DIR** constant. This ensures consistent paths for video storage, database files, and cookie directories regardless of which interface initiates the operation. The database schema is initialized via [`db/createTable.py`](https://github.com/dreammis/social-auto-upload/blob/main/db/createTable.py), creating the `file_records` table used by both the backend API and CLI status checks.

## Implementation Examples

The following snippets demonstrate how each layer interacts with the system.

### Command-Line Upload to Douyin

```bash
sau douyin upload \
    --account myDouyin \
    --file ./my_video.mp4 \
    --title "Summer Vlog" \
    --tags "#travel,#vlog" \
    --schedule "2024-08-01 10:00"

```

*This command parses arguments into a `DouyinVideoUploadRequest`, resolves the cookie file, and triggers the uploader module.*

### Frontend File Retrieval

```javascript
import { http } from '@/utils/request'

export function fetchFiles () {
  return http.get('/getFiles')
}

```

*The `http` instance configures the base URL and headers in [`sau_frontend/src/utils/request.js`](https://github.com/dreammis/social-auto-upload/blob/main/sau_frontend/src/utils/request.js).*

### Triggering Publication from the UI

```javascript
// Inside PublishCenter.vue
function publish (videoId, platform) {
  const payload = {
    account_name: selectedAccount,
    video_file: videoId,
    title: titleInput,
    description: descriptionInput,
    tags: tagList,
    publish_date: schedule ? new Date(schedule) : 0,
    publish_strategy: 'IMMEDIATE'
  }
  http.post(`/publish/${platform}`, payload)
      .then(() => ElMessage.success('Publish scheduled'))
}

```

*This posts to platform-specific endpoints (e.g., `/publish/douyin`), which the backend routes to the appropriate Playwright automation.*

## Key Source Files and Responsibilities

Understanding the social-auto-upload project architecture requires familiarity with these critical files:

- **[`sau_backend.py`](https://github.com/dreammis/social-auto-upload/blob/main/sau_backend.py)**: Flask application factory, route definitions, and file storage logic.
- **[`sau_cli.py`](https://github.com/dreammis/social-auto-upload/blob/main/sau_cli.py)**: Argument parsing, dataclass construction, and asynchronous upload orchestration.
- **[`sau_frontend/src/main.js`](https://github.com/dreammis/social-auto-upload/blob/main/sau_frontend/src/main.js)**: Vue application bootstrap and global component registration.
- **[`sau_frontend/src/router/index.js`](https://github.com/dreammis/social-auto-upload/blob/main/sau_frontend/src/router/index.js)**: URL routing to the five primary dashboard views.
- **[`sau_frontend/src/utils/request.js`](https://github.com/dreammis/social-auto-upload/blob/main/sau_frontend/src/utils/request.js)**: Axios configuration and HTTP interceptors.
- **[`uploader/douyin_uploader/main.py`](https://github.com/dreammis/social-auto-upload/blob/main/uploader/douyin_uploader/main.py)**: Example platform implementation handling login and publishing.
- **[`db/createTable.py`](https://github.com/dreammis/social-auto-upload/blob/main/db/createTable.py)**: Database schema initialization for file metadata persistence.
- **[`conf.example.py`](https://github.com/dreammis/social-auto-upload/blob/main/conf.example.py)**: Template for runtime configuration including `BASE_DIR`.

## Summary

- The **social-auto-upload project architecture** separates concerns into a Flask REST API, a Vue.js frontend, and a Python CLI tool.
- All layers share **SQLite storage** and filesystem paths defined in [`conf.py`](https://github.com/dreammis/social-auto-upload/blob/main/conf.py), ensuring data consistency.
- The **backend** handles file uploads up to 160 MiB and serves static assets while managing Playwright automation.
- The **CLI** provides headless, asyncio-driven automation for terminal users using dataclass-based request objects.
- The **frontend** uses Element Plus components and Pinia stores, communicating via axios to localhost:5409.

## Frequently Asked Questions

### How does the Vue frontend communicate with the Flask backend?

The frontend uses an axios instance configured in [`sau_frontend/src/utils/request.js`](https://github.com/dreammis/social-auto-upload/blob/main/sau_frontend/src/utils/request.js) to send HTTP requests to `http://localhost:5409`. The backend enables cross-origin resource sharing via **Flask-CORS**, allowing the Vue dev server and built static files to interact with the REST API seamlessly.

### What is the maximum video file size allowed?

The Flask backend enforces a **160 MiB limit** through the `MAX_CONTENT_LENGTH` configuration setting in [`sau_backend.py`](https://github.com/dreammis/social-auto-upload/blob/main/sau_backend.py). Uploads exceeding this threshold receive a 413 error before reaching the storage layer.

### How does the CLI handle authentication cookies?

The CLI stores per-platform cookies in JSON files under the `cookies/` directory, named according to the pattern `<platform>_<account>.json`. The `resolve_account_file` function in [`sau_cli.py`](https://github.com/dreammis/social-auto-upload/blob/main/sau_cli.py) locates these files and passes them to Playwright contexts, enabling persistent logins across automation sessions.

### Can I use the uploader without running the web interface?

Yes. The CLI component operates independently of the Flask server. You can execute [`sau_cli.py`](https://github.com/dreammis/social-auto-upload/blob/main/sau_cli.py) subcommands directly to trigger uploads using stored cookies, making it suitable for cron jobs or CI/CD pipelines where a GUI is unnecessary.