Architecture

How decli is structured so Mac desk excellence comes first, and the platform grows without losing the plot.

Wedge

Instant value = Mac-only desk backup & restore that is great. Platform APIs, agents, and integrations expand the ecosystem after that trust is earned.

System map

┌─────────────────────────────────────────────────────────────┐
│  Humans                                                      │
│  MacBook / mini / iPad  ·  Workspace sign-in  ·  1Password   │
└───────────────┬─────────────────────────────┬───────────────┘
                │ CLI / menu bar              │ Web console
                ▼                             ▼
┌──────────────────────────┐    ┌──────────────────────────────┐
│  decli CLI (Typer)       │    │  Next.js web (43100)         │
│  desk · google · ai · …  │◄──►│  Settings · Integrations     │
└───────────┬──────────────┘    │  docs.decli.dev              │
            │                   └──────────────┬───────────────┘
            │ bridge 43105                     │ BFF / rewrites
            ▼                                  ▼
┌──────────────────────────┐    ┌──────────────────────────────┐
│  FastAPI apps/api 43101  │    │  Google Cloud (project decli)│
│  REST · GraphQL · OAuth  │    │  Auth · Drive · Maps · AQI   │
└───────────┬──────────────┘    │  Agents · Observability ·    │
            │                   │  IAM · Storage · Telemetry   │
            ▼                   └──────────────────────────────┘
┌──────────────────────────┐
│  Local desk              │
│  Caddy · Postgres@15     │
│  iTerm · ~/dev · uv/pnpm │
└──────────────────────────┘

Layers

Desk (local) — Caddy one-instance, Homebrew Postgres, iTerm, repos. Pack/recover is the product.
CLI — Natural language + typed commands; writes session environment.
Bridge — Local API for menu bar and web permission grants.
Web platform — Auth, settings, integrations hub, docs, playground.
Google product APIs — Workspace, Drive, Docs suite, Maps, Air Quality.
Google platform APIs — Agents, App Hub/Topology/Lifecycle, observability, IAM/IAP/SCC, storage, telemetry, model armor — operate and improve the system.

Data flows

Pack

Components → snapshot under ~/.decli/backups/desk/ → encrypt → destination (iCloud / AWS / GCS / Drive / S3-compatible / Tailscale peer).

Recover

Decrypt → bootstrap phases → restore components → deps install → soft Docker → AI key pull → doctor.

Session meta

Active device + optional browser geo → Air Quality → ~/.decli/session/environment.json and Magenta properties on web.

Settings vs integrations

See overview: settings = behavior; integrations = connections. New capabilities should register a capability id, connection health, CLI mirror, and docs page.

Recursive improvement

Use desk pack/recover daily
Emit telemetry (Magenta + GCP Logging/Monitoring/Trace)
Agents and notebooks consume signals
Playbook defaults and doctor checks get better
Repeat