Knowledge Vault

Polyglot Monorepo Architecture

2 min read

Polyglot Monorepo Architecture

Overview

A multi-project monorepo pattern housing several independent but related projects across multiple languages (TypeScript, Go, Rust). Demonstrates layered architecture with daemon-client communication, event-driven state management via EventBus, and repository pattern for persistence abstraction.

Structure

The architecture contains autonomous projects sharing a workspace:

  • HumanLayer — Human-in-the-loop AI agent approval system (Turbo monorepo)
  • github.gg — GitHub code analysis platform (Next.js)
  • OpenSpec — Spec management CLI tool
  • RepoMirror — Repository mirroring tool

Key characteristics: CLI-first design for tooling, language polyglot (TypeScript, Go, Rust), event-driven real-time capabilities.

Layered Architecture (HumanLayer Example)

Daemon Layer (Go)

Central orchestration service: session management, approval handling, RPC server. Entry point: hld/cmd/hld/main.go. Depends on SQLite store, Claude Code wrapper.

CLI Layer (TypeScript)

User interface for daemon interaction: command handlers, MCP server, daemon client. Communicates via JSON-RPC over Unix socket.

UI Layer (React/Tauri)

Desktop application for session management. Uses Zustand stores and communicates with daemon via HTTP API.

Service Layer (Go)

Core business logic: SessionManager (launch, continue, interrupt, terminate), ApprovalManager, EventBus (pub/sub for session state changes). Interface-based with concrete implementations.

Data Layer (Go)

Persistence abstraction via ConversationStore interface with SQLite implementation. Repository pattern.

Key Abstractions

  • SessionManager — Lifecycle management for AI coding sessions (Launch, Continue, Interrupt, Terminate)
  • ConversationStore — Data persistence abstraction (Repository pattern with SQLite)
  • EventBus — Pub/sub with session-scoped channels (Observer pattern)
  • tRPC Router — Type-safe API layer (Procedure-based RPC)

Data Flow

User Action (CLI/WUI) → Daemon Client → HLD Daemon
  ├─ SessionManager
  ├─ ApprovalManager
  └─ EventBus → SSE/WebSocket → UI

State management: Zustand stores in WUI, SQLite in daemon, EventBus for real-time state synchronization.

Cross-Cutting Concerns

  • Logging: Go slog (structured), TypeScript console + Sentry
  • Validation: Zod schemas at API boundaries, Go struct validation
  • Error handling: Exception bubbling with boundary handlers, error codes via RPC

See Also

Graph View

Backlinks