Package Architecture

ArgoBox modules follow a 3-tier extraction pattern that separates pure logic from platform-specific wiring. This makes modules reusable outside ArgoBox (in any Node 18+, Cloudflare Workers, Deno, or Bun environment).

The 3 Tiers

packages/MODULE/src/          ← Tier 1 + 2 (portable, published to npm)
  types.ts                    ← Tier 1: Pure types, zero imports
  core.ts                     ← Tier 1: Pure functions, dependency injection
  adapters.ts                 ← Tier 2: Adapter interfaces (injectable)
  index.ts                    ← Re-exports all public API

src/lib/MODULE/adapters/      ← Tier 3 (stays in ArgoBox repo)
  argobox.ts                  ← Wires Tier 1/2 to ArgoBox runtime-env, auth, KV

Tier 1: Types & Core Logic

• Zero framework imports — only Web standard APIs (fetch, crypto.subtle, TextEncoder)
• Dependency injection — all external I/O via adapter interfaces
• Works everywhere — CF Workers, Node, Deno, Bun
• Example: @argobox/chat exports classifySensitivity(), resolveProvider(), etc.

Tier 2: Adapter Interfaces

• Defines contracts — StorageAdapter, EnvAdapter, AuthAdapter
• No implementation — just TypeScript interfaces
• Consumers wire their own — ArgoBox wires KV, fork users wire Redis/Postgres/etc.

Tier 3: ArgoBox Adapter (NOT published)

• Imports ArgoBox-specific modules — runtime-env.ts, auth.ts, streaming.ts
• Creates concrete adapters — createStorageAdapter() returns KV-backed storage
• Stays in src/lib/ — never published to npm

Extracted Packages (as of 2026-03-17)

All 39 packages pass tsc --noEmit and are wired into the prebuild chain.

Package	Subpath Exports	Category
@argobox/tailscale	., ./types, ./adapters	Infrastructure
@argobox/openclaw	., ./types, ./adapters	AI
@argobox/api-credentials	., ./types, ./adapters	Core
@argobox/chat	., ./types, ./adapters	AI
@argobox/workbench	., ./types, ./adapters	Development
@argobox/build-swarm	., ./types, ./adapters	Development
@argobox/cloudflare	., ./types, ./adapters	Infrastructure
@argobox/deployments-sync	., ./types, ./adapters	Development
@argobox/health-monitor	., ./types, ./adapters	Infrastructure
@argobox/network-scanner	., ./types, ./adapters	Security
@argobox/newsletter	., ./types, ./adapters	Content
@argobox/rag-manager	., ./types, ./adapters	AI
@argobox/rag-ops	., ./types, ./adapters	AI
@argobox/security	., ./types, ./adapters	Security
@argobox/servers	., ./types	Infrastructure
@argobox/ai-gateway	., ./types, ./streaming, ./brain-chat	AI
@argobox/edge-toolkit	., ./auth, ./kv-cache, ./rate-limiter, ./roles, ./config, ./types	Core
@argobox/demo-data	., ./types, ./generators/*	Development
@argobox/platform	., ./types, ./core	Infrastructure
@argobox/project-pulse	., ./types, ./core, ./history, ./adapters	Development
@argobox/security-scanner	., ./types, ./patterns, ./scanner, ./healer	Security
@argonaut/core	.	AI

How Imports Work

API routes import from the package:

// src/pages/api/admin/tailscale-status.ts
import { listDevices, listAuthKeys } from '@argobox/tailscale';

Tier 3 adapters import types from the package, ArgoBox modules locally:

// src/lib/tailscale/adapters/argobox.ts
import type { StorageAdapter, EnvAdapter } from '@argobox/tailscale';
import { getEnv, getKV } from '../../runtime-env';  // ArgoBox-specific

Chat uses re-export stubs for backward compatibility:

// src/lib/chat/core.ts (thin stub)
export { classifySensitivity, resolveProvider, ... } from '@argobox/chat';

Build Pipeline

All 39 packages compile during prebuild (before Astro build). The chain is defined in the root package.json prebuild script:

prebuild:
  cd packages/argonaut && npx tsc
  cd packages/security-scanner && npx tsc
  cd packages/tailscale && npx tsc
  cd packages/openclaw && npx tsc
  cd packages/api-credentials && npx tsc
  cd packages/chat && npx tsc
  cd packages/workbench && npx tsc
  cd packages/project-pulse && npx tsc
  cd packages/build-swarm && npx tsc
  cd packages/cloudflare && npx tsc
  cd packages/deployments-sync && npx tsc
  cd packages/health-monitor && npx tsc
  cd packages/network-scanner && npx tsc
  cd packages/newsletter && npx tsc
  cd packages/rag-manager && npx tsc
  cd packages/rag-ops && npx tsc
  cd packages/security && npx tsc
  cd packages/servers && npx tsc
  cd packages/ai-gateway && npx tsc
  cd packages/edge-toolkit && npx tsc
  cd packages/demo-data && npx tsc
  cd packages/platform && npx tsc

Each package produces dist/ with .js + .d.ts files. Vite resolves imports via package.json exports with the "default" condition (required for SSR).

Critical: Every export entry in package.json MUST include a "default" condition alongside "import" and "types". Without it, Vite's commonjs-resolver fails during SSR.

For Fork Users

Fork users get all Tier 1/2 logic via the packages. They only need to:

1. Create their own Tier 3 adapter (or copy and modify argobox.ts)
2. Wire their storage backend (Redis, Postgres, etc.) to the adapter interfaces
3. Set environment variables per FORK.md

See FORK.md at the project root for the complete fork setup guide.

Adding a New Package

Use the MODULE_TEMPLATE:

cp -r MODULE_TEMPLATE packages/my-module
# Edit package.json: name, description
# Move src/lib/my-module/types.ts → packages/my-module/src/types.ts
# Move src/lib/my-module/core.ts → packages/my-module/src/core.ts
# Create index.ts with re-exports
# Update root package.json: add workspace dependency
# Update prebuild script: add tsc step
# Run: pnpm --filter @argobox/my-module exec tsc --noEmit

See the full extraction checklist in FORKABILITY-PLAN.md (Vaults).