How alghamdima/aqw works
1. This is a pnpm/Turborepo monorepo organized around a single product, TurboClaw, with one primary customer-facing app and several shared domain packages. The repo is split into apps/, packages/, and tooling/, with Turborepo handling workspace orchestration, caching, and shared build rules.
2. apps/web is the main frontend shell. It is a Next.js App Router application with localized routes under [locale], split into two major surfaces: a marketing site and a dashboard. The dashboard contains account, billing, API key, and agent/instance management screens.
3. The web app is mostly a composition layer. Its modules/ directory groups feature areas by domain (auth, billing, dashboard, marketing, common, user), while lib/ holds cross-cutting client/server helpers for API access, auth, query state, metadata, and providers. This keeps page routes thin and pushes behavior into feature modules.
4. There is a catch-all API bridge in the web app at apps/web/src/app/api/[...route]/route.ts. That suggests the frontend exposes a single API entrypoint that forwards to or wraps the backend package rather than embedding business logic directly in the UI.
5. packages/api is the backend service boundary. It defines environment loading, middleware, shared error handling, and feature routers. The main routers are auth and openclaw, with an additional pairing sub-router under openclaw. This is the primary business/API layer consumed by the web app.
6. packages/openclaw is the core domain engine. It contains the deployment orchestration logic, instance utilities, pairing config, logs, and provider adapters. The deployment subsystem supports multiple backends: Fly, GCP, and VPS/Caddy, indicating the product can manage OpenClaw instances across different infrastructure targets.
7. Deployment is modeled as a provider abstraction. Shared schemas and env loaders sit above provider-specific implementations, so the app can treat deployment as a single domain while swapping execution targets underneath. The dashboard’s instance views, deploy forms, logs, and pairing screens likely map directly to this package’s lifecycle objects.
8. packages/db is the persistence layer. It uses Drizzle migrations and schema definitions, with separate tables for auth and openclaw domains. It also includes utility scripts for reset/status, making database state and migration management a first-class part of the architecture.
9. Authentication is isolated into packages/auth and consumed by both the web app and API layer. The package exposes client/server entrypoints and env configuration, while the web app has dedicated auth modules for API calls and social provider UI. Auth is therefore a shared infrastructure capability, not just a page concern.
10. Billing is similarly isolated in packages/billing and surfaced in the dashboard. The package has client/server SDK entrypoints and environment config, while the web app contains billing-specific views and API helpers. This keeps payment logic separate from UI and from the core deployment domain.
11. Shared cross-cutting code lives in packages/shared, packages/i18n, and packages/ui. shared holds constants, exception utilities, IDs, pagination/sort schemas, and logging providers; i18n centralizes translation resources and locale helpers for English and Spanish; ui is split into shared assets/styles and web components, giving the app a reusable design system.
12. Operationally, the repo is built for multi-environment deployment. There are docs for local development, Google Cloud, VPS setup, billing, and operations, plus Docker Compose, GitHub Actions workflows, and lint/format tooling. This indicates the architecture is designed not just for runtime code, but for repeatable deployment, database publishing, and CI-driven validation.
Main entry points: web Web app · api API · openclaw OpenClaw · turbo.json Turbo
Components 24
Apps
Customer-facing runtime applications.
- Web app · Localized App Router frontend with marketing and dashboard surfaces.
apps/web - API bridge · Single frontend API entrypoint that forwards requests into the backend layer.
apps/web/src/app/api/[...route]/route.ts - Web modules · Domain-oriented feature composition for auth, billing, dashboard, marketing, and user flows.
apps/web/src/modules - Web lib · Shared client/server helpers for API access, auth, query state, metadata, and providers.
apps/web/src/lib - Routes · Localized marketing and dashboard route surfaces, including account, billing, API keys, and instance screens.
apps/web/src/app/[locale] - Common UI · Shared layout, theming, navigation, and common UI composition for the web app.
apps/web/src/modules/common - Dashboard · Dashboard feature area for agent and instance management, deployment, logs, and pairing.
apps/web/src/modules/dashboard - Marketing · Public-facing home, header, footer, and promotional content for the product site.
apps/web/src/modules/marketing
Packages
Shared domain, platform, and UI packages.
- API · Primary business API boundary with env loading, middleware, shared errors, and feature routers.
packages/api - Auth router · Authentication routes and API boundary for login and session-related flows.
packages/api/src/modules/auth/router.ts - OpenClaw router · Core product routes for OpenClaw domain operations.
packages/api/src/modules/openclaw/router.ts - Pairing router · Nested pairing routes under the OpenClaw API domain.
packages/api/src/modules/openclaw/pairing/router.ts - OpenClaw · Core deployment orchestration, pairing config, logs, and provider adapters.
packages/openclaw - Deployment · Deployment lifecycle, schema, logs, and provider abstraction for instance operations.
packages/openclaw/src/deployment - Providers · Backend-specific deployment implementations for Fly, GCP, and VPS/Caddy.
packages/openclaw/src/deployment/providers - Database · Persistence layer with migrations, schemas, and database maintenance scripts.
packages/db - Auth pkg · Shared client/server authentication package consumed by the web app and API.
packages/auth - Billing pkg · Shared client/server billing package surfaced in the dashboard and API helpers.
packages/billing - Shared · Constants, exceptions, IDs, pagination/sort schemas, and logging providers.
packages/shared - i18n · Translation resources and locale helpers for English and Spanish.
packages/i18n - UI kit · Reusable web design system components, hooks, and styles.
packages/ui/web - UI assets · Shared icons, SVG assets, theme styles, and UI typings.
packages/ui/shared
Connections 35
- Turbo → Web app: builds · Coordinates app tasks and caching for the web workspace.
- Turbo → API: orchestrates · Runs package tasks with workspace-aware boundaries and cache rules.
- Turbo → OpenClaw: orchestrates · Includes the core domain package in monorepo task execution.
- Web app → Routes: routes · Routes are composed from localized marketing and dashboard surfaces.
- Web app → Web modules: composes · Page shells stay thin by delegating behavior to feature modules.
- Web app → Web lib: uses · UI uses shared client/server helpers for data, auth, and providers.
- Web app → API bridge: exposes · Frontend forwards or wraps backend calls through a single API entrypoint.
- Routes → Marketing: includes · Localized route tree includes the public marketing surface.
- Routes → Dashboard: includes · Localized route tree includes the authenticated dashboard surface.
- Dashboard → Common UI: shares · Dashboard UI reuses common layout, theme, and navigation primitives.
- Marketing → Common UI: shares · Marketing UI reuses shared layout and presentation primitives.
- Web app → i18n: localizes · The app consumes centralized translations and locale helpers.
- Web app → UI kit: renders · Web app uses shared component library for interactive UI.
- Web app → UI assets: styles · Web app consumes shared assets and theme styles.
- Web app → Auth pkg: auth · Frontend auth flows rely on the shared authentication package.
- Web app → Billing pkg: billing · Billing views and helpers depend on the shared billing package.
- API bridge → API: forwards to · Catch-all route bridges frontend requests into the backend API.
- API → Auth router: routes · Backend exposes authentication feature routes.
- API → OpenClaw router: routes · Backend exposes the main OpenClaw domain routes.
- OpenClaw router → Pairing router: nests · OpenClaw API contains a pairing sub-router.
- API → OpenClaw: uses · API layer delegates domain work to the core OpenClaw package.
- OpenClaw → Deployment: contains · Deployment is the central orchestration subsystem.
- Deployment → Providers: adapts · Deployment swaps execution targets through provider adapters.
- OpenClaw → Database: persists · Domain state and lifecycle data are backed by the database layer.
- OpenClaw → Shared: depends on · OpenClaw reuses shared constants, schemas, IDs, and logging.
- API → Database: reads/writes · Backend participates in persistence and domain state management.
- API → Auth pkg: authn · API uses the shared authentication infrastructure.
- API → Billing pkg: billing · API uses the shared billing infrastructure.
- Auth pkg → Shared: depends on · Auth package consumes shared utilities and schemas.
- Billing pkg → Shared: depends on · Billing package consumes shared utilities and types.
- i18n → Shared: types · Locale resources share common types and validation utilities.
- UI kit → UI assets: extends · Web component library builds on shared assets and styles.
- Tooling → Turbo: supports · Repo tooling complements workspace orchestration and code generation.
- Tooling → Web app: checks · Shared tooling is used to lint, format, and validate the web app.
- Tooling → API: checks · Shared tooling is used to lint, format, and validate backend packages.