Developers
Architecture
Deep dive into Talome's system architecture -- monorepo structure, data flow, database design, and runtime components.
Talome is built as a TypeScript monorepo with three applications and a shared types package. This page provides a comprehensive technical overview of how the system is structured and how data flows through it.
Monorepo Layout
talome/
apps/
core/ Hono backend: AI agent, tools, Docker API, DB, MCP server
dashboard/ Next.js 16 frontend: dashboard, chat UI, app store
web/ Fumadocs site: documentation and marketing
packages/
types/ Shared TypeScript types (UserPermissions, etc.)
.claude/ Claude Code skills and auto-memory
docs/ Internal architecture documentationapps/core -- The Backend
The backend is a Hono server written in TypeScript. It handles API requests, AI chat streaming, Docker container management, database operations, automation scheduling, and MCP protocol serving.
| Path | Purpose |
|---|---|
src/ai/agent.ts | System prompt definition and domain registrations. The central file that wires all tools to the AI. |
src/ai/tool-registry.ts | Dynamic tool loading engine. Manages domains, settings-based activation, keyword routing. |
src/ai/tool-gateway.ts | Security gateway. Enforces tier-based access control per security mode. |
src/ai/tools/ | 37 tool files containing 230+ tool definitions across 16 domains. |
src/ai/custom-tools.ts | Runtime for user-created custom tools. |
src/ai/claude-runner.ts | Headless Claude Code executor for self-improvement and app creation. |
src/routes/ | 47 Hono route files. Each exports a Hono router mounted at /api/*. |
src/db/schema.ts | Drizzle ORM schema defining ~25 SQLite tables. |
src/db/index.ts | Database connection and singleton export. |
src/db/audit.ts | Audit log write helper. |
src/db/memories.ts | Memory ranking and retrieval logic. |
src/docker/client.ts | Dockerode wrapper for container operations. |
src/stores/ | Multi-source app store: Talome native, CasaOS, Umbrel format parsers. |
src/creator/ | App creation orchestrator. Blueprint generation and workspace scaffolding. |
src/middleware/ | Auth middleware, CORS, session management. |
src/automation/ | Cron scheduler (croner) and step executor. |
src/mcp/ | MCP server implementation for Claude Code and other MCP clients. |
apps/dashboard -- The Frontend
The frontend is a Next.js 16 application using the App Router, React 19, Tailwind CSS 4, and shadcn/ui.
| Path | Purpose |
|---|---|
src/app/dashboard/ | 26+ App Router pages (containers, apps, media, files, settings, etc.) |
src/components/ui/ | 40+ shadcn/ui primitives (button, card, dialog, table, etc.) |
src/components/widgets/ | 20+ dashboard widgets (CPU, memory, disk, services, media calendar, etc.) |
src/components/assistant/ | AI chat interface: message bubbles, tool call display, streaming indicator. |
src/components/dashboard/ | Dashboard-level components (app cards, container tables, store views). |
src/components/files/ | File manager and media player components. |
src/components/settings/ | Settings page sections (general, integrations, security, users). |
src/atoms/ | Jotai atoms for global state management (chat state, sidebar, preferences). |
src/hooks/ | Custom React hooks (useContainers, useSettings, useChat, etc.). |
src/lib/ | Utility functions, API client, formatting helpers. |
apps/web -- Documentation Site
A Fumadocs-powered site serving the documentation and marketing pages. Content lives in MDX files under content/docs/.
packages/types -- Shared Types
TypeScript type definitions shared between apps/core and apps/dashboard. Includes UserPermissions, API response types, and shared constants.
Tech Stack
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 16 App Router | Server-side rendering, routing, React Server Components |
| React | React 19 | UI rendering with concurrent features |
| Styling | Tailwind CSS 4 | Utility-first CSS framework |
| UI Primitives | shadcn/ui | 40+ accessible, customizable components |
| Icons | HugeIcons | Icon library (@hugeicons/react, @hugeicons/core-free-icons) |
| State | Jotai | Atomic state management for client state |
| Backend | Hono | Fast, lightweight TypeScript HTTP framework |
| AI SDK | Vercel AI SDK | Streaming chat, tool execution, structured output |
| AI Provider | @ai-sdk/anthropic | Claude integration (primary) |
| Database | SQLite + better-sqlite3 | Embedded database with synchronous reads |
| ORM | Drizzle ORM | Type-safe SQL query builder |
| Docker | Dockerode | Native Node.js Docker Engine API client |
| Scheduling | croner | Cron expression parser and job scheduler |
| Validation | Zod | Runtime type validation everywhere |
| Monorepo | pnpm workspaces + Turborepo | Dependency management and parallel build tasks |
Data Flow
AI Chat
Context injected into each request:
- System prompt (~5,000 tokens, cached via Anthropic prompt caching)
- Top 10 memories (ranked by 0.4 recency + 0.3 access + 0.3 confidence)
- Active domain context and page context
- Security mode (permissive/cautious/locked)
- Max 10 tool calls per turn (
stepCountIs(10))
App Installation
Self-Improvement
Database Schema
Talome uses a single SQLite file managed by Drizzle ORM. The database provides synchronous reads (via better-sqlite3) for performance and simplicity. Key table groups:
Authentication and Users
| Table | Purpose |
|---|---|
users | User accounts with hashed passwords, roles (admin/member), and permissions |
Conversations and AI
| Table | Purpose |
|---|---|
conversations | Chat conversations with optimistic locking version |
messages | Individual messages (user, assistant, system) linked to conversations |
memories | AI memory system: preferences, facts, contexts, corrections with confidence and access count |
ai_usage_log | Token usage tracking per model with cost estimation |
App Management
| Table | Purpose |
|---|---|
store_sources | Configured app store sources (Talome, CasaOS, Umbrel, Git) |
app_catalog | Normalized app metadata from all store sources |
installed_apps | Currently installed apps with status, version, and container IDs |
install_errors | Detailed error logs for failed installations |
Automation
| Table | Purpose |
|---|---|
automations | Automation definitions with trigger, steps, and schedule |
automation_runs | Execution history for each automation |
automation_step_runs | Per-step execution details within a run |
System
| Table | Purpose |
|---|---|
settings | Key-value configuration store |
settings_history | Change history for settings (who changed what, when) |
audit_log | Every tool execution with tier, timestamp, and approval status |
notifications | System notifications (info, warning, critical) |
metrics | Historical system metrics (CPU, memory, disk, network) |
container_events | Container state transitions (for crash detection) |
system_events | System-level events for the agent loop |
remediation_log | Autonomous remediation actions taken by the agent |
Self-Improvement
| Table | Purpose |
|---|---|
evolution_log | Legacy evolution change log |
evolution_runs | Self-improvement run tracking with status, diff output, and rollback info |
evolution_suggestions | AI-generated improvement suggestions with priority and risk |
UI and Configuration
| Table | Purpose |
|---|---|
widget_manifests | Dashboard widget definitions and layout |
proxy_routes | Reverse proxy route configuration with TLS status |
terminal_sessions | Persistent terminal session metadata |
Runtime Components
Security Gateway
The security gateway wraps every tool with access control based on the system-wide security_mode setting:
| Mode | Read Tools | Modify Tools | Destructive Tools |
|---|---|---|---|
permissive | Execute freely | Execute freely | Execute freely |
cautious (default) | Execute freely | Execute freely | Require user confirmation |
locked | Execute freely | Blocked | Blocked |
The gateway also writes to the audit_log for every tool execution, including blocked attempts.
Memory Ranking
The top 10 memories are injected into each chat system prompt, selected by a composite score:
- Recency -- recently created or updated memories score higher
- Access frequency -- memories recalled more often score higher
- Confidence -- corrections (confidence adjustments) affect ranking
- Deduplication -- new memories with >80% bigram similarity to existing ones are rejected
Automation Scheduler
The automation engine uses croner for cron-based scheduling. On startup:
- All enabled automations with
scheduletriggers are registered with croner - Event-based triggers (container_stopped, disk_usage_exceeds) are registered with the event bus
- Webhook triggers generate unique URLs
- When a trigger fires, the step executor runs each step in sequence, passing output forward
MCP Server
The MCP server runs as a stdio process launched by Claude Code at startup. It:
- Calls
getAllRegisteredTools()to get every tool from every domain - Converts Vercel AI SDK tool schemas to MCP-compatible JSON Schema
- Handles tool call requests from Claude Code, executing them through the same tool pipeline
- Operates independently of the Hono web server (reads the same SQLite DB and Docker socket)
Ports
| Service | Port | Configurable Via |
|---|---|---|
| Dashboard | 3000 | DASHBOARD_PORT |
| Backend API | 4000 | CORE_PORT |
| Terminal daemon | 4001 | TERMINAL_DAEMON_PORT |
| Docs site | 3100 | Dev mode only |
Directory Conventions
App Installation
Apps are installed to ~/.talome/apps/<appId>/. Each app directory contains:
~/.talome/apps/jellyfin/
docker-compose.yml Generated from the app manifest
config/ Volume mount (relative paths)
cache/ Volume mount
.env App-specific environment overridesApp Creation
Generated apps use a workspace at ~/.talome/generated-apps/<appId>/:
~/.talome/generated-apps/<appId>/
.talome-creator/
blueprint.json Structured app specification
instructions/ Generation guides
references/ Talome source file snapshots
sources/ Existing app manifests to adapt
generated-app/ Scaffold outputUser Apps
User-created apps are stored at ~/.talome/user-apps/.
Backups
App backups are stored at ~/.talome/backups/<appId>/<timestamp>.tar.gz.