# rixz-dev/base-ryn-ai architecture

> Architecture diagram of the GitHub repository rixz-dev/base-ryn-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rixz-dev/base-ryn-ai
- Repository: https://github.com/rixz-dev/base-ryn-ai

## Overview

1. **What this repo is**
   - A **Node.js virtual assistant / chat-bot** called RYN AI.
   - The architecture is centered on **conversation handling**, **memory/state**, **LLM calls**, and **background automation**.
   - It is not a full product yet; README explicitly says this is a base version.

2. **Process entry and runtime**
   - `index.js` is the main application entrypoint.
   - `ecosystem.config.js` suggests it is meant to run under a process manager such as **PM2**.
   - `.env` holds runtime configuration for API keys, tokens, and environment-specific settings.

3. **Inbound interaction layer**
   - `handlers/message.js` handles text/chat messages.
   - `handlers/photo.js` handles image inputs.
   - These handlers are the main boundary between external user input and the assistant’s internal orchestration.

4. **AI client boundary**
   - `ai/client.js` is the core adapter to the model/provider layer.
   - The README points to **NVIDIA NIM** as the intended AI backend.
   - This module likely isolates prompt submission, response parsing, and provider-specific calls from the rest of the app.

5. **Cognitive state / “brain” subsystem**
   - The `brain/` folder is the assistant’s internal state and reasoning layer.
   - `brain/memory.js` stores or retrieves conversational context and long-term recall.
   - `brain/mood.js` and `brain/emotion.js` track inferred user/assistant state.
   - `brain/dates.js` likely normalizes time-related context and date awareness.
   - `brain/prompt.js` assembles the system/context prompt sent to the model.
   - `brain/consolidation.js` suggests periodic summarization or memory compression.

6. **Tooling and capability layer**
   - `tools/` contains external-action modules the assistant can invoke.
   - `tools/search.js`, `tools/weather.js`, `tools/reader.js`, and `tools/digest.js` are web/data utilities.
   - `tools/vision.js` and `tools/voice.js` represent multimodal capabilities, though the README notes these are currently error-prone.
   - `tools/index.js` likely exports or routes available tools to the AI orchestration layer.

7. **Typical request flow**
   - User message/photo arrives through a handler.
   - The handler consults the brain layer for memory, mood, date context, and prompt construction.
   - The AI client sends the composed prompt to the model.
   - If the model or orchestrator decides a tool is needed, a module in `tools/` is called.
   - The result is merged back into the conversation response and possibly stored in memory.

8. **Background automation**
   - `scheduler/cron.js` indicates scheduled jobs.
   - This is where autonomous features live: reminders, periodic notifications, consolidation, or digest generation.
   - This subsystem is separate from live chat handling and runs on a time trigger rather than user input.

9. **Autonomous behavior and notifications**
   - The README calls out “auto notification” and “autonomous,” which implies the bot can initiate actions without a direct message.
   - That behavior most likely depends on the scheduler plus brain/memory state to decide when to notify or summarize.

10. **External dependencies and integration points**
   - The main external boundary is the **LLM provider** via `ai/client.js`.
   - The web-related tools likely depend on third-party services for search, weather, and content reading.
   - Voice and vision are present as planned features, but the README suggests they are not stable yet.

11. **State and persistence**
   - Memory is a first-class architectural concern here, not an afterthought.
   - The `brain/` modules imply the assistant maintains both short-term conversation context and longer-lived remembered facts.
   - `brain/consolidation.js` likely transforms accumulated interactions into smaller stored summaries.

12. **Diagramming summary**
   - The clearest architecture diagram should show four main zones:
     - **Inbound handlers** (`message`, `photo`)
     - **Brain/orchestration** (`memory`, `prompt`, `emotion`, `mood`, `dates`, `consolidation`)
     - **AI + tools** (`ai/client`, `tools/*`)
     - **Schedulers/automation** (`scheduler/cron`)
   - The central control flow is: **user input or scheduled event → brain context → AI client → optional tools → response/notification → memory update**.

