Architecture

Overview

AACWorkflow is a Go backend + monorepo frontend (pnpm workspaces + Turborepo) with shared packages.

┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
│   Next.js    │────>│  Go Backend  │────>│   PostgreSQL     │
│   Frontend   │<────│  (Chi + WS)  │<────│   (pgvector)     │
└──────────────┘     └──────┬───────┘     └──────────────────┘
                            │
                     ┌──────┴───────┐
                     │ Agent Daemon │  (runs on your machine)
                     │Claude/Codex/ │
                     │OpenClaw/Copilot│
                     └──────────────┘

Project Structure

Directory	Purpose	Technology
`server/`	Go backend	Chi router, sqlc for DB, gorilla/websocket
`apps/web/`	Next.js frontend	App Router
`apps/desktop/`	Electron desktop app	electron-vite
`apps/docs/`	Documentation site	Fumadocs
`apps/mobile/`	iOS mobile app	Expo / React Native
`packages/core/`	Headless business logic	Zero react-dom, shared across platforms
`packages/ui/`	Atomic UI components	Zero business logic, shadcn-based
`packages/views/`	Shared business pages	Zero next/*, zero react-router imports
`packages/tsconfig/`	Shared TypeScript config	—
`packages/eslint-config/`	Shared ESLint config	—
`services/billing/`	Stripe-backed billing	Go, Chi, Stripe SDK

Backend Architecture

Entry points (cmd/): server (HTTP API), aacworkflow (CLI + daemon), migrate
Handlers (internal/handler/): one file per domain (issue, comment, agent, auth, daemon)
Real-time (internal/realtime/): Hub manages WebSocket clients, server broadcasts events
Authentication (internal/auth/ + internal/middleware/): JWT (HS256), middleware sets X-User-ID and X-User-Email headers
Task lifecycle (internal/service/task.go): enqueue → claim → start → complete/fail
Agent SDK (pkg/agent/): Unified Backend interface for executing prompts through Claude Code or Codex
Daemon (internal/daemon/): Auto-detects CLI tools, registers runtimes, polls for tasks
Database: PostgreSQL 17 with pgvector, sqlc generates code from SQL in pkg/db/queries/

Frontend Architecture

Internal Packages Pattern

All shared packages export raw .ts/.tsx files (no pre-compilation). The consuming app's bundler compiles them directly, giving zero-config HMR and instant go-to-definition.

Package Boundaries

packages/core/ — zero react-dom, zero localStorage, zero UI libraries. All Zustand stores live here.
packages/ui/ — pure UI components, zero business logic.
packages/views/ — zero next/*, zero react-router-dom. Uses NavigationAdapter for routing.

State Management

TanStack Query owns all server state (issues, users, workspaces)
Zustand owns all client state (UI selections, filters, drafts)
React Context is reserved for cross-cutting platform plumbing (WorkspaceIdProvider, NavigationProvider)

Data Flow

Browser → ApiClient (shared/api) → REST API (Chi handlers) → sqlc queries → PostgreSQL
Browser ← WSClient (shared/api) ← WebSocket ← Hub.Broadcast() ← Handlers/TaskService

Multitenancy

All queries are filtered by workspace_id. Membership checks control access. The X-Workspace-ID header routes requests to the correct workspace.

Billing is provided by services/billing/ — a separate Go service with Stripe-backed prepaid-credit wallets and subscription plans, operated by AACWorkflow. The main backend proxies /api/cloud-billing/* calls to it after authenticating the user. See Billing for details.