# yikart/aitoearn architecture

> Architecture diagram of the GitHub repository yikart/aitoearn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yikart/aitoearn
- Repository: https://github.com/yikart/aitoearn

## Overview

1. This repository is a multi-surface product, not a single app. The main runtime pieces are:
   - `project/aitoearn-backend`: the primary cloud/backend monorepo
   - `project/aitoearn-web`: the Next.js marketing + product web app
   - `project/aitoearn-electron`: the desktop client, including its own bundled server
   - top-level Docker/Nginx assets for deployment and static hosting

2. The core backend is `project/aitoearn-backend`, organized as an Nx monorepo with two NestJS applications:
   - `aitoearn-server`: the main business API
   - `aitoearn-ai`: the AI/agent execution service
   Shared libraries provide cross-cutting infrastructure like MongoDB, Redis, queues, auth, assets, MCP, and SDK clients.

3. `aitoearn-server` is the central domain API. It owns the user-facing business modules for:
   - accounts and account groups
   - content/material/media management
   - platform connections and publishing
   - engagement and interaction workflows
   - credits, notifications, short links, tools, relay/OAuth, and internal/admin APIs
   It also renders a few server-side views for auth flows.

4. `aitoearn-ai` is the automation/agent side of the backend. It contains:
   - AI chat and task orchestration
   - image/video generation pipelines
   - draft generation
   - material adaptation
   - model/provider adapters for Gemini, Grok, OpenAI, and Volcengine
   - agent “skills” and MCP tool implementations
   This service is where long-running AI jobs, schedulers, and agent task handling live.

5. The main data flow in the backend is request-driven API plus background execution:
   - HTTP controllers accept commands from web/Electron/MCP clients
   - services persist state in MongoDB
   - Redis is used for pub/sub, task coordination, rate/state sharing, and locks
   - queue workers consume asynchronous jobs for publishing, engagement, credits, notifications, and AI media processing
   This separation is important: controllers are thin entry points, while work is pushed into queues/schedulers/consumers.

6. Persistence is mostly MongoDB, with a dedicated repository/schema layer in `libs/mongodb` and `libs/channel-db`.
   Those libraries centralize collection models such as users, accounts, publish records, media, notifications, credits, tasks, and interaction records.
   `libs/mongodb` appears to be the newer unified persistence layer for the main backend; `libs/channel-db` supports channel-specific task/account records.

7. External integrations are a major architectural boundary. The backend talks to:
   - social platform APIs for publishing and engagement: Douyin, Kuaishou/Kwai, Bilibili, Xiaohongshu, TikTok, YouTube, Facebook, Instagram, Threads, Twitter/X, Pinterest, LinkedIn, WeChat Official Accounts, Google Business
   - AI model providers: Gemini, Grok, OpenAI, Volcengine
   - object storage: Ali OSS and AWS S3 abstractions in shared libs
   - messaging/notifications: email, SMS, Feishu logging/alerts
   - optional relay OAuth service, used to avoid requiring every self-hosted deployment to register its own platform app credentials

8. The publishing subsystem in `aitoearn-server` is one of the biggest internal boundaries. It is split into:
   - high-level publish orchestration
   - platform-specific publisher implementations
   - staging/upload/media-container logic
   - webhook handlers for platform callbacks
   - schedulers that enqueue publish jobs
   - consumers that finalize publish state and update records
   This subsystem bridges content stored internally with platform-side credentials, media uploads, scheduled execution, and post-publish state tracking.

9. The engagement subsystem is separate from publishing, but similar in shape. It includes:
   - platform providers for comment/interaction actions
   - workers for distributing engagement tasks and replying to comments
   - record services for interaction history and reply logs
   - admin/internal APIs for task visibility
   This indicates the product treats “publish” and “engage” as distinct workflows, even though they target the same social platforms.

10. `aitoearn-ai` exposes APIs for user-facing AI features and agent execution. It includes:
    - content generation endpoints and logs
    - AI asset management
    - model configuration/pricing
    - task status schedulers
    - agent runtime and Claude-code router integration
    - MCP tool modules for media, subtitles, image/video editing, style transfer, drama recap, and utility actions
    The presence of MCP support means this service is designed to be called not only by the web app but also by external agents like Claude/Cursor/OpenClaw.

11. `project/aitoearn-web` is the main browser front end. It is a Next.js app with:
    - internationalized routes under `[lng]`
    - product pages for chat, draft box, accounts, brand promotion, tasks history, agent assets, and welcome/marketing content
    - a large component library for publish dialogs, chat, channel management, notifications, plugin onboarding, and account selection
    - client-side stores for user, agent, publish/plugin state, and caches
    It is the primary interactive UI that coordinates with the backend APIs and SSE/task streams.

