Architecture & Code

Architecture & Code

How the platform is built

Agent systems in full, then a page per area — platform, orchestration, channels, and the agent runtime.

apps/apiruntime adapterlive events

The five sections

Section 01Agent SystemsThe full system below the UI in one doc — agent system, orchestration, channels, and the harness / agent runtime.How requests move →Section 02PlatformService boundary and responsibilities, the agent system, and cross-cutting concerns — deployment, security, code map, design rules.apps/webapps/apiSection 03OrchestrationCompanies, agents, wakeups, runs and live events — and the operational sequences that drive them.queuedrunningdoneSection 04ChannelsWhatsApp and Telegram ingress, dispatch, and the shared outbound message tool.inboundreplySection 05Agent RuntimeThe harness — runtime interface, invoker, adapter vs runtime config, env layers, run-scoped auth.Bearer $RUN_TOKENOn GitHub ↗The monorepoLIFEOSAI lives at github.com/metaweavehq. Read-access for engagement clients; full open-source on request.apps/packages/

Code repository

LIFEOSAI lives at github.com/metaweavehq. Read-access for engagement clients; full open-source on request — see Enterprise · Open-source policy for the licensing detail.

LifeOSAI Architecture

Standalone architecture pack — inline styling only, no remote assets or runtime scripts. Use the Full screen button above, or open the full diagram in a new tab ↗.

Diagram Set

1. Full System Architecture

   • External entry surfaces: browser, Tauri desktop, channels, operators, CI.
   • Browser-facing control plane: apps/web, apps/auth, apps/user-management.
   • Product domains: LifeOSAI Chat, LifeOSAI Companies, LifeOSAI Apps.
   • Runtime plane: apps/api, company orchestration, wakeups, schedulers, agent invoker, live event bus, runtime adapters.
   • Data and operations: database, workspaces, transcripts, company files, skills, artifacts, logs, health checks.
   • Cloud and local lanes: same product APIs, different execution locality.

2. Company Orchestration Runtime

   • Work sources: issue assignment, issue comments, approvals, routine timers, heartbeat timers, direct chat, run now, and channel inbound messages.
   • enqueueWakeup creates queued runs with source and context snapshot.
   • Schedulers claim eligible work and start runtime invocation.
   • Agent invoker mints run-scoped bearer tokens and assembles env, cwd, model, and adapter metadata.
   • Runtime adapters publish run logs, activity, issue updates, and company live events.
   • Run status and agent status are deliberately separate.

3. LifeOSAI Chat System

   • Normal LifeOSAI chat.
   • Direct company-agent chat.
   • Live run transcript mode.
   • Completed transcript replay.
   • Files, Spotlight, Skills, Connectors, Plugins, runtime/model selection.
   • Session listing stays narrow; message lookup can resolve known company-agent transcript paths.

4. Channels Architecture

   • WhatsApp and Telegram ingress.
   • Channel registry and session metadata.
   • Channel-to-agent dispatch.
   • Shared outbound tool contract: mcp__channels__message for Claude Code and the equivalent Pi Agent tool path.
   • Delivery audit links inbound and outbound messages to company, agent, run, and channel session.

5. Runtime Adapter And Tool Plane

   • adapter_config: process env, cwd, command, args, model, instruction discovery, adapter-specific execution knobs.
   • runtime_config: heartbeat policy, scheduler policy, and future session compaction policy.
   • Agent env and project env share the same binding model; project env wins on collisions.
   • Secret refs are company-scoped, validated on write, resolved during invocation, and redacted from persisted output excerpts.

6. Cloud And Local Deployment

   • Cloud: GCP project lifeosai-481608, region asia-south-1, Cloud Run services, Compute Engine agent runtime containers, Artifact Registry docker-images, cloud database, and workspace storage.
   • Local: Tauri 2.0 desktop wrapper, sidecars on ports 3000/3001/3002/4000, local database, ~/LIFEOSAI, and ~/.lifeosai/companies.

7. Security, Data, And Observability

   • User auth and run auth are separate boundaries.
   • Agent-exposed APIs require Authorization: Bearer $LIFEOSAI_RUN_TOKEN.
   • Company access, secret refs, and workspace paths are validated at their own boundaries.
   • Activity logging preserves actor, entity, action, agent id, run id, and details.

8. Operational Sequences

   • Issue assignment.
   • Direct agent chat.
   • Routine timer.
   • Channel inbound.
   • Secret env resolution.

Source Anchors

Useful code anchors for maintaining the diagram:

Path	Responsibility
apps/web	LifeOSAI browser app, static export surface, chat/company/app shell.
apps/tauri	Local desktop wrapper and sidecar boundary.
apps/user-management/src	Central browser-facing routing hub.
apps/user-management/src/sessions/reader.ts	Chat/session transcript reader for Claude Code and Pi Agent sessions.
apps/api/src/orchestration/engine/heartbeat.ts	Heartbeat scheduler and run lifecycle.
apps/api/src/orchestration/engine/wakeup.ts	Wakeup queue helpers.
apps/api/src/orchestration/engine/agent-invoker.ts	Runtime invocation, env assembly, run token injection, and event publishing.
apps/api/src/orchestration/engine/event-bus.ts	Company live event bus.
apps/api/src/orchestration/routes/middleware.ts	Run-scoped bearer-token authentication for agent APIs.
apps/api/src/channels/dispatch.ts	Channel-to-agent dispatch.
apps/api/src/channels/message-tool.ts	mcp__channels__message.
packages/agent/src/runtimes	Claude Code and Pi Agent runtime adapters.
packages/shared/src/orchestration/constants.ts	Live event type constants.
packages/shared/src/orchestration/types/live.ts	Typed live event payloads.
packages/shared/src/orchestration/env-config.ts	Env binding, normalization, secret ref handling, and redaction helpers.

Maintenance notes

• Keep this artifact focused on system architecture, not React component structure.
• If a future change adds a new product surface, place it first in the product domain and control-plane sections, then add orchestration/runtime detail only if the surface actually invokes agents.
• If a future change adds a new agent-exposed API, document the run-token boundary and the related live event contract.
• If a future change touches channels, update the channel ingress, dispatch, outbound tool, and audit path together.

Source doc: lifeosai-agent-systems.md — the written system documentation behind this diagram.

Read next

Platform overview What the code is implementing.

Office Library architecture (deeper) The library and memory implementation.

Enterprise deployment How to deploy on your infrastructure.