Skip to content

Codebase Navigation

Jump to bottom
github-actions[bot] edited this page Oct 13, 2026 · 2 revisions

Canonical source: docs/15-ai-context/codebase-navigation.md — this page is rendered from it on every publish; edit the source.

Codebase Navigation Guide

How to find anything in the ClawAI monorepo. Use this as a map when exploring the codebase.

Monorepo Root Structure

d:/Freelance/Claw/
  apps/                     # All deployable applications (13 backend + 1 frontend)
  packages/                 # Shared npm workspace packages
    shared-types/           # 18+ enums, event payloads, auth types
    shared-constants/       # Exchange name, ports, API prefix, pagination defaults
    shared-rabbitmq/        # RabbitMQModule, RabbitMQService (retry+DLQ), StructuredLogger
    shared-auth/            # AuthGuard, RolesGuard, @Public, @Roles, @CurrentUser decorators
  infra/
    nginx/                  # nginx.conf with 20+ route mappings (port 4000 -> services)
  scripts/
    install.sh              # Automated setup for Linux/macOS
    install.ps1             # Automated setup for Windows
    claw.sh                 # Service management (up/down/status/logs)
  docs/                     # 15 documentation sections
  .env.example              # All environment variables with descriptions
  .env                      # Local environment values (not committed)
  docker-compose.dev.yml    # Full dev environment (~22 containers)
  docker-compose.yml        # Production compose
  package.json              # Root workspace config
  CLAUDE.md                 # Mandatory project rules for AI agents and developers

Backend Service Internal Structure

Every NestJS service follows this identical layout:

apps/claw-<service>/
  prisma/                           # Prisma schema and migrations (PG services only)
    schema.prisma
    migrations/
  src/
    main.ts                         # Bootstrap, port binding, Swagger, global pipes/filters
    app/                            # Global NestJS infrastructure
      app.module.ts                 # Root module, imports all feature modules
      decorators/                   # Custom decorators (e.g., @CurrentUser)
      filters/                      # GlobalExceptionFilter, BusinessExceptionFilter
      guards/                       # AuthGuard, RolesGuard
      interceptors/                 # Logging, timing, correlation ID interceptors
      pipes/                        # ZodValidationPipe, custom pipes
    common/                         # Shared within this service
      constants/                    # Service-specific constants
      enums/                        # Service-specific enums
      errors/                       # BusinessException, EntityNotFoundException
      utilities/                    # Wrapped third-party libraries, helper functions
    modules/                        # Feature modules (one per domain entity group)
      <domain>/
        <domain>.module.ts          # NestJS module declaration
        <domain>.controller.ts      # HTTP endpoints (3-line methods)
        <domain>.service.ts         # Business logic (max 30 lines/method)
        <domain>.repository.ts      # Data access (Prisma/Mongoose, no throws)
        <domain>.manager.ts         # Complex orchestration (if needed, max 80 lines/method)
        dto/                        # Zod schemas + inferred types for request validation
        types/                      # TypeScript types/interfaces for this domain
        constants/                  # Domain-specific constants
      health/                       # Health check endpoint (every service has one)
    infrastructure/                 # External integrations config
      prisma/                       # PrismaModule, PrismaService
      rabbitmq/                     # RabbitMQ consumer setup, event handlers
      mongoose/                     # Mongoose schemas (MongoDB services only)
    generated/                      # Prisma client output (auto-generated, do not edit)
    __tests__/                      # Test files
      <domain>/
        <name>.spec.ts
  package.json
  tsconfig.json
  tsconfig.build.json
  nest-cli.json
  eslint.config.mjs

Service-Specific Variations

Service Notable Extras
chat chat-messages/managers/ (ChatExecutionManager, ContextAssemblyManager)
connector common/utilities/ (AES-256-GCM encryption utility)
routing routing/managers/ (routing decision engine, Ollama router integration)
memory memory/managers/ (extraction manager, pgvector queries)
ollama ollama/managers/ (model pull manager, generation manager)
audit infrastructure/mongoose/ (Mongoose schemas for audit logs, usage ledger)
client-logs infrastructure/mongoose/ (Mongoose schemas for client logs)
server-logs infrastructure/mongoose/ (Mongoose schemas for server logs)

Frontend Internal Structure

