# akazdayo/aikyo-discord architecture

> Architecture diagram of the GitHub repository akazdayo/aikyo-discord, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akazdayo/aikyo-discord
- Repository: https://github.com/akazdayo/aikyo-discord

## Overview

##### Project Type and Purpose
- This is a lightweight Node.js/TypeScript “Aikyo Companion” template: a small framework that boots multiple conversational AI agents (companions) and wires them together via a Firehose WebSocket server and libp2p for peer-to-peer communication. It serves as a starter kit for launching and orchestrating AI personas (e.g. “kyoko” and “aya”), connecting them to the Anthropic API, and streaming messages to clients.

##### File Structure Analysis
- Top level
- src/index.ts: main entrypoint, starts companion loops + Firehose server
- src/cards/: persona definitions (prompts, tools, seeded history)
- src/tools/: plugin directory for Aikyo Tools (e.g. knowledge or action modules)
- src/utils/: runtime helpers
– companion.ts: companion loop orchestration
– discordClient.ts: (optional) Discord integration factory
– firehose.ts: Firehose WebSocket server factory
– types/: shared Zod schemas for companion, firehose, Discord, etc.
- Config & Dev
- .env.example / .env: API keys (Anthropic) and other environment variables
- package.json / pnpm-lock.yaml: dependencies & scripts (dev, dev:debug)
- example_request.json: sample client payload for testing via websocat

##### Key README Insights
- Boot process: “pnpm run dev” → tsx src/index.ts
- By default, it instantiates two agents and listens on WS port 8080
- Supports verbose libp2p logs with DEBUG=libp2p:*
- Encourages adding custom Tools under src/tools/

## Diagram (Mermaid)

```mermaid
graph TB
    %% Configuration
    Env[".env.example"]:::config
    Package["package.json"]:::config
    SampleReq["example_request.json"]:::config

    %% Boot
    Boot["Boot Process\n(src/index.ts)"]:::internal

    %% Client
    Client["Client\n(WebSocket Consumer)"]:::external

    %% Firehose Server
    Firehose["Firehose WS Server"]:::internal

    %% Runtime Container
    subgraph "Runtime" 
        direction TB
        Zod["Zod Schema Validator"]:::internal

        %% Companion Core (code)
        CompanionCore["Companion Loop Core"]:::internal

        %% Companion Instances
        KyLoop["Kyoko Companion Loop"]:::internal
        AyLoop["Aya Companion Loop"]:::internal
    end

    %% Extension Modules Boundary
    subgraph "Extension Modules" 
        style Extension Modules stroke-dasharray: 5 5
        direction TB
        subgraph "Persona Cards" 
            direction TB
            KyokoCard["kyoko.ts\n(src/cards/)"]:::plugin
            AyaCard["aya.ts\n(src/cards/)"]:::plugin
        end
        subgraph "Tools Plugin" 
            direction TB
            Tools["src/tools/"]:::plugin
        end
    end

    %% P2P Network
    P2P["libp2p Overlay\n(P2P Network)"]:::internal

    %% External LLM Service
    Anthropic["Anthropic API"]:::external

    %% Discord Integration (Optional)
    Discord["Discord Integration\nFactory"]:::external

    %% Relationships
    Boot --> Firehose
    Boot --> Runtime

    Client -->|"WS request/response"| Firehose
    Firehose -->|"distribute requests"| KyLoop
    Firehose -->|"distribute requests"| AyLoop

    KyLoop -->|"invoke HTTP POST"| Anthropic
    AyLoop -->|"invoke HTTP POST"| Anthropic

    KyLoop -->|"P2P message"| P2P
    AyLoop -->|"P2P message"| P2P

    KyLoop -->|"call tool modules"| Tools
    AyLoop -->|"call tool modules"| Tools

    %% Core and validation
    KyLoop -->|"use core logic"| CompanionCore
    AyLoop -->|"use core logic"| CompanionCore

    KyLoop -->|"validate schemas"| Zod
    AyLoop -->|"validate schemas"| Zod

    %% Config into runtime
    Env -->|"load variables"| Runtime

    %% Optional Discord integration
    Boot -->|"factory init"| Discord

    %% Click Events
    click Boot "https://github.com/akazdayo/aikyo-discord/blob/main/src/index.ts"
    click Firehose "https://github.com/akazdayo/aikyo-discord/blob/main/src/utils/firehose.ts"
    click CompanionCore "https://github.com/akazdayo/aikyo-discord/blob/main/src/utils/companion.ts"
    click KyokoCard "https://github.com/akazdayo/aikyo-discord/blob/main/src/cards/kyoko.ts"
    click AyaCard "https://github.com/akazdayo/aikyo-discord/blob/main/src/cards/aya.ts"
    click Tools "https://github.com/akazdayo/aikyo-discord/tree/main/src/tools/"
    click Discord "https://github.com/akazdayo/aikyo-discord/blob/main/src/utils/discordClient.ts"
    click SampleReq "https://github.com/akazdayo/aikyo-discord/blob/main/example_request.json"
    click Env "https://github.com/akazdayo/aikyo-discord/blob/main/.env.example"
    click Package "https://github.com/akazdayo/aikyo-discord/blob/main/package.json"
    classDef internal fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef external fill:#DFFFD0,stroke:#000,stroke-width:1px
    classDef plugin fill:#FFE0B2,stroke:#000,stroke-width:1px
    classDef config fill:#E0E0E0,stroke:#000,stroke-width:1px
```
