Monorepo Structure

Directory Layout

hn-monorepo/
├── apps/
│   ├── archus/            # Agent management dashboard (OpenClaw)
│   ├── bgs-service/       # Building cleaning service platform
│   ├── calnexus/          # Calendar + AI scheduling app
│   ├── elbe-akustik/      # Hearing aid shop platform
│   ├── lexilink/          # Learning platform (vocab, tests, classes)
│   ├── nexus-lms/         # Learning management system
│   ├── planex/            # Project planning tool (AI-powered)
│   ├── portfolio/         # Portfolio/landing site
│   └── qript/             # Video scripting tool [experimental]
├── packages/              # 21 shared packages (@hn-monorepo/*)
├── k8s/                   # Kubernetes manifests (Kustomize)
│   ├── base/              # Namespace + shared resources
│   ├── apps/              # Per-app deployments, services, ingresses
│   ├── convex/            # Self-hosted Convex backends
│   ├── overlays/          # Environment overrides (staging, preview)
│   ├── rbac/              # Role-based access control
│   └── secrets/           # K8s secret definitions
├── docs/                  # Documentation (Mintlify)
├── scripts/               # Utility scripts (op-dev.sh, generate-env-op.sh)
└── turbo.json             # Turborepo pipeline configuration

Top-Level Directories

apps/

Each subdirectory is an independently deployable Next.js application. Apps can import shared packages via @hn-monorepo/* but must not import from other apps.

packages/

Shared code organized by domain. Packages depend on other packages, never on apps. All packages use the @hn-monorepo/{name} naming convention and are auto-discovered via Bun workspaces.

k8s/

Kubernetes manifests using Kustomize. Contains base resources, per-app deployment definitions, environment overlays (staging, preview), RBAC policies, and secret definitions.

docs/

Project documentation powered by Mintlify. Includes architecture decision records, deployment guides, and app-specific documentation.

Turborepo Build Graph

Turborepo manages the build pipeline defined in turbo.json. It:

• Analyzes dependency relationships between apps and packages
• Runs tasks in the correct order based on the dependency graph
• Caches build outputs to skip unchanged work
• Parallelizes independent tasks

Key pipeline tasks:

Task	Description
build	Build all apps and packages
dev	Start all apps in development mode
lint	Run Biome linting
format	Run Biome formatting
typecheck	Run TypeScript type checking
test	Run Vitest unit tests
test:e2e	Run Playwright E2E tests

Workspace Dependencies

Internal packages use the workspace:* protocol in package.json:

{
  "dependencies": {
    "@hn-monorepo/ui": "workspace:*",
    "@hn-monorepo/auth": "workspace:*",
    "@hn-monorepo/config": "workspace:*"
  }
}

This tells Bun to resolve the dependency from the local workspace rather than the npm registry. Changes to a package are immediately available to all consuming apps without publishing.