apps/claw-frontend/
  src/
    app/                            # Next.js App Router pages and layouts
      (authenticated)/              # Protected routes (require JWT)
        chat/
          page.tsx                  # Chat list page
          [threadId]/
            page.tsx                # Individual chat thread page
        connectors/
        models/
        routing/
        memory/
        context/
        files/
        observability/
        audits/
        logs/
        admin/
        settings/
        dashboard/
          page.tsx
      (public)/                     # Public routes
        login/
          page.tsx
      layout.tsx                    # Root layout (providers, theme, i18n)
      globals.css                   # CSS variables, Tailwind base styles
    components/                     # Reusable UI components
      ui/                           # shadcn/ui primitives (auto-generated, do NOT edit)
      layout/                       # Sidebar, header, navigation
      chat/                         # Chat-specific components (MessageBubble, Composer, etc.)
      connectors/                   # Connector management components
      shared/                       # Cross-cutting components (loading, error, empty states)
    hooks/                          # Custom React hooks (one file per hook)
      chat/                         # use-send-message.ts, use-thread-detail.ts, etc.
      auth/                         # use-auth.ts, use-login.ts
      connectors/                   # use-connectors.ts, use-connector-detail.ts
      <domain>/                     # Grouped by domain
    repositories/                   # API layer (HTTP calls)
      chat/
        chat.repository.ts          # Chat API methods (fetch threads, send message, etc.)
      auth/
        auth.repository.ts
      shared/
        query-keys.ts               # TanStack Query key factories
      <domain>/
        <domain>.repository.ts
    services/                       # Business logic that doesn't fit hooks or repositories
    types/                          # TypeScript type definitions
      chat.types.ts                 # Chat domain types
      auth.types.ts                 # Auth domain types
      component.types.ts            # Shared component prop types
      i18n.types.ts                 # Type-safe i18n keys
      <domain>.types.ts
    enums/                          # Frontend enums
      <name>.enum.ts
    constants/                      # Frontend constants
      <name>.constants.ts
    utilities/                      # Utility functions
      <name>.utility.ts
    stores/                         # Zustand stores (minimal client-only state)
      auth.store.ts                 # Auth state (token, user)
      sidebar.store.ts              # Sidebar open/closed
      <name>.store.ts
    lib/                            # Third-party library configuration
      i18n/
        locales/                    # 9 locale files
          en.ts                     # English (source of truth)
          ar.ts                     # Arabic (RTL)
          de.ts                     # German
          es.ts                     # Spanish
          fr.ts                     # French
          it.ts                     # Italian
          pt.ts                     # Portuguese
          ru.ts                     # Russian
        index.ts                    # i18n setup and hook export
      validation/                   # Zod schemas for frontend forms
        <name>.schema.ts
      utils.ts                      # cn() utility for Tailwind class merging
    middleware.ts                    # Next.js middleware (auth redirect, locale detection)
  public/                           # Static assets
  package.json
  next.config.ts
  tailwind.config.ts
  tsconfig.json
  eslint.config.mjs
  vitest.config.ts

Where to Find Things

Backend

Looking for... Location
HTTP endpoints apps/claw-<service>/src/modules/<domain>/<domain>.controller.ts
Business logic apps/claw-<service>/src/modules/<domain>/<domain>.service.ts
Complex orchestration apps/claw-<service>/src/modules/<domain>/<domain>.manager.ts or managers/
Database queries apps/claw-<service>/src/modules/<domain>/<domain>.repository.ts
Request validation apps/claw-<service>/src/modules/<domain>/dto/<name>.dto.ts
Domain types apps/claw-<service>/src/modules/<domain>/types/<name>.types.ts
Service enums apps/claw-<service>/src/common/enums/<name>.enum.ts
Service constants apps/claw-<service>/src/common/constants/<name>.constants.ts
Error classes apps/claw-<service>/src/common/errors/
Utility wrappers apps/claw-<service>/src/common/utilities/<name>.utility.ts
Database schema apps/claw-<service>/prisma/schema.prisma
RabbitMQ consumers apps/claw-<service>/src/infrastructure/rabbitmq/
Tests apps/claw-<service>/src/__tests__/<domain>/
Global filters/guards apps/claw-<service>/src/app/filters/ and apps/claw-<service>/src/app/guards/
Service bootstrap apps/claw-<service>/src/main.ts
Module registration apps/claw-<service>/src/app/app.module.ts

Frontend

Looking for... Location
Page components apps/claw-frontend/src/app/(authenticated)/<route>/page.tsx
UI components apps/claw-frontend/src/components/<domain>/
shadcn/ui primitives apps/claw-frontend/src/components/ui/ (do not edit)
Custom hooks apps/claw-frontend/src/hooks/<domain>/use-<name>.ts
API calls apps/claw-frontend/src/repositories/<domain>/<domain>.repository.ts
Query keys apps/claw-frontend/src/repositories/shared/query-keys.ts
Type definitions apps/claw-frontend/src/types/<domain>.types.ts
Enums apps/claw-frontend/src/enums/<name>.enum.ts
Constants apps/claw-frontend/src/constants/<name>.constants.ts
Utilities apps/claw-frontend/src/utilities/<name>.utility.ts
Zustand stores apps/claw-frontend/src/stores/<name>.store.ts
i18n translations apps/claw-frontend/src/lib/i18n/locales/<lang>.ts
Form validation apps/claw-frontend/src/lib/validation/<name>.schema.ts
Tailwind config apps/claw-frontend/tailwind.config.mts
CSS variables/theme apps/claw-frontend/src/app/globals.css