12. The web app’s architecture reflects two usage modes:
    - marketing/public pages, SEO, and documentation content
    - authenticated product workflows for generating content, managing accounts, and launching publish/engagement tasks
    It also has explicit support for browser plugin flows and task/chat streaming, so the UI is built around live task state rather than simple form submission.

13. `project/aitoearn-electron` is a separate desktop product with a split architecture:
    - a React/Vite renderer UI
    - an Electron main process with modules for accounts, publish, reply, auto-run, tasks, tracing, tools, and platform integrations
    - a bundled server under `project/aitoearn-electron/server`
    The desktop app is not just a shell; it contains substantial automation logic and its own backend, likely for local workflows, plugin-style platform operations, and offline/sidecar features.

14. Deployment and operations are first-class in this repo:
    - `docker-compose.yml`, Nginx config, and Dockerfiles support self-hosted deployment
    - GitHub Actions run build/check/release workflows separately for backend and web
    - top-level `scripts` and backend `scripts/build-docker.mjs` support packaging
    - the backend README emphasizes API-key based usage, MCP endpoints, and optional relay configuration
    This suggests the architecture is intended for both SaaS hosting and private/self-hosted installations.

15. If you are drawing an architecture diagram, the clearest boundaries are:
    - clients: web app, Electron app, external MCP clients, browser/plugin flows
    - backend APIs: `aitoearn-server` for business workflows and `aitoearn-ai` for AI/agent execution
    - shared infrastructure: MongoDB, Redis, queues, object storage, email/SMS, platform APIs, AI providers
    - async workers/schedulers: publish, engagement, credits, notifications, AI task processing
    - optional relay/OAuth path for platform authorization in self-hosted deployments

