LifeOSAI architecture

Cloud, Local, Agent Runtime, Company Orchestration, And Channels

A poster-style architecture map for the full LifeOSAI system. It shows the same system from the whole-platform view down into company orchestration, chat, channel routing, runtime adapters, deployment, and security boundaries.

Not UI components This document focuses on platform architecture, service boundaries, runtime flow, and data movement.
Two deployment modes Cloud on GCP plus local Tauri 2 sidecars using the same core services and adapters.
Agent systems Claude Code runtime and Pi Agent runtime share orchestration, run auth, events, tools, and transcripts.
01 / full architecture

Full System Architecture

The top row shows clients and external systems. The main boundary contains the cloud services, product domains, orchestration tier, runtime execution tier, data tier, and operational side tiers. Local desktop runs the same conceptual stack with sidecars and local workspaces.

Control Runtime Data Ops
Desktop users Tauri app, local workspace, sidecar services
Web users Browser app for chat, companies, apps
Channel users WhatsApp, Telegram, and connected chat surfaces
GitHub Actions Build, scan, push, promote, release
Model providers Claude, OpenAI-compatible, Gemini, local models
Operators Secrets, env, releases, observability, support
LOS LifeOSAI platform boundary
GCP cloud region project lifeosai-481608 / asia-south-1
LifeOSAI service network public control plane plus private runtime/data planes
Public control tier
apps/web Next.js LifeOSAI frontend, static export compatible
apps/user-management All web requests route through this service
apps/auth User auth, tokens, auth callbacks
Apps surface ERP, microapps, embedded operational apps
Product systems
LifeOSAI Chat Sessions, direct agent chat, live run transcript
Companies Agents, issues, routines, goals, files
Apps ERP and microapp runtime surfaces
Private orchestration tier
apps/api Agent API and orchestration service
Wakeup queue Assignment, comment, routine, heartbeat, channel wakeups
Schedulers Heartbeat service and routine scheduler
Event bus Company SSE, live run events, activity events
Agent invoker Runtime selection, env build, run token minting
Run API guard Bearer run token validates company, agent, run
Execution tier
Cloud VM containers Runtime containers, workspace mount, tool execution
Adapter runtimes Claude Code runtime and Pi Agent runtime
Channel and integration tier
Channel dispatch Inbound messages mapped to company agent wakes
Message tool mcp__channels__message sends replies
Connectors External account and service integrations
Skills/plugins Default, company, and uploaded capabilities
Primary data tier
Postgres Companies, agents, issues, runs, routines
Workspace storage Company files, projects, generated artifacts
Transcripts Claude/Pi session history and run replay
Company secrets secret_ref values and env redaction keys
Local-compatible state
Tauri sidecars Local service processes
SQLite/Postgres Local app state
~/LIFEOSAI Local chat and project workspace
~/.lifeosai/companies Company agent transcript paths

OPS Delivery tier

CI pipelines Typecheck, lint, build, scan
Image registry docker-images repository
Cloud services web, auth, usermanagement
Desktop release Tauri updater assets

SEC Security tier

User auth Browser and desktop session
Run JWT Per-run agent bearer token
Company guard Company-scoped access checks
Path allowlist Transcript and file boundaries

OBS Observability tier

Run logs SDK events and excerpts
SSE stream Company live events
Activity log Issue and run audit trail
Health checks Service and DB backoff

AI Model and tool tier

Model APIs Provider-specific calls
Browser tools Chrome and web tooling
MCP servers Channels, integrations, custom tools
Skill runtime Bundled and company skills
02 / company orchestration

Company Orchestration Deep Dive

Company orchestration converts company events into agent runs. The queue, scheduler, invoker, runtime, and event bus are shared by tasks, routines, channel messages, direct chat, and heartbeat timers.

Agent lifecycle Run lifecycle
trigger Company event Issue created, assigned, commented, approved, routine timer, heartbeat timer, channel inbound.
queue enqueueWakeup Creates run row, stores context snapshot, marks run queued.
claim Scheduler Heartbeat and routine schedulers claim eligible runs and start execution.
invoke Agent invoker Builds env, resolves adapter config, mints run bearer token.
execute Runtime adapter Claude Code or Pi Agent streams SDK events and tool events.
publish Event bus Sends company SSE events, activity logs, run logs, status updates.
Run events heartbeat.run.queued, running, log, event, completed, failed, cancelled
Agent status agent.status only when real agent status changes
Issue events issue.created, issue.updated, issue.comment.created, issue.deleted
Activity events activity.logged for audit and company timeline
Live chat panel AgentChatContext consumes selected direct agent or selected live run
03 / chat system

LifeOSAI Chat Architecture

Chat is shared by normal LifeOSAI chat, direct company-agent chat, live run viewing, completed transcript replay, and file/skill/plugin context surfaces.

