# david-patrick-chuks/riona-ai-agent architecture

> Architecture diagram of the GitHub repository david-patrick-chuks/riona-ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/david-patrick-chuks/riona-ai-agent
- Repository: https://github.com/david-patrick-chuks/riona-ai-agent

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Entrypoint Layer"
        E1["src/index.ts"]:::infra
        E2["src/app.ts"]:::infra
        E3["src/server.ts"]:::infra
    end

    subgraph "Configuration & Secrets"
        CFG1[".env.example"]:::config
        CFG2["src/config/db.ts"]:::config
        CFG3["src/config/logger.ts"]:::config
        CFG4["src/secret/index.ts"]:::config
    end

    subgraph "Orchestration & Services"
        SVC["src/services/index.ts"]:::infra
    end

    subgraph "Domain Logic (Agent Module)"
        A1["src/Agent/index.ts"]:::agent
        subgraph "Characters"
            A2["src/Agent/characters"]:::agent
            A3["src/Agent/characters/ArcanEdge.System.Agent.json"]:::agent
            A4["src/Agent/characters/elon.character.json"]:::agent
            A5["src/Agent/characters/sample.character.json"]:::agent
        end
        A6["src/Agent/schema/index.ts"]:::agent
        A7["src/Agent/script/summarize.ts"]:::agent
        subgraph "Training Subsystem"
            T1["src/Agent/training/FilesTraining.ts"]:::agent
            T2["src/Agent/training/TrainWithAudio.ts"]:::agent
            T3["src/Agent/training/WebsiteScraping.ts"]:::agent
            T4["src/Agent/training/youtubeURL.ts"]:::agent
        end
    end

    subgraph "Infrastructure Adapters (Client Module)"
        C1["src/client/IG-bot/index.ts"]:::client
        C2["src/client/Instagram.ts"]:::client
        C3["src/client/X-bot/index.ts"]:::client
        C4["src/client/X-bot/client/index.ts"]:::client
        C5["src/client/Twitter.ts"]:::client
        C6["src/client/Github.ts"]:::client
    end

    subgraph "Utilities"
        U1["src/utils/download.ts"]:::infra
        U2["src/utils/index.ts"]:::infra
    end

    subgraph "Scripts & Codegen"
        SC["src/scripts/generateCharacter.ts"]:::infra
    end

    subgraph "Testing"
        TST1["src/test/index.ts"]:::infra
        TST2["src/test/tweets.ts"]:::infra
    end

    subgraph "External Services"
        Ext1["Google Generative AI"]:::external
        Ext2["Puppeteer"]:::external
        Ext3["Instagram Web"]:::external
        Ext4["MongoDB"]:::external
    end

    subgraph "Cross-Cutting"
        ERR["src/types/puppeteer.d.ts"]:::cross
    end

    E1 --> E2 --> E3
    E2 -->|"load config"| CFG2
    E2 -->|"load config"| CFG3
    E2 -->|"load secrets"| CFG4
    CFG2 -->|"connect"| Ext4
    E2 -->|"init services"| SVC
    SVC -->|"invoke agent"| A1
    SVC -->|"invoke client"| C1
    A1 -->|"load characters"| A2
    A1 -->|"use schema"| A6
    A1 -->|"summarize"| A7
    A1 -->|"train"| T1
    A1 -->|"train"| T2
    A1 -->|"train"| T3
    A1 -->|"train"| T4
    A1 -->|"generate content"| Ext1
    C1 -->|"automation"| Ext2
    C1 -->|"target"| Ext3
    C2 -->|"helper"| Ext2
    C3 -->|"future bot"| Ext2
    C4 -->|"future client"| Ext2
    U1 --> SVC
    U2 --> SVC
    SC --> A1
    SC --> A2
    TST1 --> A1
    TST2 --> C3
    CFG3 --> E2
    CFG3 --> SVC
    CFG3 --> A1
    CFG3 --> C1

    click E1 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/index.ts"
    click E2 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/app.ts"
    click E3 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/server.ts"
    click CFG1 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/.env.example"
    click CFG2 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/config/db.ts"
    click CFG3 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/config/logger.ts"
    click CFG4 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/secret/index.ts"
    click SVC "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/services/index.ts"
    click A1 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/Agent/index.ts"
    click A2 "https://github.com/david-patrick-chuks/riona-ai-agent/tree/main/src/Agent/characters"
    click A3 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/Agent/characters/ArcanEdge.System.Agent.json"
    click A4 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/Agent/characters/elon.character.json"
    click A5 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/Agent/characters/sample.character.json"
    click A6 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/Agent/schema/index.ts"
    click A7 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/Agent/script/summarize.ts"
    click T1 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/Agent/training/FilesTraining.ts"
    click T2 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/Agent/training/TrainWithAudio.ts"
    click T3 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/Agent/training/WebsiteScraping.ts"
    click T4 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/Agent/training/youtubeURL.ts"
    click C1 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/client/IG-bot/index.ts"
    click C2 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/client/Instagram.ts"
    click C3 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/client/X-bot/index.ts"
    click C4 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/client/X-bot/client/index.ts"
    click C5 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/client/Twitter.ts"
    click C6 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/client/Github.ts"
    click U1 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/utils/download.ts"
    click U2 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/utils/index.ts"
    click SC "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/scripts/generateCharacter.ts"
    click TST1 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/test/index.ts"
    click TST2 "https://github.com/david-patrick-chuks/riona-ai-agent/blob/main/src/test/tweets.ts"

    classDef agent fill:#f9f,stroke:#333,stroke-width:1px
    classDef client fill:#9ff,stroke:#333,stroke-width:1px
    classDef infra fill:#ff9,stroke:#333,stroke-width:1px
    classDef config fill:#ccf,stroke:#333,stroke-width:1px
    classDef cross fill:#cfc,stroke:#333,stroke-width:1px
    classDef external fill:#eee,stroke:#333,stroke-width:1px
```
