Platform

Architecture & Code

The platform & agent system

Service boundary and responsibilities, interaction modes, and the cross-cutting concerns — deployment, security, the code map, and design rules.

apps/webapps/apipackages/agent

The platform shape and the agent system. Use the Full screen button above, or open the platform diagram in a new tab ↗.

System Boundary

LifeOSAI is a cross-platform agent operating system. The same product model runs in two deployment modes:

• Cloud mode: browser traffic is served by cloud services, and agent runtimes run in cloud infrastructure.
• Local mode: the Tauri desktop app starts local sidecars and uses local files and local data stores.

The high-level service boundary is:

User / channel / operator

apps/web or external channel transport

apps/user-management

apps/api

packages/agent runtime adapter

Claude Code agent or Pi agent

apps/user-management is the browser-facing routing hub. It validates the user session and forwards product requests to the correct backend service. Agent execution is owned by apps/api, especially the orchestration engine and runtime invoker.

Service Responsibilities

Layer	Owner	Responsibility
Product entry	apps/web	LifeOSAI chat, companies, apps, files, settings, and static-export compatible shell
Desktop shell	apps/tauri	Local desktop wrapper, updater, sidecar process management
Routing hub	apps/user-management	User-authenticated API gateway, session reader, orchestration proxy, file proxy
Agent API	apps/api	Agent runtime APIs, company orchestration, wakeups, schedulers, channels, secrets
Runtime SDK	packages/agent	Runtime abstraction, Claude Code adapter, Pi Agent adapter, normalized streaming events
Shared contracts	packages/shared	Orchestration types, live event constants, env normalization, validators
Persistent data	Prisma DB	Companies, agents, issues, runs, routines, activity, secrets, channel state
Workspace data	Filesystem or mounted volume	Chat workspaces, company project files, artifacts, skills, logs

LifeOSAI Agent System

The agent system covers normal chat, direct company-agent chat, and live run transcripts. It is intentionally separate from company task orchestration, although both paths can use the same runtime adapters.

Agent Interaction Modes

Mode	Description	Primary state
LifeOSAI chat	User chats with the selected runtime outside a company task	Chat session id, runtime, model
Direct company-agent chat	User talks directly to a company agent	Company id, agent id, remembered session id
Live run transcript	UI follows an active orchestration run	Run id, session id, runtime log stream
Completed transcript replay	UI reads a previous run/session	Stored session messages
Channel conversation	WhatsApp, Telegram, or another transport talks to an agent	Channel session key, channel metadata, runtime session id

The frontend may present these modes differently, but the backend contract is the same idea: a session is attached to a runtime, the runtime streams events, and those events become transcript records or live run events.

Agent Capabilities

LifeOSAI agents can be extended by:

• Skills: bundled, company-scoped, or user-uploaded capability folders.
• Plugins: installed runtime extensions and tool bundles.
• Connectors: external account or service integrations.
• MCP servers: tool servers such as channels, browser, Slack, or custom tools.
• Files: allowed workspace roots and company/project file roots.
• Channels: transport-specific inbound messages and outbound replies.

The runtime process receives these capabilities through a combination of:

• Runtime options passed by apps/api.
• Environment variables assembled before invocation.
• MCP server definitions.
• Additional skill directories.
• Adapter-specific command or SDK options.

Chat Session Flow

User sends message

apps/web

apps/user-management session/chat route

apps/api or runtime handler

packages/agent runtime

Claude Code or Pi Agent

normalized stream events

persisted transcript and/or live response

Session discovery and session message lookup are separate concerns. Listing sessions should stay limited to the known LifeOSAI root. Message lookup can resolve known company-agent transcript paths when a run/session already points there.

Local And Cloud Deployment

Local Mode

Local mode is built around the Tauri app and sidecar services:

Port	Service
3000	apps/web
3001	apps/user-management
3002	apps/auth
4000	apps/api

Important local roots:

• ~/LIFEOSAI
• ~/.lifeosai/companies
• local database, usually SQLite or local Postgres depending on mode

Cloud Mode

Cloud mode uses GCP and CI/CD:

• GCP project: lifeosai-481608
• region: asia-south-1
• Artifact Registry repo: docker-images
• Cloud Run services: web, auth, user-management
• Compute Engine or runtime containers for agent execution
• workspace root: /workspace/LIFEOSAI

The product API surface should remain the same between local and cloud. Only the execution locality, filesystem root, and infrastructure backing services change.

Security Boundaries

Boundary	Enforcement
User session	apps/user-management validates browser/desktop requests
Company access	Orchestration services assert company access before reads/writes
Agent run APIs	Run-scoped bearer token validates company, agent, and run
Secrets	Company-scoped secret refs validated on write and resolved at invocation
Files	Session and file readers allow only known LifeOSAI roots
Logs	Secret-backed env values are redacted before persistence
Channels	Transport plugins and channel sessions map inbound messages to known company/agent context

Code Map

Area	Main files
Runtime interface	packages/agent/src/runtimes/types.ts
Claude Code runtime	packages/agent/src/runtimes/claude-code-runtime.ts
Pi Agent runtime	packages/agent/src/runtimes/pi-agent-runtime.ts
Runtime event normalization	packages/agent/src/runtimes/event-normalizer.ts
Agent invoker	apps/api/src/orchestration/engine/agent-invoker.ts
Wakeup queue	apps/api/src/orchestration/engine/wakeup.ts
Heartbeat scheduler	apps/api/src/orchestration/engine/heartbeat.ts
Routine scheduler	apps/api/src/orchestration/engine/routine-scheduler.ts
Event bus	apps/api/src/orchestration/engine/event-bus.ts
Run auth	apps/api/src/orchestration/auth/run-token.ts
Agent API guard	apps/api/src/orchestration/routes/middleware.ts
Issues	apps/api/src/orchestration/services/issues.ts
Agents	apps/api/src/orchestration/services/agents.ts
Projects	apps/api/src/orchestration/services/projects.ts
Routines	apps/api/src/orchestration/services/routines.ts
Activity	apps/api/src/orchestration/services/activity-log.ts
Secrets	apps/api/src/orchestration/services/secrets.ts
Env config	packages/shared/src/orchestration/env-config.ts
Live event types	packages/shared/src/orchestration/types/live.ts
Channels dispatch	apps/api/src/channels/dispatch.ts
Channels message tool	apps/api/src/channels/message-tool.ts
WhatsApp channel	apps/api/src/channels/plugins/whatsapp.ts
Telegram channel	apps/api/src/channels/plugins/telegram.ts
Session reader	apps/user-management/src/sessions/reader.ts

Design rules

• Keep run lifecycle and agent lifecycle separate.
• Keep adapter_config and runtime_config separate.
• Keep user auth and run auth separate.
• Prefer event payloads that are complete enough for subscribers to update without broad refetches.
• Resolve secrets only inside the runtime invocation boundary.
• Redact secret values before logs are persisted.
• Treat channel sending as a tool call, not as prompt-only behavior.
• Keep local and cloud request contracts aligned even when storage roots differ.

Read next

Agent Systems The full system below the UI in one doc.

Orchestration Companies, agents, wakeups, runs and live events.

Channels WhatsApp and Telegram ingress, dispatch, and the outbound tool.

Agent Runtime The harness — runtime interface, invoker, env layers, run-scoped auth.

Architecture overview Back to the section map and the full system diagram.