Main entry points: [`handlers/message.js`](https://github.com/rixz-dev/base-ryn-ai/blob/main/handlers/message.js) (Text handler), [`tools/index.js`](https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/index.js) (Tool router), [`scheduler/cron.js`](https://github.com/rixz-dev/base-ryn-ai/blob/main/scheduler/cron.js) (Cron), [`brain/memory.js`](https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/memory.js) (Memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_index_js["App entry<br/>entrypoint<br/>[index.js]"]
  node_ecosystem_config_js["PM2 config<br/>process config"]
end

subgraph group_inbound["Inbound"]
  node_handlers_message_js["Text handler<br/>chat ingress<br/>[message.js]"]
  node_handlers_photo_js["Photo handler<br/>media ingress<br/>[photo.js]"]
end

subgraph group_brain["Brain"]
  node_brain_memory_js[("Memory<br/>state store<br/>[memory.js]")]
  node_brain_prompt_js["Prompt builder<br/>context composer<br/>[prompt.js]"]
  node_brain_emotion_js(("Emotion<br/>affect state<br/>[emotion.js]"))
  node_brain_mood_js(("Mood<br/>affect state<br/>[mood.js]"))
  node_brain_dates_js(("Dates<br/>time context<br/>[dates.js]"))
  node_brain_consolidation_js{{"Consolidation<br/>summary job<br/>[consolidation.js]"}}
end

subgraph group_ai["AI + Tools"]
  node_ai_client_js["AI client<br/>llm adapter<br/>[client.js]"]
  node_tools_index_js["Tool router<br/>tool registry<br/>[index.js]"]
  node_tools_search_js["Search<br/>web tool<br/>[search.js]"]
  node_tools_weather_js["Weather<br/>external tool<br/>[weather.js]"]
  node_tools_reader_js["Reader<br/>content tool<br/>[reader.js]"]
  node_tools_digest_js["Digest<br/>summary tool<br/>[digest.js]"]
  node_tools_vision_js["Vision<br/>multimodal tool<br/>[vision.js]"]
  node_tools_voice_js["Voice<br/>multimodal tool<br/>[voice.js]"]
end

subgraph group_automation["Automation"]
  node_scheduler_cron_js{{"Cron<br/>scheduler<br/>[cron.js]"}}
end

node_index_js -->|"wires"| node_handlers_message_js
node_index_js -->|"wires"| node_handlers_photo_js
node_index_js -->|"starts"| node_scheduler_cron_js
node_index_js -.->|"deploys with"| node_ecosystem_config_js
node_handlers_message_js -->|"reads/writes"| node_brain_memory_js
node_handlers_message_js -->|"builds"| node_brain_prompt_js
node_handlers_message_js -->|"consults"| node_brain_emotion_js
node_handlers_message_js -->|"consults"| node_brain_mood_js
node_handlers_message_js -->|"consults"| node_brain_dates_js
node_handlers_message_js -->|"calls"| node_ai_client_js
node_handlers_photo_js -->|"reads/writes"| node_brain_memory_js
node_handlers_photo_js -->|"builds"| node_brain_prompt_js
node_handlers_photo_js -->|"calls"| node_ai_client_js
node_brain_prompt_js -->|"feeds"| node_ai_client_js
node_brain_memory_js -.->|"supplies"| node_brain_consolidation_js
node_brain_consolidation_js -->|"updates"| node_brain_memory_js
node_ai_client_js -->|"enables tools"| node_tools_index_js
node_tools_index_js -->|"exports"| node_tools_search_js
node_tools_index_js -->|"exports"| node_tools_weather_js
node_tools_index_js -->|"exports"| node_tools_reader_js
node_tools_index_js -->|"exports"| node_tools_digest_js
node_tools_index_js -->|"exports"| node_tools_vision_js
node_tools_index_js -->|"exports"| node_tools_voice_js
node_scheduler_cron_js -->|"runs"| node_brain_consolidation_js
node_scheduler_cron_js -->|"runs"| node_tools_digest_js
node_scheduler_cron_js -->|"consults"| node_brain_memory_js
node_scheduler_cron_js -->|"calls"| node_ai_client_js

click node_index_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/index.js"
click node_ecosystem_config_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/ecosystem.config.js"
click node_handlers_message_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/handlers/message.js"
click node_handlers_photo_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/handlers/photo.js"
click node_brain_memory_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/memory.js"
click node_brain_prompt_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/prompt.js"
click node_brain_emotion_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/emotion.js"
click node_brain_mood_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/mood.js"
click node_brain_dates_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/dates.js"
click node_brain_consolidation_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/consolidation.js"
click node_ai_client_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/ai/client.js"
click node_tools_index_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/index.js"
click node_tools_search_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/search.js"
click node_tools_weather_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/weather.js"
click node_tools_reader_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/reader.js"
click node_tools_digest_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/digest.js"
click node_tools_vision_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/vision.js"
click node_tools_voice_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/voice.js"
click node_scheduler_cron_js "https://github.com/rixz-dev/base-ryn-ai/blob/main/scheduler/cron.js"

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_index_js,node_ecosystem_config_js toneBlue
class node_handlers_message_js,node_handlers_photo_js toneAmber
class node_brain_memory_js,node_brain_prompt_js,node_brain_emotion_js,node_brain_mood_js,node_brain_dates_js,node_brain_consolidation_js toneMint
class node_ai_client_js,node_tools_index_js,node_tools_search_js,node_tools_weather_js,node_tools_reader_js,node_tools_digest_js,node_tools_vision_js,node_tools_voice_js toneRose
class node_scheduler_cron_js toneIndigo
```

## Components

### Runtime

Process entry and deployment

- [App entry](https://github.com/rixz-dev/base-ryn-ai/blob/main/index.js): entrypoint · Main application bootstrap and runtime wiring · `index.js`
- [PM2 config](https://github.com/rixz-dev/base-ryn-ai/blob/main/ecosystem.config.js): process config · Process manager configuration for deployment/runtime · `ecosystem.config.js`

### Inbound

User-facing input handlers

- [Text handler](https://github.com/rixz-dev/base-ryn-ai/blob/main/handlers/message.js): chat ingress · Routes incoming text messages into assistant flow · `handlers/message.js`
- [Photo handler](https://github.com/rixz-dev/base-ryn-ai/blob/main/handlers/photo.js): media ingress · Handles image-based user input · `handlers/photo.js`

### Brain

State, context, and prompt assembly

- [Memory](https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/memory.js): state store · Conversation context and longer-term recall · `brain/memory.js`
- [Prompt builder](https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/prompt.js): context composer · Builds the system and conversation prompt · `brain/prompt.js`
- [Emotion](https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/emotion.js): affect state · Tracks inferred emotional state · `brain/emotion.js`
- [Mood](https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/mood.js): affect state · Tracks assistant or user mood signals · `brain/mood.js`
- [Dates](https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/dates.js): time context · Normalizes date and time-aware context · `brain/dates.js`
- [Consolidation](https://github.com/rixz-dev/base-ryn-ai/blob/main/brain/consolidation.js): summary job · Compresses or summarizes accumulated memory · `brain/consolidation.js`

### AI + Tools

Model client and callable capabilities

- [AI client](https://github.com/rixz-dev/base-ryn-ai/blob/main/ai/client.js): llm adapter · Provider boundary for model calls and response handling · `ai/client.js`
- [Tool router](https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/index.js): tool registry · Exposes available assistant tools · `tools/index.js`
- [Search](https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/search.js): web tool · Searches external sources · `tools/search.js`
- [Weather](https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/weather.js): external tool · Fetches weather data · `tools/weather.js`
- [Reader](https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/reader.js): content tool · Reads or extracts content from sources · `tools/reader.js`
- [Digest](https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/digest.js): summary tool · Produces digests or summaries · `tools/digest.js`
- [Vision](https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/vision.js): multimodal tool · Image-related capability, currently unstable · `tools/vision.js`
- [Voice](https://github.com/rixz-dev/base-ryn-ai/blob/main/tools/voice.js): multimodal tool · Audio-related capability, currently unstable · `tools/voice.js`

### Automation

Scheduled background work

- [Cron](https://github.com/rixz-dev/base-ryn-ai/blob/main/scheduler/cron.js): scheduler · Runs autonomous and periodic background jobs · `scheduler/cron.js`

## Connections

- App entry → Text handler: wires · Bootstraps text message handling
- App entry → Photo handler: wires · Bootstraps photo handling
- App entry → Cron: starts · Starts background automation
- App entry → PM2 config: deploys with · Designed to run under process manager config
- Text handler → Memory: reads/writes · Uses conversation state and recall
- Text handler → Prompt builder: builds · Composes prompt context for the model
- Text handler → Emotion: consults · Incorporates emotional state
- Text handler → Mood: consults · Incorporates mood signals
- Text handler → Dates: consults · Adds time-aware context
- Text handler → AI client: calls · Sends the assembled prompt to the model layer
- Photo handler → Memory: reads/writes · Uses conversation state and recall
- Photo handler → Prompt builder: builds · Composes multimodal prompt context
- Photo handler → AI client: calls · Sends image-aware requests to the model layer
- Prompt builder → AI client: feeds · Provides the final context passed to the LLM
- Memory → Consolidation: supplies · Provides accumulated state for summarization
- Consolidation → Memory: updates · Writes compact summaries back into memory
- AI client → Tool router: enables tools · Allows model-driven tool invocation
- Tool router → Search: exports · Registers search capability
- Tool router → Weather: exports · Registers weather capability
- Tool router → Reader: exports · Registers reader capability
- Tool router → Digest: exports · Registers digest capability
- Tool router → Vision: exports · Registers vision capability
- Tool router → Voice: exports · Registers voice capability
- Cron → Consolidation: runs · Triggers periodic memory consolidation
- Cron → Digest: runs · Generates scheduled digests and updates
- Cron → Memory: consults · Uses stored state for autonomous actions
- Cron → AI client: calls · Can initiate model-backed background tasks