# whitewolf251501-dot/aa-os-yuvi architecture

> Architecture diagram of the GitHub repository whitewolf251501-dot/aa-os-yuvi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/whitewolf251501-dot/aa-os-yuvi
- Repository: https://github.com/whitewolf251501-dot/aa-os-yuvi

## Overview

YUVI is a browser-based AI business operating system for running a small growth-agency workspace. Its main interaction is a user sending a message through the app: intent detection routes recognized requests to skills, while other messages are enriched with business, memory, and knowledge context before going to Groq and returning to the chat. The workspace also covers lead/client management, generated-output libraries and chat widgets, uploaded knowledge, proactive follow-ups, and configurable skills. The README documents the core chat and skill flow; sampled source supports knowledge and widget behavior, while some workspace wiring is only visible in the app as a whole.

Main entry points: [`app.js`](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/app.js) (App Workspace), [`memory/contextBuilder.js`](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/memory/contextBuilder.js) (Context Builder), [`brain/brain.js`](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/brain.js) (Brain API), [`integrations/groq.js`](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/integrations/groq.js) (Groq Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Business Workspace"]
  node_app["App Workspace<br/>[app.js]"]
  node_chat_ui["Chat Interface<br/>[index.html]"]
  node_crm["Leads And Clients<br/>[app.js]"]
  node_library["Output Library<br/>[libraryEngine.js]"]
  node_widgets["Chat Widgets<br/>[widgetEngine.js]"]
end

subgraph group_ai["AI Conversation"]
  node_brain["Brain API<br/>[brain.js]"]
  node_intent["Intent Detection<br/>[intentDetector.js]"]
  node_composer["Prompt Composer<br/>[promptComposer.js]"]
  node_skill_orch["Skill Orchestrator"]
  node_groq_adapter["Groq Adapter<br/>[groq.js]"]
end

subgraph group_capabilities["Skills And Knowledge"]
  node_registry["Skill Registry<br/>[skillRegistry.js]"]
  node_loader["Skill Loader<br/>[skillLoader.js]"]
  node_skill_manager["Skill Manager<br/>[skillManager.js]"]
  node_prompt_skills["Uploaded Prompt Skills"]
  node_parser["File Parser<br/>[fileParser.js]"]
  node_knowledge["Knowledge Manager"]
end

subgraph group_state["Memory And Security"]
  node_context["Context Builder<br/>[contextBuilder.js]"]
  node_browser_store[("Browser Storage<br/>[contextBuilder.js]")]
  node_vault[("Encrypted Vault<br/>[vault.js]")]
  node_webauthn["Biometric Helper<br/>[webauthn.js]"]
end

subgraph group_integrations["Automation And Integrations"]
  node_event_bus["Event Bus<br/>[eventBus.js]"]
  node_event_rules["Event Rules<br/>[eventRules.js]"]
  node_scheduler["Scheduler<br/>[scheduler.js]"]
  node_proactive["Proactive Engine<br/>[proactiveEngine.js]"]
  node_github{{"GitHub Memory<br/>[github.js]"}}
  node_canva["Canva Links<br/>[canva.js]"]
  node_whatsapp["WhatsApp Links<br/>[whatsapp.js]"]
  node_n8n["n8n Integration<br/>[n8n.js]"]
end

node_user(("Business User"))
node_groq_service{{"Groq API"}}

node_user -->|"sends message"| node_chat_ui
node_chat_ui -->|"forwards input"| node_app
node_app -->|"calls chat"| node_brain
node_brain -->|"detects intent"| node_intent
node_intent -->|"routes match"| node_skill_orch
node_skill_orch -->|"executes skill"| node_registry
node_brain -->|"composes fallback"| node_composer
node_composer -->|"requests context"| node_context
node_context -->|"reads knowledge"| node_knowledge
node_context -->|"reads memory"| node_github
node_context -->|"reads local data"| node_browser_store
node_composer -->|"builds messages"| node_groq_adapter
node_groq_adapter -->|"sends prompt"| node_groq_service
node_groq_service -->|"returns response"| node_groq_adapter
node_groq_adapter -->|"returns response"| node_brain
node_brain -->|"returns result"| node_app
node_app -->|"renders reply"| node_chat_ui
node_app -->|"manages records"| node_crm
node_app -->|"archives outputs"| node_library
node_app -->|"manages widgets"| node_widgets
node_app -->|"secures workspace"| node_vault
node_vault -.->|"requests PRF"| node_webauthn
node_app -->|"opens settings"| node_skill_manager
node_skill_manager -->|"configures skills"| node_registry
node_loader -->|"registers skills"| node_registry
node_prompt_skills -->|"registers uploaded skill"| node_registry
node_skill_manager -->|"manages files"| node_knowledge
node_knowledge -->|"parses uploads"| node_parser
node_knowledge -->|"stores extracted text"| node_browser_store
node_context -->|"reads GitHub file"| node_github
node_github -.->|"syncs memory"| node_browser_store
node_app -->|"emits workspace events"| node_event_bus
node_event_rules -->|"subscribes rules"| node_event_bus
node_scheduler -->|"dispatches scheduled events"| node_event_bus
node_app -->|"checks follow-ups"| node_proactive
node_app -.->|"opens design links"| node_canva
node_app -.->|"creates contact links"| node_whatsapp
node_app -.->|"calls integration"| node_n8n

click node_app "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/app.js"
click node_chat_ui "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/index.html"
click node_crm "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/app.js"
click node_library "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/libraryEngine.js"
click node_widgets "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/widgetEngine.js"
click node_brain "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/brain.js"
click node_intent "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/intentDetector.js"
click node_composer "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/promptComposer.js"
click node_skill_orch "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/skillOrchestrator.js"
click node_groq_adapter "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/integrations/groq.js"
click node_registry "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/skills/skillRegistry.js"
click node_loader "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/skills/skillLoader.js"
click node_skill_manager "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/skills/skillManager.js"
click node_prompt_skills "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/skills/promptSkillEngine.js"
click node_parser "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/knowledge/fileParser.js"
click node_knowledge "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/knowledge/knowledgeManager.js"
click node_context "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/memory/contextBuilder.js"
click node_browser_store "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/memory/contextBuilder.js"
click node_vault "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/core/vault.js"
click node_webauthn "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/core/webauthn.js"
click node_event_bus "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/eventBus.js"
click node_event_rules "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/automation/eventRules.js"
click node_scheduler "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/automation/scheduler.js"
click node_proactive "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/proactiveEngine.js"
click node_github "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/integrations/github.js"
click node_canva "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/integrations/canva.js"
click node_whatsapp "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/integrations/whatsapp.js"
click node_n8n "https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/integrations/n8n.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_app,node_chat_ui,node_crm,node_library,node_widgets,node_user toneBlue
class node_brain,node_intent,node_composer,node_skill_orch,node_groq_adapter toneAmber
class node_registry,node_loader,node_skill_manager,node_prompt_skills,node_parser,node_knowledge,node_groq_service toneMint
class node_context,node_browser_store,node_vault,node_webauthn toneRose
class node_event_bus,node_event_rules,node_scheduler,node_proactive,node_github,node_canva,node_whatsapp,node_n8n toneIndigo
```

## Components

### Business Workspace

- [App Workspace](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/app.js): `app.js`
- [Chat Interface](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/index.html): `index.html`
- [Leads And Clients](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/app.js): `app.js`
- [Output Library](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/libraryEngine.js): `brain/libraryEngine.js`
- [Chat Widgets](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/widgetEngine.js): `brain/widgetEngine.js`

### AI Conversation

- [Brain API](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/brain.js): `brain/brain.js`
- [Intent Detection](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/intentDetector.js): `brain/intentDetector.js`
- [Prompt Composer](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/promptComposer.js): `brain/promptComposer.js`
- [Skill Orchestrator](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/skillOrchestrator.js): `brain/skillOrchestrator.js`
- [Groq Adapter](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/integrations/groq.js): `integrations/groq.js`

### Skills And Knowledge

- [Skill Registry](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/skills/skillRegistry.js): `skills/skillRegistry.js`
- [Skill Loader](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/skills/skillLoader.js): `skills/skillLoader.js`
- [Skill Manager](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/skills/skillManager.js): `skills/skillManager.js`
- [Uploaded Prompt Skills](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/skills/promptSkillEngine.js): `skills/promptSkillEngine.js`
- [File Parser](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/knowledge/fileParser.js): `knowledge/fileParser.js`
- [Knowledge Manager](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/knowledge/knowledgeManager.js): `knowledge/knowledgeManager.js`

### Memory And Security

- [Context Builder](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/memory/contextBuilder.js): `memory/contextBuilder.js`
- [Browser Storage](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/memory/contextBuilder.js): `memory/contextBuilder.js`
- [Encrypted Vault](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/core/vault.js): `core/vault.js`
- [Biometric Helper](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/core/webauthn.js): `core/webauthn.js`

### Automation And Integrations

- [Event Bus](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/eventBus.js): `brain/eventBus.js`
- [Event Rules](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/automation/eventRules.js): `automation/eventRules.js`
- [Scheduler](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/automation/scheduler.js): `automation/scheduler.js`
- [Proactive Engine](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/brain/proactiveEngine.js): `brain/proactiveEngine.js`
- [GitHub Memory](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/integrations/github.js): `integrations/github.js`
- [Canva Links](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/integrations/canva.js): `integrations/canva.js`
- [WhatsApp Links](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/integrations/whatsapp.js): `integrations/whatsapp.js`
- [n8n Integration](https://github.com/whitewolf251501-dot/aa-os-yuvi/blob/main/integrations/n8n.js): `integrations/n8n.js`

### Other components

- **Business User**
- **Groq API**

## Connections

- Business User → Chat Interface: sends message
- Chat Interface → App Workspace: forwards input
- App Workspace → Brain API: calls chat
- Brain API → Intent Detection: detects intent
- Intent Detection → Skill Orchestrator: routes match
- Skill Orchestrator → Skill Registry: executes skill
- Brain API → Prompt Composer: composes fallback
- Prompt Composer → Context Builder: requests context
- Context Builder → Knowledge Manager: reads knowledge
- Context Builder → GitHub Memory: reads memory
- Context Builder → Browser Storage: reads local data
- Prompt Composer → Groq Adapter: builds messages
- Groq Adapter → Groq API: sends prompt
- Groq API → Groq Adapter: returns response
- Groq Adapter → Brain API: returns response
- Brain API → App Workspace: returns result
- App Workspace → Chat Interface: renders reply
- App Workspace → Leads And Clients: manages records
- App Workspace → Output Library: archives outputs
- App Workspace → Chat Widgets: manages widgets
- App Workspace → Encrypted Vault: secures workspace
- Encrypted Vault → Biometric Helper: requests PRF
- App Workspace → Skill Manager: opens settings
- Skill Manager → Skill Registry: configures skills
- Skill Loader → Skill Registry: registers skills
- Uploaded Prompt Skills → Skill Registry: registers uploaded skill
- Skill Manager → Knowledge Manager: manages files
- Knowledge Manager → File Parser: parses uploads
- Knowledge Manager → Browser Storage: stores extracted text
- Context Builder → GitHub Memory: reads GitHub file
- GitHub Memory → Browser Storage: syncs memory
- App Workspace → Event Bus: emits workspace events
- Event Rules → Event Bus: subscribes rules
- Scheduler → Event Bus: dispatches scheduled events
- App Workspace → Proactive Engine: checks follow-ups
- App Workspace → Canva Links: opens design links
- App Workspace → WhatsApp Links: creates contact links
- App Workspace → n8n Integration: calls integration