Main entry points: [`project/aitoearn-backend/apps/aitoearn-server`](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-server) (Domain API), [`project/aitoearn-backend/apps/aitoearn-ai`](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-ai) (AI service), [`project/aitoearn-electron/server`](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-electron/server) (Desktop server), [`project/aitoearn-backend/libs`](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs) (Shared libs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_web["Web app<br/>Next.js product UI"]
end

subgraph group_backend["Backend"]
  node_backend_repo["Backend monorepo<br/>Nx/Nest backend"]
  node_server_app["Domain API<br/>NestJS app"]
  node_ai_app["AI service<br/>NestJS app"]
  node_shared_libs["Shared libs<br/>infrastructure libs"]
  node_mongo_lib[("Mongo layer<br/>persistence layer")]
  node_redis_lib[("Redis layer<br/>cache/pub-sub")]
  node_queue_lib["Queue layer<br/>job queues"]
  node_publish_flow["Publishing<br/>publish workflow"]
  node_engage_flow["Engagement<br/>interaction workflow"]
  node_content_flow["Content"]
  node_ai_orchestration["AI orchestration<br/>AI/task runtime"]
  node_model_adapters["Model adapters<br/>provider adapters"]
  node_mcp_tools["MCP tools<br/>tool modules"]
  node_server_client_lib["Server client<br/>typed SDK"]
  node_ai_client_lib["AI client<br/>typed SDK"]
  node_relay_oauth["Relay OAuth<br/>auth relay"]
end

subgraph group_desktop["Desktop"]
  node_electron["Desktop app<br/>Electron client"]
  node_electron_server["Desktop server<br/>bundled Nest API"]
end

subgraph group_deploy["Deploy"]
  node_deployment["Deploy assets<br/>docker/nginx<br/>[docker-compose.yml]"]
end

node_web -->|"uses APIs"| node_server_app
node_web -->|"streams tasks"| node_ai_app
node_web -.->|"shares contract"| node_server_client_lib
node_electron -->|"bundles backend"| node_electron_server
node_electron -->|"syncs data"| node_server_app
node_electron_server -->|"persists state"| node_mongo_lib
node_electron_server -->|"coordinates jobs"| node_redis_lib
node_electron_server -->|"processes work"| node_queue_lib
node_backend_repo -->|"contains"| node_server_app
node_backend_repo -->|"contains"| node_ai_app
node_backend_repo -->|"shares infra"| node_shared_libs
node_shared_libs -->|"includes"| node_mongo_lib
node_shared_libs -->|"includes"| node_redis_lib
node_shared_libs -->|"includes"| node_queue_lib
node_server_app -->|"owns"| node_content_flow
node_server_app -->|"owns"| node_publish_flow
node_server_app -->|"owns"| node_engage_flow
node_server_app -->|"delegates auth"| node_relay_oauth
node_server_app -->|"enqueues jobs"| node_queue_lib
node_server_app -->|"uses redis"| node_redis_lib
node_server_app -->|"stores domain data"| node_mongo_lib
node_ai_app -->|"implements"| node_ai_orchestration
node_ai_app -->|"uses providers"| node_model_adapters
node_ai_app -->|"exposes tools"| node_mcp_tools
node_ai_app -->|"consumes jobs"| node_queue_lib
node_ai_app -->|"locks state"| node_redis_lib
node_ai_app -->|"logs tasks"| node_mongo_lib
node_server_client_lib -->|"calls"| node_server_app
node_ai_client_lib -->|"calls"| node_ai_app
node_deployment -->|"packages"| node_backend_repo
node_deployment -->|"hosts"| node_web
node_deployment -.->|"packages"| node_electron_server

click node_web "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-web"
click node_electron "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-electron"
click node_electron_server "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-electron/server"
click node_backend_repo "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend"
click node_server_app "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-server"
click node_ai_app "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-ai"
click node_shared_libs "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs"
click node_mongo_lib "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs/mongodb"
click node_redis_lib "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs/redis"
click node_queue_lib "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs/aitoearn-queue"
click node_publish_flow "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-server/src/core/channel/publishing"
click node_engage_flow "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-server/src/core/channel/engagement"
click node_content_flow "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-server/src/core/content"
click node_ai_orchestration "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-ai/src/core"
click node_model_adapters "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-ai/src/core/ai/libs"
click node_mcp_tools "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-ai/src/core/agent/mcp"
click node_server_client_lib "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs/aitoearn-server-client"
click node_ai_client_lib "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs/aitoearn-ai-client"
click node_relay_oauth "https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-server/src/core/relay"
click node_deployment "https://github.com/yikart/aitoearn/blob/main/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web toneBlue
class node_backend_repo,node_server_app,node_ai_app,node_shared_libs,node_mongo_lib,node_redis_lib,node_queue_lib,node_publish_flow,node_engage_flow,node_content_flow,node_ai_orchestration,node_model_adapters,node_mcp_tools,node_server_client_lib,node_ai_client_lib,node_relay_oauth toneAmber
class node_electron,node_electron_server toneMint
class node_deployment toneRose
```

## Components

### Clients

User-facing apps and external client surfaces

- [Web app](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-web): Next.js product UI · Internationalized marketing site plus authenticated product workflows. · `project/aitoearn-web`

### Backend

Primary cloud backend monorepo and shared infrastructure

- [Backend monorepo](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend): Nx/Nest backend · Primary cloud backend with shared libraries, queues, persistence, and two NestJS apps. · `project/aitoearn-backend`
- [Domain API](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-server): NestJS app · Central business API for accounts, content, publishing, engagement, credits, and internal/admin flows. · `project/aitoearn-backend/apps/aitoearn-server`
- [AI service](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-ai): NestJS app · AI and agent execution service for chat, generation pipelines, MCP tools, and long-running jobs. · `project/aitoearn-backend/apps/aitoearn-ai`
- [Shared libs](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs): infrastructure libs · Common backend libraries for auth, queues, storage, MongoDB, Redis, redlock, MCP, mail, and SDK clients. · `project/aitoearn-backend/libs`
- [Mongo layer](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs/mongodb): persistence layer · Unified MongoDB repositories and schemas for users, accounts, content, media, tasks, credits, and notifications. · `project/aitoearn-backend/libs/mongodb`
- [Redis layer](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs/redis): cache/pub-sub · Redis client and pub-sub coordination for task state, shared locks, and runtime signaling. · `project/aitoearn-backend/libs/redis`
- [Queue layer](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs/aitoearn-queue): job queues · Queue abstractions, processors, metrics, and payload contracts for async work. · `project/aitoearn-backend/libs/aitoearn-queue`
- [Publishing](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-server/src/core/channel/publishing): publish workflow · Publish orchestration, staging, webhooks, schedulers, consumers, and platform-specific publishers. · `project/aitoearn-backend/apps/aitoearn-server/src/core/channel/publishing`
- [Engagement](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-server/src/core/channel/engagement): interaction workflow · Commenting and interaction task flow with providers, workers, and record tracking. · `project/aitoearn-backend/apps/aitoearn-server/src/core/channel/engagement`
- [Content](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-server/src/core/content): content/material domain · Material, media, and grouping APIs that feed publishing and AI-assisted creation. · `project/aitoearn-backend/apps/aitoearn-server/src/core/content`
- [AI orchestration](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-ai/src/core): AI/task runtime · Chat, draft generation, image/video tasks, material adaptation, and task status scheduling. · `project/aitoearn-backend/apps/aitoearn-ai/src/core`
- [Model adapters](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-ai/src/core/ai/libs): provider adapters · Provider integrations for Gemini, Grok, OpenAI, and Volcengine plus pricing/config management. · `project/aitoearn-backend/apps/aitoearn-ai/src/core/ai/libs`
- [MCP tools](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-ai/src/core/agent/mcp): tool modules · Agent tool implementations for media, subtitles, image/video editing, style transfer, and recap workflows. · `project/aitoearn-backend/apps/aitoearn-ai/src/core/agent/mcp`
- [Server client](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs/aitoearn-server-client): typed SDK · Backend client library used by other runtimes to call server-side account, content, platform, and task APIs. · `project/aitoearn-backend/libs/aitoearn-server-client`
- [AI client](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/libs/aitoearn-ai-client): typed SDK · Client library for calling the AI service from other backend modules or external consumers. · `project/aitoearn-backend/libs/aitoearn-ai-client`
- [Relay OAuth](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-backend/apps/aitoearn-server/src/core/relay): auth relay · Optional relay-based OAuth path for self-hosted deployments to avoid per-site platform app registration. · `project/aitoearn-backend/apps/aitoearn-server/src/core/relay`

### Desktop

Electron client and its bundled server

- [Desktop app](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-electron): Electron client · React/Vite desktop product with embedded automation and local workflows. · `project/aitoearn-electron`
- [Desktop server](https://github.com/yikart/aitoearn/tree/main/project/aitoearn-electron/server): bundled Nest API · Local/sidecar backend for the desktop client, including task, platform, finance, and user services. · `project/aitoearn-electron/server`

### Deploy

Top-level deployment and hosting assets

- [Deploy assets](https://github.com/yikart/aitoearn/blob/main/docker-compose.yml): docker/nginx · Top-level Docker Compose, Nginx config, and build scripts for self-hosted and packaged deployments. · `docker-compose.yml`

## Connections

- Web app → Domain API: uses APIs · Browser workflows call the main business API for accounts, content, publish, engagement, and notifications.
- Web app → AI service: streams tasks · The web app drives chat, draft generation, and agent task streams against the AI service.
- Web app → Server client: shares contract · Frontend state and API usage mirror backend contract patterns exposed by the server client.
- Desktop app → Desktop server: bundles backend · The desktop client includes a substantial local server for automation and platform operations.
- Desktop app → Domain API: syncs data · Desktop UI consumes the central business API for user, account, publish, and task data.
- Desktop server → Mongo layer: persists state · The bundled server stores users, accounts, tasks, records, and operational data in MongoDB.
- Desktop server → Redis layer: coordinates jobs · Local server modules use Redis for state sharing, locking, and task coordination.
- Desktop server → Queue layer: processes work · Desktop server uses queues for async task audits and workflow processing.
- Backend monorepo → Domain API: contains · The Nx monorepo hosts the main domain API application.
- Backend monorepo → AI service: contains · The Nx monorepo hosts the AI/agent execution application.
- Backend monorepo → Shared libs: shares infra · Both backend apps depend on shared infrastructure libraries.
- Shared libs → Mongo layer: includes · MongoDB repositories and schemas centralize persistence for backend services.
- Shared libs → Redis layer: includes · Redis support is packaged as a shared backend module.
- Shared libs → Queue layer: includes · Queue processors and contracts are centralized in shared libraries.
- Domain API → Content: owns · The main API owns content, material, and media management.
- Domain API → Publishing: owns · Publishing is a core domain boundary of the main API.
- Domain API → Engagement: owns · Engagement and interaction workflows are managed separately from publishing.
- Domain API → Relay OAuth: delegates auth · Self-hosted deployments can route platform authorization through the relay OAuth service.
- Domain API → Queue layer: enqueues jobs · Controllers hand off publishing, engagement, credits, notifications, and media work to queues.
- Domain API → Redis layer: uses redis · Redis supports pub/sub, locks, rate sharing, and coordination in the main API.
- Domain API → Mongo layer: stores domain data · The business API persists accounts, publish records, media, credits, notifications, and users in MongoDB.
- AI service → AI orchestration: implements · The AI service hosts chat, generation, adaptation, and agent runtime modules.
- AI service → Model adapters: uses providers · Model-specific adapters connect the service to Gemini, Grok, OpenAI, and Volcengine.
- AI service → MCP tools: exposes tools · The AI service publishes MCP tool modules for external agents and internal automation.
- AI service → Queue layer: consumes jobs · AI generation and status handling are driven by asynchronous queue workers and consumers.
- AI service → Redis layer: locks state · Task orchestration uses Redis for redlock-style coordination and shared runtime state.
- AI service → Mongo layer: logs tasks · AI logs, tasks, assets, and adaptation state are persisted in MongoDB.
- Server client → Domain API: calls · Typed client package wraps main backend endpoints for reuse by other runtimes.
- AI client → AI service: calls · Typed client package wraps AI service endpoints for reuse by other runtimes.
- Deploy assets → Backend monorepo: packages · Docker and build scripts package the backend monorepo for release and self-hosted deployment.
- Deploy assets → Web app: hosts · Nginx and container assets support deploying the web application.
- Deploy assets → Desktop server: packages · Desktop release assets include containerized packaging for the bundled server.
