# uselexora/lexora architecture

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

- Interactive diagram: https://gitdiagram.com/uselexora/lexora
- Repository: https://github.com/uselexora/lexora

## Overview

Lexora is a local-first desktop AI agent: people create tasks, converse with an agent, authorize local access, and review work products. The documented product spans a Vue/Electron desktop, API, and independent TypeScript agent runtime; the sampled runtime entry point wires chat, memory, skills, model, search, Redis, and checkpoint dependencies. The README also documents automations, MCP, sandboxed tools, and native Rust capabilities. Several links for those unsampled features are therefore documented relationships, not inspected call paths.

Main entry points: [`apps/agent/src/main.ts`](https://github.com/uselexora/lexora/blob/master/apps/agent/src/main.ts) (Agent service), [`apps/buddy/electron/main/app/DesktopApplication.ts`](https://github.com/uselexora/lexora/blob/master/apps/buddy/electron/main/app/DesktopApplication.ts) (Electron desktop), [`apps/api/src/modules/chat/chat-sessions.service.ts`](https://github.com/uselexora/lexora/blob/master/apps/api/src/modules/chat/chat-sessions.service.ts) (Chat sessions), [`apps/agent/src/core/runner.ts`](https://github.com/uselexora/lexora/blob/master/apps/agent/src/core/runner.ts) (Agent runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_desktop["Electron desktop"]
  node_taskindex["Task index"]
  node_webchat["Web chat engine"]
  node_skillsui["Skills manager"]
  node_automation["Automations<br/>[automations.ts]"]
end

subgraph group_services["API services"]
  node_api["API application<br/>[app.module.ts]"]
  node_chatsessions["Chat sessions"]
  node_profiles["Agent profiles"]
  node_apiskills["Skill services"]
  node_auth["Authentication<br/>[auth.service.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_agententry["Agent service<br/>[main.ts]"]
  node_runner["Agent runner<br/>[runner.ts]"]
  node_agentconfig["Runtime config<br/>[runtime-config.ts]"]
  node_model["Model provider<br/>[chat-model.ts]"]
  node_websearch["Web search<br/>[index.ts]"]
end

subgraph group_execution["Local execution"]
  node_permissions["Permission engine"]
  node_browser["Browser integration"]
  node_mcp["MCP tools<br/>[provider.ts]"]
end

subgraph group_platform["State and integrations"]
  node_storage["Object storage<br/>[storage.service.ts]"]
  node_database[("API database<br/>[prisma.service.ts]")]
  node_redisstreams["Runtime streams<br/>[redis-streams.ts]"]
  node_redislock["Runtime locks<br/>[redis-lock.ts]"]
  node_checkpointer[("Checkpoint store<br/>[checkpointer.ts]")]
end

node_user(("User"))

node_user -->|"starts tasks"| node_desktop
node_desktop -->|"manages tasks"| node_taskindex
node_desktop -.->|"offers chat"| node_webchat
node_webchat -.->|"persists sessions"| node_chatsessions
node_chatsessions -->|"resolves profile"| node_profiles
node_chatsessions -->|"reads and writes"| node_database
node_api -.->|"routes chat"| node_chatsessions
node_api -.->|"routes authentication"| node_auth
node_auth -->|"uses Prisma"| node_database
node_agententry -->|"loads config"| node_agentconfig
node_agententry -->|"creates runner"| node_runner
node_agententry -->|"creates model factory"| node_model
node_agententry -->|"wires streams"| node_redisstreams
node_agententry -->|"creates locks"| node_redislock
node_agententry -->|"creates checkpointer"| node_checkpointer
node_agententry -->|"creates search client"| node_websearch
node_agententry -.->|"uses chat API"| node_chatsessions
node_skillsui -.->|"manages skills"| node_apiskills
node_desktop -->|"authorizes local tools"| node_permissions
node_desktop -.->|"provides browser tools"| node_browser
node_desktop -->|"schedules tasks"| node_automation
node_runner -.->|"requests authorized execution"| node_permissions
node_runner -.->|"uses extensible tools"| node_mcp
node_chatsessions -.->|"serves chat assets"| node_storage
node_user -.->|"signs in"| node_auth

click node_desktop "https://github.com/uselexora/lexora/blob/master/apps/buddy/electron/main/app/DesktopApplication.ts"
click node_taskindex "https://github.com/uselexora/lexora/blob/master/apps/buddy/src/modules/tasks/widgets/task-index/useTaskIndexController.ts"
click node_webchat "https://github.com/uselexora/lexora/blob/master/apps/web/src/composables/chat/createChatEngine.ts"
click node_skillsui "https://github.com/uselexora/lexora/blob/master/apps/buddy/src/modules/skills/state/useSkillsManager.ts"
click node_api "https://github.com/uselexora/lexora/blob/master/apps/api/src/app.module.ts"
click node_chatsessions "https://github.com/uselexora/lexora/blob/master/apps/api/src/modules/chat/chat-sessions.service.ts"
click node_profiles "https://github.com/uselexora/lexora/blob/master/apps/api/src/modules/agent/agent-profiles.service.ts"
click node_apiskills "https://github.com/uselexora/lexora/blob/master/apps/api/src/modules/agent/agent-skills.service.ts"
click node_auth "https://github.com/uselexora/lexora/blob/master/apps/api/src/modules/auth/auth.service.ts"
click node_storage "https://github.com/uselexora/lexora/blob/master/apps/api/src/infrastructure/storage/storage.service.ts"
click node_database "https://github.com/uselexora/lexora/blob/master/apps/api/src/database/prisma.service.ts"
click node_agententry "https://github.com/uselexora/lexora/blob/master/apps/agent/src/main.ts"
click node_runner "https://github.com/uselexora/lexora/blob/master/apps/agent/src/core/runner.ts"
click node_agentconfig "https://github.com/uselexora/lexora/blob/master/apps/agent/src/config/runtime-config.ts"
click node_model "https://github.com/uselexora/lexora/blob/master/apps/agent/src/integrations/model-providers/chat-model.ts"
click node_redisstreams "https://github.com/uselexora/lexora/blob/master/apps/agent/src/integrations/redis-streams.ts"
click node_redislock "https://github.com/uselexora/lexora/blob/master/apps/agent/src/integrations/redis-lock.ts"
click node_checkpointer "https://github.com/uselexora/lexora/blob/master/apps/agent/src/runtime/checkpointer.ts"
click node_permissions "https://github.com/uselexora/lexora/blob/master/apps/buddy/service/src/permissions/PermissionEngine.ts"
click node_browser "https://github.com/uselexora/lexora/blob/master/apps/buddy/electron/main/browser/BrowserIntegration.ts"
click node_automation "https://github.com/uselexora/lexora/blob/master/apps/buddy/electron/main/local-chat/automations.ts"
click node_websearch "https://github.com/uselexora/lexora/blob/master/apps/agent/src/integrations/web-search/index.ts"
click node_mcp "https://github.com/uselexora/lexora/blob/master/apps/agent/src/core/skills/action-providers/mcp/provider.ts"

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_desktop,node_taskindex,node_webchat,node_skillsui,node_automation,node_user toneBlue
class node_api,node_chatsessions,node_profiles,node_apiskills,node_auth toneAmber
class node_agententry,node_runner,node_agentconfig,node_model,node_websearch toneMint
class node_permissions,node_browser,node_mcp toneRose
class node_storage,node_database,node_redisstreams,node_redislock,node_checkpointer toneIndigo
```

## Components

### Desktop experience

- [Electron desktop](https://github.com/uselexora/lexora/blob/master/apps/buddy/electron/main/app/DesktopApplication.ts): `apps/buddy/electron/main/app/DesktopApplication.ts`
- [Task index](https://github.com/uselexora/lexora/blob/master/apps/buddy/src/modules/tasks/widgets/task-index/useTaskIndexController.ts): `apps/buddy/src/modules/tasks/widgets/task-index/useTaskIndexController.ts`
- [Web chat engine](https://github.com/uselexora/lexora/blob/master/apps/web/src/composables/chat/createChatEngine.ts): `apps/web/src/composables/chat/createChatEngine.ts`
- [Skills manager](https://github.com/uselexora/lexora/blob/master/apps/buddy/src/modules/skills/state/useSkillsManager.ts): `apps/buddy/src/modules/skills/state/useSkillsManager.ts`
- [Automations](https://github.com/uselexora/lexora/blob/master/apps/buddy/electron/main/local-chat/automations.ts): `apps/buddy/electron/main/local-chat/automations.ts`

### API services

- [API application](https://github.com/uselexora/lexora/blob/master/apps/api/src/app.module.ts): `apps/api/src/app.module.ts`
- [Chat sessions](https://github.com/uselexora/lexora/blob/master/apps/api/src/modules/chat/chat-sessions.service.ts): `apps/api/src/modules/chat/chat-sessions.service.ts`
- [Agent profiles](https://github.com/uselexora/lexora/blob/master/apps/api/src/modules/agent/agent-profiles.service.ts): `apps/api/src/modules/agent/agent-profiles.service.ts`
- [Skill services](https://github.com/uselexora/lexora/blob/master/apps/api/src/modules/agent/agent-skills.service.ts): `apps/api/src/modules/agent/agent-skills.service.ts`
- [Authentication](https://github.com/uselexora/lexora/blob/master/apps/api/src/modules/auth/auth.service.ts): `apps/api/src/modules/auth/auth.service.ts`

### Agent runtime

- [Agent service](https://github.com/uselexora/lexora/blob/master/apps/agent/src/main.ts): `apps/agent/src/main.ts`
- [Agent runner](https://github.com/uselexora/lexora/blob/master/apps/agent/src/core/runner.ts): `apps/agent/src/core/runner.ts`
- [Runtime config](https://github.com/uselexora/lexora/blob/master/apps/agent/src/config/runtime-config.ts): `apps/agent/src/config/runtime-config.ts`
- [Model provider](https://github.com/uselexora/lexora/blob/master/apps/agent/src/integrations/model-providers/chat-model.ts): `apps/agent/src/integrations/model-providers/chat-model.ts`
- [Web search](https://github.com/uselexora/lexora/blob/master/apps/agent/src/integrations/web-search/index.ts): `apps/agent/src/integrations/web-search/index.ts`

### Local execution

- [Permission engine](https://github.com/uselexora/lexora/blob/master/apps/buddy/service/src/permissions/PermissionEngine.ts): `apps/buddy/service/src/permissions/PermissionEngine.ts`
- [Browser integration](https://github.com/uselexora/lexora/blob/master/apps/buddy/electron/main/browser/BrowserIntegration.ts): `apps/buddy/electron/main/browser/BrowserIntegration.ts`
- [MCP tools](https://github.com/uselexora/lexora/blob/master/apps/agent/src/core/skills/action-providers/mcp/provider.ts): `apps/agent/src/core/skills/action-providers/mcp/provider.ts`

### State and integrations

- [Object storage](https://github.com/uselexora/lexora/blob/master/apps/api/src/infrastructure/storage/storage.service.ts): `apps/api/src/infrastructure/storage/storage.service.ts`
- [API database](https://github.com/uselexora/lexora/blob/master/apps/api/src/database/prisma.service.ts): `apps/api/src/database/prisma.service.ts`
- [Runtime streams](https://github.com/uselexora/lexora/blob/master/apps/agent/src/integrations/redis-streams.ts): `apps/agent/src/integrations/redis-streams.ts`
- [Runtime locks](https://github.com/uselexora/lexora/blob/master/apps/agent/src/integrations/redis-lock.ts): `apps/agent/src/integrations/redis-lock.ts`
- [Checkpoint store](https://github.com/uselexora/lexora/blob/master/apps/agent/src/runtime/checkpointer.ts): `apps/agent/src/runtime/checkpointer.ts`

### Other components

- **User**

## Connections

- User → Electron desktop: starts tasks (evidence: `README.md`)
- Electron desktop → Task index: manages tasks (evidence: `README.md`)
- Electron desktop → Web chat engine: offers chat
- Web chat engine → Chat sessions: persists sessions
- Chat sessions → Agent profiles: resolves profile (evidence: `apps/api/src/modules/chat/chat-sessions.service.ts`)
- Chat sessions → API database: reads and writes (evidence: `apps/api/src/modules/chat/chat-sessions.service.ts`)
- API application → Chat sessions: routes chat
- API application → Authentication: routes authentication
- Authentication → API database: uses Prisma (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Agent service → Runtime config: loads config (evidence: `apps/agent/src/main.ts`)
- Agent service → Agent runner: creates runner (evidence: `apps/agent/src/main.ts`)
- Agent service → Model provider: creates model factory (evidence: `apps/agent/src/main.ts`)
- Agent service → Runtime streams: wires streams (evidence: `apps/agent/src/main.ts`)
- Agent service → Runtime locks: creates locks (evidence: `apps/agent/src/main.ts`)
- Agent service → Checkpoint store: creates checkpointer (evidence: `apps/agent/src/main.ts`)
- Agent service → Web search: creates search client (evidence: `apps/agent/src/main.ts`)
- Agent service → Chat sessions: uses chat API
- Skills manager → Skill services: manages skills
- Electron desktop → Permission engine: authorizes local tools (evidence: `README.md`)
- Electron desktop → Browser integration: provides browser tools (evidence: `README.md`)
- Electron desktop → Automations: schedules tasks (evidence: `README.md`)
- Agent runner → Permission engine: requests authorized execution (evidence: `README.md`)
- Agent runner → MCP tools: uses extensible tools (evidence: `README.md`)
- Chat sessions → Object storage: serves chat assets
- User → Authentication: signs in
