# infinite-labs-ai/infinite-os architecture

> Architecture diagram of the GitHub repository infinite-labs-ai/infinite-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/infinite-labs-ai/infinite-os
- Repository: https://github.com/infinite-labs-ai/infinite-os

## Overview

1. **Overall shape: local-first monorepo with a control plane and a data plane**
   - Infinite OS is split into a user-facing **CLI**, a local **app daemon**, a background **worker**, and a **Postgres** database.
   - The CLI is the operator shell and chat UI; the daemon provides the local API boundary; the worker owns scheduled/background sync work; Postgres stores synced analytics data plus system state.

2. **Primary request flow**
   - A user runs `infinite` or `infinite setup` in the terminal.
   - The CLI talks to the **app daemon** over localhost.
   - For analytics questions, the CLI delegates to the **LLM controller** and the **analytical engine** to turn a natural-language prompt into governed metric queries, then renders the result in the TUI.
   - For setup and syncing, the CLI orchestrates connection/configuration flows and then triggers local services.

3. **Data ingestion and sync boundary**
   - The **worker** is the subsystem that connects to external providers and syncs data into Postgres.
   - Supported providers in the repo include **GA4, PostHog, Stripe, Meta, Shopify, and X**.
   - The database is treated as a rebuildable cache: provider source systems remain authoritative, while local tables store sync state, raw records, jobs, schedules, and queryable views.

4. **Analytics/metric layer**
   - `packages/analytical-engine` and `packages/metadata` define the typed metric/provenance layer that answers questions like “page views last 7 days.”
   - This layer is what keeps the system from behaving like a free-form SQL tool: it resolves queries to known metrics and source-aware views rather than guessing.
   - The result is source-accurate analytics with explicit authority rules.

5. **LLM integration boundary**
   - `packages/llm-controller` manages model auth, prompt assembly, session memory, and query advice.
   - The README makes the trust model explicit: prompts are sent to the user’s own **Claude or Codex** credentials; the runtime does **not** execute arbitrary shell commands or expose local data except through the intended query flow.
   - This package is the bridge between conversational input and the governed analytics layer.

6. **Setup/onboarding subsystem**
   - `packages/setup` handles the guided onboarding flow: provider selection, prompts, recommendations, browser handoff, SSRF-safe flows, and reconciliation of setup state.
   - It also manages install commands and workspace artifacts, which suggests setup is a first-class workflow rather than a one-off script.
   - This is the boundary where public provider metadata, user confirmation, and local configuration converge.

7. **Configuration, identity, and encryption**
   - `packages/config` centralizes workspace ID, daemon endpoint, active project, and the local home directory layout.
   - `packages/core` handles encryption/fingerprinting concerns; the README notes connector credentials are encrypted at rest with `GROWTH_OS_ENCRYPTION_KEY`.
   - Configuration is stored locally in a gitignored `.growth-os/` area, reinforcing the local-only trust boundary.

8. **Database and migration layer**
   - `packages/db` owns schema migrations and database access.
   - The migration history shows the schema evolved to cover control-plane state, sync state, jobs/schedules, saved reports, provider-specific truth tables, metadata registries, security roles, OAuth token links, and workspace ownership.
   - There is a `pglite` adapter, indicating the repo also supports lightweight/test-local database execution in addition to Postgres.

9. **CLI and terminal UI**
   - `apps/cli` is the main user entrypoint. It contains command handling plus a rich TUI built on a vendored Ink implementation in `ui-tui/packages/ink`.
   - The CLI includes formatting, progress reporting, interactive sessions, connect/setup wizards, and transcript rendering.
   - This layer is purely presentation/orchestration; it does not own analytics or sync logic.

10. **Daemon lifecycle and coordination**
    - `apps/app` appears to be the local daemon process: it has daemon descriptor/spawn-lock logic and tests around loopback binding and listening.
    - That suggests it protects singleton startup and exposes a local HTTP surface for the CLI to discover and talk to.
    - The daemon is the coordination point between CLI requests, worker status, and local config.

11. **Background worker and scheduled jobs**
    - `apps/worker` is a separate service with its own entrypoint and tests, implying an independently runnable process.
    - Its responsibility is likely scheduled sync execution and job processing, which matches the database schema for jobs and schedules.
    - In the architecture diagram, it should sit behind the daemon/CLI and in front of provider APIs and Postgres writes.

