How yikart/aitoearn works
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: aitoearn-server Domain API · aitoearn-ai AI service · server Desktop server · libs Shared libs
Components 20
Clients
User-facing apps and external client surfaces
- Web app · Internationalized marketing site plus authenticated product workflows.
project/aitoearn-web
Backend
Primary cloud backend monorepo and shared infrastructure
- Backend monorepo · Primary cloud backend with shared libraries, queues, persistence, and two NestJS apps.
project/aitoearn-backend - Domain API · Central business API for accounts, content, publishing, engagement, credits, and internal/admin flows.
project/aitoearn-backend/apps/aitoearn-server - AI service · AI and agent execution service for chat, generation pipelines, MCP tools, and long-running jobs.
project/aitoearn-backend/apps/aitoearn-ai - Shared libs · Common backend libraries for auth, queues, storage, MongoDB, Redis, redlock, MCP, mail, and SDK clients.
project/aitoearn-backend/libs - Mongo layer · Unified MongoDB repositories and schemas for users, accounts, content, media, tasks, credits, and notifications.
project/aitoearn-backend/libs/mongodb - Redis layer · Redis client and pub-sub coordination for task state, shared locks, and runtime signaling.
project/aitoearn-backend/libs/redis - Queue layer · Queue abstractions, processors, metrics, and payload contracts for async work.
project/aitoearn-backend/libs/aitoearn-queue - Publishing · Publish orchestration, staging, webhooks, schedulers, consumers, and platform-specific publishers.
project/aitoearn-backend/apps/aitoearn-server/src/core/channel/publishing - Engagement · Commenting and interaction task flow with providers, workers, and record tracking.
project/aitoearn-backend/apps/aitoearn-server/src/core/channel/engagement - Content · Material, media, and grouping APIs that feed publishing and AI-assisted creation.
project/aitoearn-backend/apps/aitoearn-server/src/core/content - AI orchestration · Chat, draft generation, image/video tasks, material adaptation, and task status scheduling.
project/aitoearn-backend/apps/aitoearn-ai/src/core - Model 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 · 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 · 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 · Client library for calling the AI service from other backend modules or external consumers.
project/aitoearn-backend/libs/aitoearn-ai-client - Relay OAuth · 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 · React/Vite desktop product with embedded automation and local workflows.
project/aitoearn-electron - Desktop server · 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 · Top-level Docker Compose, Nginx config, and build scripts for self-hosted and packaged deployments.
docker-compose.yml
Connections 32
- 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.