Chat surfaces
Normal chatLifeOSAI chat home and sessions.
Direct agent chatCompany agent selected from chat header.
Live run transcriptRun logs streamed into chat panel.
Completed replaySession messages loaded by runtime and session id.
Context surfaces
FilesExplorer and preview, including relative HTML assets.
SpotlightSearch and quick workspace context.
SkillsDefault, company, uploaded, install/update flows.
Connectors and pluginsExternal capability and tool packages.
Session and transcript retrieval
Session listingScoped to top-level LifeOSAI chat workspaces.
Messages endpointCan load project and company-agent transcript paths.
Runtime readerClaude Code or Pi reader selected by runtime query.
Path validationAllows known LifeOSAI and company transcript roots only.
04 / channels

Channels Architecture

Channel ingress maps outside conversations into company agent wakes. Agents reply through a dedicated channel message tool so outbound messages are traceable.

inboundChannel messageExternal message enters WhatsApp, Telegram, or connector adapter.
identitySession mappingCompany, user, room, and target agent are resolved.
contextConversation bundleRecent message history and wake reason are prepared.
wakeupDispatch to agentStandard company wakeup creates queued run.
respondMessage toolAgent calls mcp__channels__message for replies.
auditActivity and deliveryDelivery status and activity are persisted.
05 / runtime adapters

Runtime Adapter And Tool Plane

Adapter configuration is for process-spawn inputs. Runtime configuration is for scheduler policy. Environment variables can exist at agent level and project level; project values override agent values when both define the same key.

Claude Code runtime
Streaming SDKRaw SDK events become run.log events.
Skills and toolsBash, files, edit, browser, MCP, channel tool.
Session transcriptSession id can appear after runtime starts.
RedactionSecret-backed values are removed from logs.
Pi Agent runtime
OpenAI-compatible streamRuntime-specific event conversion.
Shared toolsUses common tool surfaces where supported.
Transcript readerSelected by runtime parameter.
Run tokenSame protected agent API boundary.
Configuration split
adapter_configenv, cwd, command, args, model, instruction discovery.
runtime_configheartbeat, interval, max concurrent runs, compaction policy.
secret_refValidated in the company before write and resolved before run.
Env precedenceAgent env first, project env overrides on collision.
06 / deployment

Cloud And Local Deployment

Cloud mode hosts user-facing services and starts runtime containers on cloud infrastructure. Local mode uses the Tauri desktop shell and sidecars to run the same service responsibilities on the user machine.

Cloud deployment
GitHub ActionsBuild, scan, push, promote, desktop release.
Artifact Registrydocker-images for deployable services.
Cloud servicesweb-production, auth, usermanagement.
Agent runtime VMsAgent API containers and runtime processes.
Local desktop deployment
Tauri appDesktop window, updater, sidecar manager.
Local services3000 web, 3001 user-management, 3002 auth, 4000 agent API.
Local databaseSQLite or local Postgres depending on mode.
Local files~/LIFEOSAI and ~/.lifeosai/companies.
07 / security and data

Security, Data, Secrets, And Observability

The browser is authenticated by user session. Agent requests are authenticated by run-scoped bearer token. Secrets are company scoped and redacted before runtime logs are persisted.

User boundaryUser-management validates user session before routing UI requests.
Run boundaryAgent APIs require Authorization bearer run token.
Company boundaryCompany access checks prevent cross-company data writes.
Path boundarySession and file readers allow only known LifeOSAI roots.
Database stateCompanies, users, agents, projects, issues, routines, runs.
File stateCompany workspaces, project files, generated artifacts, exports.
ObservabilitySSE events, activity logs, run logs, health checks.
Event contractTyped live events shared between backend and frontend.
08 / execution sequences

Operational Sequences

These are the main cross-service paths LifeOSAI uses at runtime. They are shown as service-to-service flows rather than UI flows.

Issue assignment
Issue created or assigned to company agent. Activity event logged and wakeup enqueued. Run row queued with issue context snapshot. Scheduler starts runtime and marks run running. Agent uses protected run API to update issue/comment/files. Run completes and company SSE updates live UI.
Direct agent chat
User selects company agent in chat header. AgentChatContext stores direct agent selection. Chat session resolves agent runtime and model. User message starts direct runtime session. Transcript persists under runtime-specific store. Session can be reopened by session id.
Routine timer
Routine trigger stores cron and timezone. Routine scheduler computes nextFireAt. Wakeup source is routine timer. Agent receives routine instructions and run context. Agent performs task or exits if no work. Routine run, next run, and activity are persisted.
Channel inbound
Message arrives from external channel. Channel session maps sender/company/agent. Dispatch enqueues wakeup with conversation context. Runtime receives channel history and task context. Agent replies with channel message tool. Delivery result and audit activity are persisted.
Env resolution
Agent env config normalized and resolved. Project env config normalized and resolved. Project env overrides duplicate agent keys. secret_ref values resolved inside company boundary. Run token and LifeOSAI runtime vars injected. Secret keys passed to log redaction.