How david-patrick-chuks/riona-ai-agent works
Project Type and Purpose
• This is an AI-powered automation tool (not a web app) written in Node.js/TypeScript.
• Its core purpose is to train an AI agent on user-provided data (audio, PDF, URLs, etc.) and then automate social-media interactions (posting, liking, commenting) on Instagram (with upcoming support for Twitter and GitHub).
• The project uses Puppeteer for browser automation, Google Generative AI for content creation, and MongoDB for session/cookie persistence.
File Structure
• Top-level config files: .env.example, tsconfig.json, package.json, Docker scripts for MongoDB.
• src/Agent: Agent logic, character schemas, training scripts (audio, web scraping, YouTube).
• src/client: Per-platform automation clients (IG-bot, X-bot/Twitter, GitHub stub).
• src/config: db.ts (Mongo connection), logger.ts (winston or similar).
• src/utils: download helper, cookie and file helpers.
• src/services: likely contains wrappers around business operations (persisting cookies, scheduling tasks).
• src/app.ts & src/server.ts: entrypoints. app.ts orchestrates modules, server.ts might expose an HTTP API or CLI commands.
• src/scripts: codegen utilities for characters.
• src/test: sample data and test cases.
• secret/index.ts: holds secrets loader or key-management.
README for Additional Insights
• Architectural overview: modular separation of Agent, client, config, utils.
• Describes dependency on Puppeteer, puppeteer-extra, Google AI, MongoDB.
• Explains “agent training” vs. “agent execution” phases.
Main Components
a. Agent Module
• Training subsystem (YouTubeScraping, WebsiteScraping, Audio training).
• Summarization/Text generation script.
• Character schema definitions.
b. Client Module
• Instagram client (login, post, like, comment).
• X/Twitter client (future).
• GitHub client (future).
c. Persistence Layer
• MongoDB (sessions, cookies, agent metadata, usage logs).
d. AI & External Services
• Google Generative AI APIs.
• Puppeteer / puppeteer-extra for browser automation.
• Proxy provider (optional).
e. Orchestration Layer
• app.ts / server.ts: command dispatcher or HTTP endpoints.
• Services: high-level business logic invoking Agent + Clients + Persistence.
f. Cross-Cutting Concerns
• Logger (winston).
• Configuration (.env, config/db.ts, config/logger.ts).
• Error handlers (process.on('unhandledRejection'), uncaughtException).
Relationships & Interactions
• User (CLI or API) → Orchestration Layer (app.ts)
→ Loads Config → Connects to MongoDB
→ Initializes Agent & Client modules
→ Agent generates content via Google AI → returns captions/comments
→ Client module logs into Instagram via Puppeteer → posts content
→ Persistence Layer saves cookies/session and logs
• Agent Training: obtains data from
• WebsiteScraping (HTTP fetch → parse → feed to training)
• YouTube URL (download & transcribe → feed)
• Local files (PDF, TXT, MP3) → feed
→ Agents’ character JSON updated in MongoDB or local file store.
Architectural Patterns & Principles
• Modular layering:
1. Presentation/Entrypoint (app.ts, server.ts)
2. Application/Orchestration (src/services, controllers)
3. Domain Logic (src/Agent)
4. Infrastructure Adapters (src/client, src/config/db.ts, src/utils)
• Plugin-style clients for each social platform (enables easy extension).
• Single Responsibility: separate training scripts from runtime execution.
• Externalization of config and secrets.
Essential Notes
• Both synchronous flows (generate content → post) and asynchronous flows (training jobs → update character definitions).