# alghamdima/aqw architecture

> Architecture diagram of the GitHub repository alghamdima/aqw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alghamdima/aqw
- Repository: https://github.com/alghamdima/aqw

## Overview

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: [`apps/web`](https://github.com/alghamdima/aqw/tree/main/apps/web) (Web app), [`packages/api`](https://github.com/alghamdima/aqw/tree/main/packages/api) (API), [`packages/openclaw`](https://github.com/alghamdima/aqw/tree/main/packages/openclaw) (OpenClaw), [`turbo.json`](https://github.com/alghamdima/aqw/blob/main/turbo.json) (Turbo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_apps["Apps"]
  node_node_web_app["Web app<br/>Next.js shell"]
  node_node_web_api_bridge["API bridge<br/>catch-all route<br/>[route.ts]"]
  node_node_web_modules["Web modules<br/>feature modules"]
  node_node_web_lib["Web lib<br/>cross-cutting helpers"]
  node_node_web_routes["Routes"]
  node_node_web_common["Common UI<br/>layout primitives"]
  node_node_web_dashboard["Dashboard<br/>instance UI"]
  node_node_web_marketing["Marketing<br/>site UI"]
end

subgraph group_grp_packages["Packages"]
  node_node_api["API<br/>backend service"]
  node_node_api_auth["Auth router<br/>api router<br/>[router.ts]"]
  node_node_api_openclaw["OpenClaw router<br/>api router<br/>[router.ts]"]
  node_node_api_pairing["Pairing router<br/>sub-router<br/>[router.ts]"]
  node_node_openclaw["OpenClaw<br/>domain engine"]
  node_node_openclaw_deploy["Deployment<br/>orchestration"]
  node_node_openclaw_providers["Providers<br/>adapter layer"]
  node_node_db["Database<br/>Drizzle schema"]
  node_node_auth_pkg["Auth pkg<br/>auth sdk"]
  node_node_billing_pkg["Billing pkg<br/>billing sdk"]
  node_node_shared["Shared<br/>common utilities"]
  node_node_i18n["i18n<br/>locale resources"]
  node_node_ui_web["UI kit<br/>web components"]
  node_node_ui_shared["UI assets<br/>shared styles"]
end

subgraph group_grp_tooling["Tooling"]
  node_node_turbo["Turbo<br/>workspace orchestration<br/>[turbo.json]"]
  node_node_tooling["Tooling"]
end

node_node_turbo -->|"builds"| node_node_web_app
node_node_turbo -->|"orchestrates"| node_node_api
node_node_turbo -->|"orchestrates"| node_node_openclaw
node_node_web_app -->|"routes"| node_node_web_routes
node_node_web_app -->|"composes"| node_node_web_modules
node_node_web_app -->|"uses"| node_node_web_lib
node_node_web_app -->|"exposes"| node_node_web_api_bridge
node_node_web_routes -->|"includes"| node_node_web_marketing
node_node_web_routes -->|"includes"| node_node_web_dashboard
node_node_web_dashboard -->|"shares"| node_node_web_common
node_node_web_marketing -->|"shares"| node_node_web_common
node_node_web_app -->|"localizes"| node_node_i18n
node_node_web_app -->|"renders"| node_node_ui_web
node_node_web_app -->|"styles"| node_node_ui_shared
node_node_web_app -->|"auth"| node_node_auth_pkg
node_node_web_app -->|"billing"| node_node_billing_pkg
node_node_web_api_bridge -->|"forwards to"| node_node_api
node_node_api -->|"routes"| node_node_api_auth
node_node_api -->|"routes"| node_node_api_openclaw
node_node_api_openclaw -->|"nests"| node_node_api_pairing
node_node_api -->|"uses"| node_node_openclaw
node_node_openclaw -->|"contains"| node_node_openclaw_deploy
node_node_openclaw_deploy -->|"adapts"| node_node_openclaw_providers
node_node_openclaw -->|"persists"| node_node_db
node_node_openclaw -->|"depends on"| node_node_shared
node_node_api -->|"reads/writes"| node_node_db
node_node_api -->|"authn"| node_node_auth_pkg
node_node_api -->|"billing"| node_node_billing_pkg
node_node_auth_pkg -->|"depends on"| node_node_shared
node_node_billing_pkg -->|"depends on"| node_node_shared
node_node_i18n -->|"types"| node_node_shared
node_node_ui_web -->|"extends"| node_node_ui_shared
node_node_tooling -->|"supports"| node_node_turbo
node_node_tooling -->|"checks"| node_node_web_app
node_node_tooling -->|"checks"| node_node_api

click node_node_web_app "https://github.com/alghamdima/aqw/tree/main/apps/web"
click node_node_web_api_bridge "https://github.com/alghamdima/aqw/blob/main/apps/web/src/app/api/[...route]/route.ts"
click node_node_web_modules "https://github.com/alghamdima/aqw/tree/main/apps/web/src/modules"
click node_node_web_lib "https://github.com/alghamdima/aqw/tree/main/apps/web/src/lib"
click node_node_web_routes "https://github.com/alghamdima/aqw/tree/main/apps/web/src/app/[locale]"
click node_node_web_common "https://github.com/alghamdima/aqw/tree/main/apps/web/src/modules/common"
click node_node_web_dashboard "https://github.com/alghamdima/aqw/tree/main/apps/web/src/modules/dashboard"
click node_node_web_marketing "https://github.com/alghamdima/aqw/tree/main/apps/web/src/modules/marketing"
click node_node_api "https://github.com/alghamdima/aqw/tree/main/packages/api"
click node_node_api_auth "https://github.com/alghamdima/aqw/blob/main/packages/api/src/modules/auth/router.ts"
click node_node_api_openclaw "https://github.com/alghamdima/aqw/blob/main/packages/api/src/modules/openclaw/router.ts"
click node_node_api_pairing "https://github.com/alghamdima/aqw/blob/main/packages/api/src/modules/openclaw/pairing/router.ts"
click node_node_openclaw "https://github.com/alghamdima/aqw/tree/main/packages/openclaw"
click node_node_openclaw_deploy "https://github.com/alghamdima/aqw/tree/main/packages/openclaw/src/deployment"
click node_node_openclaw_providers "https://github.com/alghamdima/aqw/tree/main/packages/openclaw/src/deployment/providers"
click node_node_db "https://github.com/alghamdima/aqw/tree/main/packages/db"
click node_node_auth_pkg "https://github.com/alghamdima/aqw/tree/main/packages/auth"
click node_node_billing_pkg "https://github.com/alghamdima/aqw/tree/main/packages/billing"
click node_node_shared "https://github.com/alghamdima/aqw/tree/main/packages/shared"
click node_node_i18n "https://github.com/alghamdima/aqw/tree/main/packages/i18n"
click node_node_ui_web "https://github.com/alghamdima/aqw/tree/main/packages/ui/web"
click node_node_ui_shared "https://github.com/alghamdima/aqw/tree/main/packages/ui/shared"
click node_node_turbo "https://github.com/alghamdima/aqw/blob/main/turbo.json"
click node_node_tooling "https://github.com/alghamdima/aqw/tree/main/tooling"

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_node_web_app,node_node_web_api_bridge,node_node_web_modules,node_node_web_lib,node_node_web_routes,node_node_web_common,node_node_web_dashboard,node_node_web_marketing toneBlue
class node_node_api,node_node_api_auth,node_node_api_openclaw,node_node_api_pairing,node_node_openclaw,node_node_openclaw_deploy,node_node_openclaw_providers,node_node_db,node_node_auth_pkg,node_node_billing_pkg,node_node_shared,node_node_i18n,node_node_ui_web,node_node_ui_shared toneAmber
class node_node_turbo,node_node_tooling toneMint
```

## Components

### Apps

Customer-facing runtime applications.

- [Web app](https://github.com/alghamdima/aqw/tree/main/apps/web): Next.js shell · Localized App Router frontend with marketing and dashboard surfaces. · `apps/web`
- [API bridge](https://github.com/alghamdima/aqw/blob/main/apps/web/src/app/api/[...route]/route.ts): catch-all route · Single frontend API entrypoint that forwards requests into the backend layer. · `apps/web/src/app/api/[...route]/route.ts`
- [Web modules](https://github.com/alghamdima/aqw/tree/main/apps/web/src/modules): feature modules · Domain-oriented feature composition for auth, billing, dashboard, marketing, and user flows. · `apps/web/src/modules`
- [Web lib](https://github.com/alghamdima/aqw/tree/main/apps/web/src/lib): cross-cutting helpers · Shared client/server helpers for API access, auth, query state, metadata, and providers. · `apps/web/src/lib`
- [Routes](https://github.com/alghamdima/aqw/tree/main/apps/web/src/app/[locale]): app routes · Localized marketing and dashboard route surfaces, including account, billing, API keys, and instance screens. · `apps/web/src/app/[locale]`
- [Common UI](https://github.com/alghamdima/aqw/tree/main/apps/web/src/modules/common): layout primitives · Shared layout, theming, navigation, and common UI composition for the web app. · `apps/web/src/modules/common`
- [Dashboard](https://github.com/alghamdima/aqw/tree/main/apps/web/src/modules/dashboard): instance UI · Dashboard feature area for agent and instance management, deployment, logs, and pairing. · `apps/web/src/modules/dashboard`
- [Marketing](https://github.com/alghamdima/aqw/tree/main/apps/web/src/modules/marketing): site UI · 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](https://github.com/alghamdima/aqw/tree/main/packages/api): backend service · Primary business API boundary with env loading, middleware, shared errors, and feature routers. · `packages/api`
- [Auth router](https://github.com/alghamdima/aqw/blob/main/packages/api/src/modules/auth/router.ts): api router · Authentication routes and API boundary for login and session-related flows. · `packages/api/src/modules/auth/router.ts`
- [OpenClaw router](https://github.com/alghamdima/aqw/blob/main/packages/api/src/modules/openclaw/router.ts): api router · Core product routes for OpenClaw domain operations. · `packages/api/src/modules/openclaw/router.ts`
- [Pairing router](https://github.com/alghamdima/aqw/blob/main/packages/api/src/modules/openclaw/pairing/router.ts): sub-router · Nested pairing routes under the OpenClaw API domain. · `packages/api/src/modules/openclaw/pairing/router.ts`
- [OpenClaw](https://github.com/alghamdima/aqw/tree/main/packages/openclaw): domain engine · Core deployment orchestration, pairing config, logs, and provider adapters. · `packages/openclaw`
- [Deployment](https://github.com/alghamdima/aqw/tree/main/packages/openclaw/src/deployment): orchestration · Deployment lifecycle, schema, logs, and provider abstraction for instance operations. · `packages/openclaw/src/deployment`
- [Providers](https://github.com/alghamdima/aqw/tree/main/packages/openclaw/src/deployment/providers): adapter layer · Backend-specific deployment implementations for Fly, GCP, and VPS/Caddy. · `packages/openclaw/src/deployment/providers`
- [Database](https://github.com/alghamdima/aqw/tree/main/packages/db): Drizzle schema · Persistence layer with migrations, schemas, and database maintenance scripts. · `packages/db`
- [Auth pkg](https://github.com/alghamdima/aqw/tree/main/packages/auth): auth sdk · Shared client/server authentication package consumed by the web app and API. · `packages/auth`
- [Billing pkg](https://github.com/alghamdima/aqw/tree/main/packages/billing): billing sdk · Shared client/server billing package surfaced in the dashboard and API helpers. · `packages/billing`
- [Shared](https://github.com/alghamdima/aqw/tree/main/packages/shared): common utilities · Constants, exceptions, IDs, pagination/sort schemas, and logging providers. · `packages/shared`
- [i18n](https://github.com/alghamdima/aqw/tree/main/packages/i18n): locale resources · Translation resources and locale helpers for English and Spanish. · `packages/i18n`
- [UI kit](https://github.com/alghamdima/aqw/tree/main/packages/ui/web): web components · Reusable web design system components, hooks, and styles. · `packages/ui/web`
- [UI assets](https://github.com/alghamdima/aqw/tree/main/packages/ui/shared): shared styles · Shared icons, SVG assets, theme styles, and UI typings. · `packages/ui/shared`

### Tooling

Repository-wide build, lint, and automation support.

- [Turbo](https://github.com/alghamdima/aqw/blob/main/turbo.json): workspace orchestration · Turborepo configuration, generators, cache boundaries, and task orchestration. · `turbo.json`
- [Tooling](https://github.com/alghamdima/aqw/tree/main/tooling): repo tooling · Shared scripts and lint/format/typescript tooling used across the monorepo. · `tooling`

## Connections

- 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.