Shared Packages

Looking for... Location
Shared enums packages/shared-types/src/enums/
Event payloads packages/shared-types/src/events/
Auth types packages/shared-types/src/types/ (jwt-payload.type.ts, authenticated-request.type.ts)
Port/prefix constants packages/shared-constants/src/
RabbitMQ module packages/shared-rabbitmq/src/rabbitmq.module.ts
RabbitMQ service packages/shared-rabbitmq/src/rabbitmq.service.ts
Structured logger packages/shared-rabbitmq/src/structured-logger.ts
Auth guards packages/shared-auth/src/auth.guard.ts, roles.guard.ts, session-revocation.guard.ts
Auth decorators packages/shared-auth/src/decorators.ts

Infrastructure

Looking for... Location
Nginx route mappings infra/nginx/nginx.conf
Docker services docker/docker-compose.{dev,prod}.{databases,services,ollama}.yml, driven by ./scripts/claw.sh
Environment variables .env.example (root)
Setup scripts scripts/install.sh, scripts/install.ps1
Management script scripts/claw.sh

Naming Conventions

Files

Type Pattern Example
Controller <domain>.controller.ts chat-threads.controller.ts
Service <domain>.service.ts chat-threads.service.ts
Repository <domain>.repository.ts chat-threads.repository.ts
Manager <domain>.manager.ts chat-execution.manager.ts
DTO <action>-<domain>.dto.ts create-thread.dto.ts
Types <domain>.types.ts chat-thread.types.ts
Enum <name>.enum.ts routing-mode.enum.ts
Constants <name>.constants.ts token-limits.constants.ts
Utility <name>.utility.ts encryption.utility.ts
Hook use-<name>.ts use-send-message.ts
Store <name>.store.ts auth.store.ts
Test <name>.spec.ts chat-threads.service.spec.ts
Component PascalCase.tsx or kebab-case.tsx MessageBubble.tsx

Classes and Functions

Type Convention Example
NestJS class PascalCase + suffix ChatThreadsService, ChatThreadsController
Manager class PascalCase + Manager ChatExecutionManager
Repository class PascalCase + Repository ChatThreadsRepository
React component PascalCase MessageBubble, ThreadSettings
Hook camelCase with use prefix useSendMessage, useThreadDetail
Utility function camelCase encryptValue, formatTokenCount
Constants SCREAMING_SNAKE_CASE MAX_TOKEN_LIMIT, DEFAULT_TEMPERATURE
Enums PascalCase (name + values) RoutingMode.AUTO, UserRole.ADMIN

Directories

  • Backend modules: kebab-case (e.g., chat-messages, chat-threads)
  • Frontend folders: kebab-case (e.g., hooks/chat/, repositories/auth/)
  • Next.js routes: kebab-case (e.g., (authenticated)/chat/[threadId]/)

Import Patterns

Backend Imports

// 1. Node built-ins (with node: protocol)
import { randomBytes } from 'node:crypto';

// 2. NestJS/third-party frameworks
import { Injectable, Logger } from '@nestjs/common';

// 3. Shared packages (workspace imports)
import { RabbitMQService } from '@claw/shared-rabbitmq';
import { UserRole } from '@claw/shared-types';

// 4. Local imports (relative paths)
import { ChatThreadsRepository } from './chat-threads.repository';
import type { CreateThreadInput } from './dto/create-thread.dto';
import type { ThreadWithMessages } from './types/chat-thread.types';

Frontend Imports

// 1. React/Next.js
import { useState, useCallback } from 'react';
import { useRouter } from 'next/navigation';

// 2. Third-party libraries
import { useQuery, useMutation } from '@tanstack/react-query';

// 3. Internal aliases (@/ maps to src/)
import { Button } from '@/components/ui/button';
import { useTranslation } from '@/lib/i18n';
import { chatRepository } from '@/repositories/chat/chat.repository';
import type { ChatThread } from '@/types/chat.types';
import { RoutingMode } from '@/enums/routing-mode.enum';
import { MAX_MESSAGE_LENGTH } from '@/constants/chat.constants';

Key Rules

  • Always use import type { ... } for type-only imports
  • Group imports: built-in > external > internal > relative
  • Alphabetize within groups
  • Never import third-party libraries directly in services/components -- use utility wrappers
  • Backend shared packages use @claw/ scope
  • Frontend uses @/ alias for src/

ClawAI Wiki · source-controlled under wiki/ · generated/mirrored from the current repository knowledge layer.

ClawAI Wiki

Product

Architecture

Platform

Runtime & Ops

Quality

Engineering OS

Agents

Reference

Clone this wiki locally