12. **Website instrumentation as a separate distributed package**
    - `packages/instrument` is published as `infinite-tag`, a distinct package used inside a customer’s own website repository.
    - It auto-detects frameworks such as **Next.js, Vite + React, and static HTML**, and applies reversible, idempotent changes to add tracking.
    - This is an external integration boundary: it does not run inside Infinite OS itself, but feeds GA4/PostHog collection upstream.

13. **Runtime and support packages**
    - `packages/runtime` provides shared runtime helpers such as session memory, notifications, recipes, and module loading.
    - `packages/connectors` and `packages/metadata` appear to hold provider-specific fixtures and shared metadata definitions used across setup, sync, and analytics.
    - These packages keep provider logic and runtime concerns out of the CLI/daemon/worker apps.

14. **Operational packaging**
    - The repo is managed as a **pnpm workspace**, with Docker-based local stack support via `docker-compose.yml` and CI/publish workflows in `.github/workflows`.
    - Scripts and docs show a deliberate local install/update path, including automatic self-update on launch and a one-command bootstrap installer.
    - For an architecture diagram, the operational view should show: user terminal → CLI → daemon → worker → Postgres, plus side paths to provider APIs, browser-based auth, and model-provider auth.

Main entry points: [`packages/setup/src/index.ts`](https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/setup/src/index.ts) (Setup), [`apps/cli/src/index.ts`](https://github.com/infinite-labs-ai/infinite-os/blob/main/apps/cli/src/index.ts) (CLI), [`packages/db/src/index.ts`](https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/db/src/index.ts) (Database), [`apps/app/src/index.ts`](https://github.com/infinite-labs-ai/infinite-os/blob/main/apps/app/src/index.ts) (Daemon)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Apps"]
  node_cli["CLI<br/>terminal app<br/>[index.ts]"]
  node_daemon["Daemon<br/>local api<br/>[index.ts]"]
  node_worker["Worker<br/>sync runner<br/>[index.ts]"]
end

subgraph group_packages["Packages"]
  node_db[("Database<br/>postgres schema<br/>[index.ts]")]
  node_llm["LLM Control<br/>model bridge<br/>[index.ts]"]
  node_analysis["Analytical Engine<br/>metric planner<br/>[index.ts]"]
  node_metadata["Metadata<br/>metric catalog<br/>[index.ts]"]
  node_setup["Setup<br/>onboarding flow<br/>[index.ts]"]
  node_config["Config<br/>[index.ts]"]
  node_core{{"Core<br/>[index.ts]"}}
  node_runtime["Runtime<br/>[index.ts]"]
  node_instrument["Instrument<br/>site tagger<br/>[index.ts]"]
  node_connectors["Connectors<br/>provider fixtures<br/>[index.ts]"]
end

subgraph group_ui["TUI"]
  node_uiink["Ink<br/>tui runtime<br/>[index.js]"]
end

node_cli -->|"local API"| node_daemon
node_cli -->|"chat + advice"| node_llm
node_cli -->|"onboarding"| node_setup
node_cli -->|"render TUI"| node_uiink
node_daemon -.->|"coordination"| node_worker
node_daemon -->|"read settings"| node_config
node_worker -->|"writes sync data"| node_db
node_setup -->|"provision workspace"| node_config
node_setup -->|"encrypt creds"| node_core
node_setup -.->|"provider guidance"| node_connectors
node_llm -->|"governed query"| node_analysis
node_llm -->|"memory + tools"| node_runtime
node_analysis -->|"resolve metrics"| node_metadata
node_analysis -->|"query views"| node_db
node_metadata -.->|"seed schema"| node_db
node_instrument -.->|"provider targets"| node_connectors
node_instrument -.->|"bootstrap site"| node_setup
node_core -.->|"encrypted storage"| node_db
node_runtime -.->|"session UI"| node_uiink

click node_cli "https://github.com/infinite-labs-ai/infinite-os/blob/main/apps/cli/src/index.ts"
click node_daemon "https://github.com/infinite-labs-ai/infinite-os/blob/main/apps/app/src/index.ts"
click node_worker "https://github.com/infinite-labs-ai/infinite-os/blob/main/apps/worker/src/index.ts"
click node_db "https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/db/src/index.ts"
click node_llm "https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/llm-controller/src/index.ts"
click node_analysis "https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/analytical-engine/src/index.ts"
click node_metadata "https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/metadata/src/index.ts"
click node_setup "https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/setup/src/index.ts"
click node_config "https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/config/src/index.ts"
click node_core "https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/core/src/index.ts"
click node_runtime "https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/runtime/src/index.ts"
click node_instrument "https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/instrument/src/index.ts"
click node_connectors "https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/connectors/src/index.ts"
click node_uiink "https://github.com/infinite-labs-ai/infinite-os/blob/main/ui-tui/packages/ink/index.js"

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_cli,node_daemon,node_worker toneBlue
class node_db,node_llm,node_analysis,node_metadata,node_setup,node_config,node_core,node_runtime,node_instrument,node_connectors toneAmber
class node_uiink toneMint
```

## Components

### Apps

User-facing executables and local services

- [CLI](https://github.com/infinite-labs-ai/infinite-os/blob/main/apps/cli/src/index.ts): terminal app · Operator shell, setup flow, and chat UI entrypoint · `apps/cli/src/index.ts`
- [Daemon](https://github.com/infinite-labs-ai/infinite-os/blob/main/apps/app/src/index.ts): local api · Singleton local service boundary for CLI coordination · `apps/app/src/index.ts`
- [Worker](https://github.com/infinite-labs-ai/infinite-os/blob/main/apps/worker/src/index.ts): sync runner · Background job processor and provider sync service · `apps/worker/src/index.ts`

### Packages

Shared domain and infrastructure packages

- [Database](https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/db/src/index.ts): postgres schema · Migrations and access layer for state, sync data, and queryable views · `packages/db/src/index.ts`
- [LLM Control](https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/llm-controller/src/index.ts): model bridge · Auth, prompt assembly, memory, and query advice for model calls · `packages/llm-controller/src/index.ts`
- [Analytical Engine](https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/analytical-engine/src/index.ts): metric planner · Governed metric and source-aware analytics resolution · `packages/analytical-engine/src/index.ts`
- [Metadata](https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/metadata/src/index.ts): metric catalog · Typed definitions and provenance for metrics and source mappings · `packages/metadata/src/index.ts`
- [Setup](https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/setup/src/index.ts): onboarding flow · Guided provider onboarding, browser handoff, and reconciliation · `packages/setup/src/index.ts`
- [Config](https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/config/src/index.ts): workspace config · Workspace identity, daemon endpoint, and local home layout · `packages/config/src/index.ts`
- [Core](https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/core/src/index.ts): crypto core · Credential encryption and fingerprinting utilities · `packages/core/src/index.ts`
- [Runtime](https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/runtime/src/index.ts): shared runtime · Session memory, notifications, recipes, and module loading · `packages/runtime/src/index.ts`
- [Instrument](https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/instrument/src/index.ts): site tagger · External website instrumentation and provider injection package · `packages/instrument/src/index.ts`
- [Connectors](https://github.com/infinite-labs-ai/infinite-os/blob/main/packages/connectors/src/index.ts): provider fixtures · Provider-specific fixtures and connector-shape helpers · `packages/connectors/src/index.ts`

### TUI

Vendored terminal UI runtime

- [Ink](https://github.com/infinite-labs-ai/infinite-os/blob/main/ui-tui/packages/ink/index.js): tui runtime · Vendored terminal UI framework used by the CLI · `ui-tui/packages/ink/index.js`

## Connections

- CLI → Daemon: local API · CLI sends commands and session requests to the daemon
- CLI → LLM Control: chat + advice · CLI delegates conversational analysis and query guidance
- CLI → Setup: onboarding · CLI drives provider selection and setup workflows
- CLI → Ink: render TUI · CLI uses Ink-based terminal rendering and interaction
- Daemon → Worker: coordination · Daemon surfaces sync and job state from the worker
- Daemon → Config: read settings · Daemon resolves workspace and endpoint configuration
- Worker → Database: writes sync data · Worker persists jobs, raw records, and views
- Setup → Config: provision workspace · Setup creates and reconciles local workspace state
- Setup → Core: encrypt creds · Setup stores connector credentials using local encryption
- Setup → Connectors: provider guidance · Setup uses provider-specific metadata and fixtures
- LLM Control → Analytical Engine: governed query · LLM controller turns prompts into metric-aware requests
- LLM Control → Runtime: memory + tools · LLM controller uses shared session memory and runtime helpers
- Analytical Engine → Metadata: resolve metrics · Analytical engine depends on typed metric and provenance definitions
- Analytical Engine → Database: query views · Analytics read from queryable views and persisted state
- Metadata → Database: seed schema · Metadata definitions are reflected in the database schema
- Instrument → Connectors: provider targets · Instrumentation package targets GA4, PostHog, and X collection flows
- Instrument → Setup: bootstrap site · Setup can guide installation of external tracking instrumentation
- Core → Database: encrypted storage · Database stores encrypted connector and workspace secrets
- Runtime → Ink: session UI · Runtime helpers support interactive terminal sessions
