Backend Services Index

Canonical source: docs/04-backend/services-index.md — this page is rendered from it on every publish; edit the source.

Backend Services Index

Reference for ClawAI NestJS backend services; newer services are appended as they ship.

Rules every backend service shares (commands, absolute rules, Docker rebuild, checklists): backend-service-baseline.md. Each service's CLAUDE.md adds only what is specific to it.

---

Quick Reference Table

#	Service	App Name	Port	Database	Primary Purpose
1	Auth	claw-auth-service	4001	PostgreSQL (claw_auth)	Authentication, user management, sessions, RBAC
2	Chat	claw-chat-service	4002	PostgreSQL (claw_chat)	Threads, messages, context assembly, AI execution
3	Connector	claw-connector-service	4003	PostgreSQL (claw_connectors)	Cloud AI provider management, model sync, health
4	Routing	claw-routing-service	4004	PostgreSQL (claw_routing)	Intelligent model routing, policies, decisions
5	Memory	claw-memory-service	4005	PostgreSQL (claw_memory, pgvector)	Memory CRUD, extraction, context packs
6	File	claw-file-service	4006	PostgreSQL (claw_files)	File upload, storage, chunking, download
7	Audit	claw-audit-service	4007	MongoDB (claw_audit)	Audit trail, usage ledger, cost/latency analytics
8	Ollama	claw-ollama-service	4008	PostgreSQL (claw_ollama)	Local model management, pull, generate, roles
9	Health	claw-health-service	4009	None	Aggregated health checks across downstream services
10	Client Logs	claw-client-logs-service	4010	MongoDB (claw_client_logs)	Frontend log ingestion, search, stats (TTL 30d)
11	Server Logs	claw-server-logs-service	4011	MongoDB (claw_server_logs)	Backend structured logs, search, stats (TTL 30d)
12	Image	claw-image-service	4012	PostgreSQL (claw_images)	Image generation orchestration (DALL-E, Gemini, SD)
13	File Generation	claw-file-generation-service	4013	PostgreSQL (claw_file_generations)	File format conversion (PDF, DOCX, CSV, HTML, etc.)
14	Workspace	claw-workspace-service	4014	PostgreSQL (claw_workspace)	Workspace connectors, sync, search, objects, actions
15	Agent	claw-agent-service	4015	PostgreSQL (claw_agent)	Desktop agent sessions, terminal approval, repos, FS events
16	Research	claw-research-service	4016	PostgreSQL	Search, fetch, and research evidence
17	llama.cpp	claw-llamacpp-service	4017	PostgreSQL	Local llama.cpp runtime
18	Payment	claw-payment-service	4018	PostgreSQL	Checkout, subscriptions, invoices, refunds
19	Threads	claw-threads-service	4019	PostgreSQL (claw_threads)	Owner generation handoff and private publication revisions
20	Thread Generation	claw-thread-generation-service	4020	PostgreSQL (claw_thread_generation)	Durable isolated generation jobs and review pipeline
21	Plugin	claw-plugin-service	4021	PostgreSQL (claw_plugin)	Plugin and MCP catalog, installs, consent

---

Service Details

1. Auth Service

Port: 4001 | Database: PostgreSQL (claw_auth) | ORM: Prisma

Authentication, authorization, user management, and session lifecycle management. Issues JWT access tokens and manages refresh token rotation with argon2 password hashing.

Controllers:

Controller	Route Prefix	Description
AuthController	/api/v1/auth	Login, refresh, logout, profile
UsersController	/api/v1/users	User CRUD, role management, preferences
HealthController	/api/v1/health	Service health check

Key Routes:

• POST /auth/login -- Authenticate user (public)
• POST /auth/refresh -- Refresh JWT token (public)
• POST /auth/logout -- End session (authenticated)
• GET /auth/me -- Get current user profile (authenticated)
• POST /users -- Create user (ADMIN only)
• GET /users -- List users with pagination (ADMIN only)
• GET /users/:id -- Get user by ID (ADMIN only)
• PATCH /users/:id -- Update user (ADMIN only)
• DELETE /users/:id -- Deactivate user (ADMIN only)
• PATCH /users/:id/reactivate -- Reactivate user (ADMIN only)
• PATCH /users/:id/role -- Change user role (ADMIN only)
• PATCH /users/me/preferences -- Update own preferences (authenticated)
• PATCH /users/me/password -- Change own password (authenticated)

Key Services: AuthService, UsersService, SessionService

Database Tables:

• User -- email, username, passwordHash, role, status, preferences
• Session -- userId, refreshToken, expiresAt
• SystemSetting -- key/value store

Events Published:

• user.created -- When a new user is created
• user.login -- When a user successfully logs in
• user.logout -- When a user logs out
• user.role_changed -- When a user's role is updated
• user.deactivated -- When a user is deactivated

Events Consumed: None

Inter-Service Dependencies: None (foundational service)

Health Endpoint: GET /api/v1/health

---

2. Chat Service

Port: 4002 | Database: PostgreSQL (claw_chat) | ORM: Prisma

Core chat functionality. Manages threads and messages, assembles context (memories, files, context packs), executes AI completions through cloud providers and Ollama, and streams responses via SSE.

Controllers:

Controller	Route Prefix	Description
ChatMessagesController	/api/v1/chat-messages	Create, list, get, regenerate, feedback
ChatStreamController	/api/v1/chat-messages	SSE streaming for thread updates
ChatThreadsController	/api/v1/chat-threads	Thread CRUD
HealthController	/api/v1/health	Service health check

Key Routes:

• POST /chat-messages -- Send a message (triggers routing + AI execution)
• GET /chat-messages/thread/:threadId -- List messages in thread (paginated)
• GET /chat-messages/:id -- Get single message
• POST /chat-messages/:id/regenerate -- Regenerate AI response
• PATCH /chat-messages/:id/feedback -- Set thumbs up/down feedback
• SSE /chat-messages/stream/:threadId -- Real-time message stream (skip throttle)
• POST /chat-threads -- Create new thread
• GET /chat-threads -- List user's threads (paginated)
• GET /chat-threads/:id -- Get thread details
• PATCH /chat-threads/:id -- Update thread settings
• DELETE /chat-threads/:id -- Delete thread

Key Services: ChatMessagesService, ChatThreadsService, ChatStreamService, ContextAssemblyManager, ChatExecutionManager

Database Tables:

• ChatThread -- userId, title, routingMode, preferredProvider/Model, contextPackIds, systemPrompt, temperature, maxTokens
• ChatMessage -- threadId, role, content, provider, model, routingMode, inputTokens, outputTokens, latencyMs, feedback, metadata
• MessageAttachment -- messageId, fileId, type

Events Published:

• message.created -- When user sends a message
• message.completed -- When AI response is stored

Events Consumed:

• message.routed -- Receives routing decision from routing service

Inter-Service Dependencies:

• Routing Service -- via RabbitMQ (message.created -> message.routed)
• Memory Service -- HTTP (/internal/memories/for-context)
• Memory Service -- HTTP (/internal/context-packs/:id/items)
• Workspace Service -- HTTP (/internal/workspace/search)
• File Service -- HTTP (/internal/files/:id/chunks, /internal/files/:id/content)
• Connector Service -- HTTP (/internal/connectors/config)
• Ollama Service -- HTTP (/internal/ollama/router-model)
• Image Service -- HTTP (/internal/images/generate)
• File Generation Service -- HTTP (/internal/file-generations/generate)

Health Endpoint: GET /api/v1/health

---

3. Connector Service

Port: 4003 | Database: PostgreSQL (claw_connectors) | ORM: Prisma

Manages cloud AI provider connectors (OpenAI, Anthropic, Google, DeepSeek, xAI). Handles encrypted API key storage (AES-256-GCM), model discovery/sync, and health monitoring.

Controllers:

Controller	Route Prefix	Description
ConnectorsController	/api/v1/connectors	CRUD, test, sync, list models
ConnectorsInternalController	/api/v1/internal/connectors	Inter-service connector config
HealthController	/api/v1/health	Service health check

Key Routes:

• POST /connectors -- Create new connector
• GET /connectors -- List connectors (paginated)
• GET /connectors/:id -- Get connector with models
• PATCH /connectors/:id -- Update connector
• DELETE /connectors/:id -- Delete connector
• POST /connectors/:id/test -- Test connector connectivity
• POST /connectors/:id/sync -- Sync available models
• GET /connectors/:id/models -- List connector's models
• GET /internal/connectors/config?provider=X -- Get connector config (internal, public)

Key Services: ConnectorsService, ModelSyncManager, HealthCheckManager

Database Tables:

• Connector -- name, provider, status, encryptedConfig (AES-256-GCM), baseUrl
• ConnectorModel -- modelKey, displayName, lifecycle, capability flags
• ConnectorHealthEvent -- health check history
• ModelSyncRun -- sync run history

Events Published:

• connector.created -- When a connector is created
• connector.updated -- When a connector is updated
• connector.deleted -- When a connector is deleted
• connector.synced -- When models are synced
• connector.health_checked -- When health check completes

Events Consumed: None

Inter-Service Dependencies: None (consumed by chat and routing)

Health Endpoint: GET /api/v1/health

---

4. Routing Service

Port: 4004 | Database: PostgreSQL (claw_routing) | ORM: Prisma

Intelligent AI model routing across 7 modes. Uses Ollama-assisted AUTO mode with Zod-validated structured output, heuristic fallback, and configurable policies.

Controllers:

Controller	Route Prefix	Description
RoutingController	/api/v1/routing	Policies CRUD, evaluate, decisions
HealthController	/api/v1/health	Service health check

Key Routes:

• POST /routing/policies -- Create routing policy
• GET /routing/policies -- List policies (paginated)
• GET /routing/policies/:id -- Get policy
• PATCH /routing/policies/:id -- Update policy
• DELETE /routing/policies/:id -- Delete policy
• POST /routing/evaluate -- Evaluate route for a message
• GET /routing/decisions/:threadId -- Get routing decisions for thread (paginated)

Key Services: RoutingService, RoutingManager

Database Tables:

• RoutingDecision -- selectedProvider/Model, confidence, reasonTags, privacyClass, costClass, fallback
• RoutingPolicy -- name, routingMode, priority, config (JSON), isActive

Events Published:

• message.routed -- When routing decision is made
• routing.decision_made -- For audit trail

Events Consumed:

• message.created -- Triggers routing evaluation
• connector.synced -- Updates available model cache
• connector.health_checked -- Updates provider health status

Inter-Service Dependencies:

• Ollama Service -- HTTP (for AUTO mode router model)
• Connector Service -- HTTP (for available providers/models)

Health Endpoint: GET /api/v1/health

---

5. Memory Service

Port: 4005 | Database: PostgreSQL (claw_memory, pgvector) | ORM: Prisma

Manages user memories (facts, preferences, instructions, summaries) and context packs. Supports automatic extraction from completed messages via Ollama. Uses pgvector for semantic similarity search.

Controllers:

Controller	Route Prefix	Description
MemoryController	/api/v1/memories	Memory CRUD + toggle
ContextPacksController	/api/v1/context-packs	Context pack CRUD + items
MemoryInternalController	/api/v1/internal/memories	Inter-service memory fetch
ContextPacksInternalController	/api/v1/internal/context-packs	Inter-service pack items
HealthController	/api/v1/health	Service health check

Key Routes:

• POST /memories -- Create memory record
• GET /memories -- List memories (paginated, filtered)
• GET /memories/:id -- Get memory
• PATCH /memories/:id -- Update memory
• DELETE /memories/:id -- Delete memory
• PATCH /memories/:id/toggle -- Enable/disable memory
• POST /context-packs -- Create context pack
• GET /context-packs -- List context packs
• GET /context-packs/:id -- Get pack with items
• PATCH /context-packs/:id -- Update pack
• DELETE /context-packs/:id -- Delete pack
• POST /context-packs/:id/items -- Add item to pack
• DELETE /context-packs/:id/items/:itemId -- Remove item from pack
• GET /internal/memories/for-context?userId=X&limit=N -- Get memories for context assembly (internal, public)
• GET /internal/context-packs/:id/items -- Get pack items (internal, public)

Key Services: MemoryService, ContextPacksService, MemoryExtractionManager

Database Tables:

• MemoryRecord -- userId, type, content, sourceThreadId/MessageId, isEnabled
• ContextPack -- name, description, scope
• ContextPackItem -- type, content, fileId, sortOrder

Events Published:

• memory.extracted -- When memory is auto-extracted from a message

Events Consumed:

• message.completed -- Triggers memory extraction

Inter-Service Dependencies:

• Ollama Service -- HTTP (for memory extraction model)

Health Endpoint: GET /api/v1/health

---

6. File Service

Port: 4006 | Database: PostgreSQL (claw_files) | ORM: Prisma

File upload, storage, chunking (JSON, CSV, Markdown, text), and download. Supports base64 file content with automatic chunking for AI context assembly.

Controllers:

Controller	Route Prefix	Description
FilesController	/api/v1/files	Upload, list, get, delete, download, chunks
FilesInternalController	/api/v1/internal/files	Inter-service file access
HealthController	/api/v1/health	Service health check

Key Routes:

• POST /files/upload -- Upload file (base64 content)
• GET /files -- List user's files (paginated)
• GET /files/:id -- Get file metadata
• DELETE /files/:id -- Delete file
• GET /files/download/:id -- Download file content
• GET /files/:id/chunks -- Get file chunks
• GET /internal/files/:id/chunks -- Get chunks (internal, public)
• GET /internal/files/:id/content -- Get file content (internal, public)
• GET /internal/files/download/:id -- Download file (internal, public)
• POST /internal/files/store-image -- Store generated image (internal, public)

Key Services: FilesService, FileChunkingManager

Database Tables:

• File -- userId, filename, mimeType, sizeBytes, storagePath, ingestionStatus, content
• FileChunk -- fileId, chunkIndex, content

Events Published:

• file.uploaded -- When a file is uploaded
• file.chunked -- When chunking completes

Events Consumed: None

Inter-Service Dependencies: None (consumed by chat)

Health Endpoint: GET /api/v1/health

---

7. Audit Service

Port: 4007 | Database: MongoDB (claw_audit) | ODM: Mongoose

Audit trail and usage ledger. Records 11 audit actions across all services. Provides usage summary, cost analysis, and latency analytics.

Controllers:

Controller	Route Prefix	Description
AuditsController	/api/v1/	Audit logs + usage analytics
HealthController	/api/v1/health	Service health check

Key Routes:

• GET /audits -- List audit logs (paginated, filtered by action/severity/entity/date)
• GET /audits/stats -- Aggregated audit statistics
• GET /usage -- List usage entries (paginated, filtered by provider/model/date)
• GET /usage/summary -- Usage summary (token counts, request counts)
• GET /usage/cost -- Cost summary by provider/model
• GET /usage/latency -- Latency summary by provider/model

Key Services: AuditsService, UsageService, AuditEventHandler

Database Collections:

• audit_logs -- userId, action, entityType, entityId, severity, details
• usage_ledger -- resourceType, action, quantity, unit, metadata

Events Published: None

Events Consumed:

• user.login / user.logout -- Record auth events
• connector.created / connector.updated / connector.deleted -- Record connector changes
• connector.synced -- Record sync events
• routing.decision_made -- Record routing decisions
• message.completed -- Record usage (tokens, latency)
• memory.extracted -- Record extraction events

Inter-Service Dependencies: None (event consumer only)

Health Endpoint: GET /api/v1/health

---

8. Ollama Service

Port: 4008 | Database: PostgreSQL (claw_ollama) | ORM: Prisma

Manages the local Ollama AI runtime and the dynamic model discovery pipeline. Handles model pulling, role assignment, text generation, health monitoring, and a scheduled cron job that periodically discovers new Ollama models, classifies them into 17 technical + 15 business categories, and queues admin-review candidates. See docs/07-integrations/model-discovery-pipeline.md for the full design.

Controllers:

Controller	Route Prefix	Description
OllamaController	/api/v1/ollama	Models, pull, assign-role, generate, health, runtimes
OllamaDiscoveryController	/api/v1/ollama	Discovery sources, runs, candidates, bulk approve, admin catalog CRUD, hw packs
OllamaInternalController	/api/v1/internal/ollama	Inter-service router model lookup
HealthController	/api/v1/health	Service health check

Key Routes:

• GET /ollama/models -- List local models (paginated)
• POST /ollama/pull -- Pull a model from Ollama registry
• POST /ollama/assign-role -- Assign role to a model
• POST /ollama/generate -- Generate text completion (public)
• GET /ollama/health?runtime=X -- Check Ollama runtime health (public)
• GET /ollama/runtimes -- List configured runtimes
• GET /internal/ollama/router-model -- Get current router model name (internal, public)
• GET|POST|PUT|DELETE /ollama/discovery/sources[/:id] -- Manage discovery sources (admin)
• POST /ollama/discovery/refresh -- Trigger discovery run (optional dryRun flag)
• GET /ollama/discovery/runs[/:id] -- List or inspect discovery runs
• GET /ollama/discovery/candidates -- List candidates with status + search filters
• POST /ollama/discovery/candidates/:id/approve|reject -- Per-candidate actions (admin)
• POST /ollama/discovery/candidates/bulk-approve -- Bulk approve array of IDs (admin)
• POST|PUT|DELETE /ollama/catalog/admin[/:id] -- Direct catalog entry CRUD (admin)
• GET /ollama/packs -- List hardware packs (CPU, 8/12/16/24/48GB+)
• POST /ollama/packs/:profile/install -- Bulk pull pack (admin)

Key Services: OllamaService, CatalogSeedService, CatalogRemoteMetadataService, CatalogSyncService (scheduled cron), DiscoverySourceService, DiscoveryJobService, HardwarePackService

Key Managers: OllamaManager, DiscoveryManager, OllamaLibraryDiscoveryManager, ModelEnrichmentManager, CandidateImportManager

Database Tables:

• LocalModel -- name, tag, runtime, family, parameters, sizeBytes
• LocalModelRoleAssignment -- modelId, role, isActive
• PullJob -- model pull progress tracking
• RuntimeConfig -- runtime configuration
• ModelCatalogEntry -- name, tag, displayName, category, businessCategories, hardwareProfiles, isDiscovered, downloadStatus
• DiscoverySource -- admin-managed crawler configuration
• ModelDiscoveryRun -- one execution across enabled sources
• ModelDiscoveryCandidate -- discovered model awaiting review (PENDING / IMPORTED / REJECTED / DUPLICATE)

Events Published: None (generates on request)

Events Consumed: None

Scheduled Jobs:

• CatalogSyncService.scheduledRefresh() — daily at 3:00 AM when DISCOVERY_AUTO_REFRESH_ENABLED=true

Inter-Service Dependencies:

• Ollama Runtime -- HTTP (OLLAMA_BASE_URL, default port 11434)
• Ollama Library/Registry (public) -- HTTP for discovery crawl

Health Endpoint: GET /api/v1/health

---

9. Health Service

Port: 4009 | Database: None

Lightweight aggregation service. Queries health endpoints of all other services and returns a consolidated status report.

Controllers:

Controller	Route Prefix	Description
HealthController	/api/v1/health	Aggregated health check

Key Routes:

• GET /health -- Aggregated health status of all services

Key Services: HealthService

Database Tables: None

Events Published:

• health.check -- Periodic health check results

Events Consumed: None

Inter-Service Dependencies: All other services (HTTP health endpoints)

Health Endpoint: GET /api/v1/health (this IS the health endpoint)

---

10. Client Logs Service

Port: 4010 | Database: MongoDB (claw_client_logs) | ODM: Mongoose

Ingests frontend/browser logs. Supports batched ingestion, search, and statistics. Documents auto-expire after 30 days (TTL index).

Controllers:

Controller	Route Prefix	Description
ClientLogsController	/api/v1/client-logs	Create, search, stats
HealthController	/api/v1/health	Service health check

Key Routes:

• POST /client-logs -- Create client log entry (public, no auth required)
• GET /client-logs -- Search/list client logs (ADMIN, OPERATOR)
• GET /client-logs/stats -- Log statistics (ADMIN, OPERATOR)

Key Services: ClientLogsService

Database Collections:

• client_logs -- level, message, component, action, userId, route, userAgent (TTL 30d)

Events Published: None

Events Consumed: None

Inter-Service Dependencies: None

Health Endpoint: GET /api/v1/health

---

11. Server Logs Service

Port: 4011 | Database: MongoDB (claw_server_logs) | ODM: Mongoose

Ingests structured backend logs from all services via RabbitMQ and HTTP. Supports rich filtering (service, module, controller, action, request/trace IDs) and statistics. TTL 30 days.

Controllers:

Controller	Route Prefix	Description
ServerLogsController	/api/v1/server-logs	Create, batch create, search, stats
HealthController	/api/v1/health	Service health check

Key Routes:

• POST /server-logs -- Create single log entry (public)
• POST /server-logs/batch -- Create batch of log entries (public)
• GET /server-logs -- Search/list server logs (authenticated, filtered)
• GET /server-logs/stats -- Log statistics

Key Services: ServerLogsService, ServerLogEventHandler

Database Collections:

• server_logs -- level, serviceName, module, action, requestId, traceId, userId, threadId, provider, model, latencyMs, error fields (TTL 30d)

Events Published: None

Events Consumed:

• log.server -- Receives structured log events from all services via RabbitMQ

Inter-Service Dependencies: None (event consumer only)

Health Endpoint: GET /api/v1/health

---

12. Image Service

Port: 4012 | Database: PostgreSQL (claw_images) | ORM: Prisma

Orchestrates image generation across cloud providers (OpenAI DALL-E 3, Google Gemini Imagen) and local Stable Diffusion. Supports async generation with SSE progress events, retry with alternate models.

Controllers:

Controller	Route Prefix	Description
ImageGenerationController	/api/v1/images	List, get, retry, retry-alternate, SSE events
InternalImageController	/api/v1/internal/images	Inter-service generation trigger
HealthController	/api/v1/health	Service health check

Key Routes:

• GET /images -- List user's image generations (paginated)
• GET /images/:id -- Get image generation by ID
• POST /images/:id/retry -- Retry failed generation
• POST /images/:id/retry-alternate -- Retry with different provider/model
• SSE /images/:id/events -- Real-time generation progress (public)
• POST /internal/images/generate -- Enqueue image generation (internal, public)
• GET /internal/images/:generationId -- Get generation status (internal, public)
• POST /internal/images/:generationId/retry -- Retry (internal, public)
• POST /internal/images/:generationId/retry-alternate -- Retry alternate (internal, public)
• SSE /internal/images/:generationId/events -- Progress events (internal, public)

Key Services: ImageGenerationService, ImageGenerationEventsService, ImageExecutionManager

Database Tables:

• ImageGeneration -- prompt, provider, model, status, resultUrl, error, userId

Events Published:

• image.generated -- When image generation completes
• image.failed -- When image generation fails

Events Consumed: None

Inter-Service Dependencies:

• Connector Service -- HTTP (for provider API keys)
• File Service -- HTTP (for storing generated images)

Health Endpoint: GET /api/v1/health

---

13. File Generation Service

Port: 4013 | Database: PostgreSQL (claw_file_generations) | ORM: Prisma

Converts LLM-generated text content into downloadable files. Supports 7 output formats: PDF, DOCX, CSV, HTML, Markdown, JSON, and TXT. Async generation with SSE progress events.

Controllers:

Controller	Route Prefix	Description
FileGenerationController	/api/v1/file-generations	List, get, retry, SSE events
InternalFileGenerationController	/api/v1/internal/file-generations	Inter-service generation trigger
HealthController	/api/v1/health	Service health check

Key Routes:

• GET /file-generations -- List user's file generations (paginated)
• GET /file-generations/:id -- Get file generation by ID
• POST /file-generations/:id/retry -- Retry failed generation
• SSE /file-generations/:id/events -- Real-time generation progress (public)
• POST /internal/file-generations/generate -- Enqueue file generation (internal, public)
• GET /internal/file-generations/:generationId -- Get generation status (internal, public)
• POST /internal/file-generations/:generationId/retry -- Retry (internal, public)
• SSE /internal/file-generations/:generationId/events -- Progress events (internal, public)

Key Services: FileGenerationService, FileGenerationEventsService, FileExecutionManager

Database Tables:

• FileGeneration -- content, format, status, resultUrl, error, userId
• FileGenerationAsset -- generated file assets
• FileGenerationEvent -- generation event log

Events Published: None

Events Consumed: None

Inter-Service Dependencies:

• File Service -- HTTP (for storing generated files)

Health Endpoint: GET /api/v1/health

---

14. Workspace Service

Port: 4014 | Database: PostgreSQL (claw_workspace) | ORM: Prisma

External workspace integration layer. Manages provider connectors, OAuth, sync runs, searchable objects, and approval-gated actions. The chat service uses it to ground prompts with workspace citations during context assembly.

Controllers:

Controller	Route Prefix	Description
WorkspaceConnectorController	/api/v1/workspace/connectors	Connector CRUD, health, sync
WorkspaceOAuthController	/api/v1/workspace/oauth	OAuth init and callback
WorkspaceSearchController	/api/v1/workspace/search	User-facing workspace search
WorkspaceObjectController	/api/v1/workspace/objects	Synced object list and detail
WorkspaceActionController	/api/v1/workspace/actions	Action drafts, approve, reject
WorkspaceSearchInternalController	/api/v1/internal/workspace/search	Internal search for chat grounding
HealthController	/api/v1/health	Service health check

Key Routes:

• POST /workspace/connectors -- Create workspace connector
• GET /workspace/connectors -- List connectors
• POST /workspace/connectors/:id/health -- Run connector health check
• POST /workspace/connectors/:id/sync -- Trigger sync
• POST /workspace/oauth/init -- Start OAuth flow
• GET /workspace/oauth/callback -- Complete OAuth callback
• POST /workspace/search -- Search synced objects for current user
• GET /workspace/objects -- List synced objects
• GET /workspace/objects/:id -- Get object detail
• POST /workspace/actions -- Create action draft
• GET /workspace/actions -- List actions
• POST /workspace/actions/:id/approve -- Approve action
• POST /workspace/actions/:id/reject -- Reject action
• POST /internal/workspace/search -- Internal search for chat context assembly

Key Services: WorkspaceConnectorService, WorkspaceSearchService, WorkspaceActionService, WorkspaceOAuthService

Database Tables:

• WorkspaceConnector -- provider, scopes, permissionLevel, token metadata, status
• WorkspaceSyncRun -- sync mode, object type, totals, errors
• WorkspaceHealthEvent -- health check history
• WorkspaceObject -- synced issues, repos, docs, files, comments, channels, tickets
• WorkspaceObjectLink -- graph edges between synced objects
• WorkspaceAction -- action drafts and approval lifecycle

Events Published: None required for the core request path

Events Consumed: None

Inter-Service Dependencies:

• Auth Service -- JWT auth via shared-auth
• Redis -- ephemeral state and OAuth/search helpers

Health Endpoint: GET /api/v1/health

---

15. Agent Service

Port: 4015 | Database: PostgreSQL (claw_agent) | ORM: Prisma

Backend for the local desktop agent runtime. Manages CLI sessions, human-approved command execution, local repository registration, and file-system event ingestion.

Controllers:

Controller	Route Prefix	Description
AgentSessionController	/api/v1/agent/sessions	Session register, list, disconnect, heartbeat
AgentCommandController	/api/v1/agent/commands	Create, list, approve, reject, complete
AgentRepoController	/api/v1/agent/repos	Repo register, list, update, delete
AgentEventController	/api/v1/agent/events	File event reporting and listing
HealthController	/api/v1/health	Service health check

Key Routes:

• POST /agent/sessions -- Register CLI session
• GET /agent/sessions -- List sessions
• GET /agent/sessions/:id -- Get session details
• DELETE /agent/sessions/:id -- Disconnect session
• POST /agent/sessions/:id/heartbeat -- Refresh session heartbeat
• POST /agent/commands -- Create command
• GET /agent/commands -- List commands
• GET /agent/commands/pending -- Agent polls and claims approved commands
• POST /agent/commands/:id/approve -- Approve command
• POST /agent/commands/:id/reject -- Reject command
• POST /agent/commands/:id/complete -- Agent reports completion
• POST /agent/repos -- Register repo
• GET /agent/repos -- List repos
• POST /agent/events -- Report file-system events
• GET /agent/events -- List file-system events

Key Services: AgentSessionService, AgentCommandService, AgentCommandManager, AgentRepoService, AgentEventService

Database Tables:

• AgentSession -- hostname, platform, version, heartbeat, status
• TerminalCommand -- command text, lifecycle state, stdout/stderr, exitCode
• LocalRepo -- repo path, branch, dirty state, metadata
• FileWatchEvent -- created/modified/deleted/renamed activity

Events Published:

• agent.session.connected -- When a local CLI registers
• agent.session.disconnected -- When a session disconnects

Events Consumed: None

Inter-Service Dependencies:

• Auth Service -- JWT auth via shared-auth
• RabbitMQ -- session lifecycle events

Health Endpoint: GET /api/v1/health

---

16. Llamacpp Service

Purpose: Manages frontier open-weight LLMs (Kimi K2.6 1T, GLM-5.1 754B, DeepSeek V3.2/V4) that exceed Ollama's practical envelope. Provides "click to download, click to chat" UX for models in the 70 B – 1.4 T parameter range, gated by hardware preflight.

Codename: Local Frontier · Port: 4017 · Database: PostgreSQL claw_llamacpp (5440) · Volume: llamacpp-data

Modules (7):

• binary — auto-installs llama-server via dynamic GitHub-API resolution (https://api.github.com/repos/ggml-org/llama.cpp/releases/latest); per-platform asset patterns pick the right tar.gz/zip for linux-x64-{cpu,cuda12,rocm,vulkan} / win-x64-{cpu,cuda12,cuda13,vulkan} / darwin-{arm64-metal,x64-cpu}. Self-heals across upstream renames.
• catalog — 12 entries: 3 dev-class (phi-4-mini Q4, qwen3-coder Q4, llama-3.3 IQ2_XS) + 9 frontier-class (Kimi/GLM/DeepSeek variants). Browseable via /api/v1/catalog.
• pull-jobs — multi-shard HuggingFace download with resume from .partial, 5× exponential-backoff retry, per-file SHA-256 verify, SSE progress stream at /pull-jobs/:id/progress.
• models-lifecycle — single-resident model supervisor; async-mutex guards load/unload; spawns llama-server on 127.0.0.1:[48500-48999] random port; OnApplicationBootstrap clears stale READY/LOADING rows.
• inference — @Public OpenAI-compatible proxy at /api/v1/v1/chat/completions (SSE-aware); forwards to spawned llama-server child process.
• hardware — cross-vendor GPU detection (NVIDIA via nvidia-smi, AMD via /dev/kfd + rocm-smi, Intel/Vulkan via /dev/dri/render*); preflight gate refuses pulls when DISK_INSUFFICIENT (non-overridable), warns + allows override on RAM/GPU.
• health — DB + binary + active-model rollup at /api/v1/health.

Cross-service integration:

• Connector service: LLAMACPP enum value + LlamacppAdapter (/managers/adapters/llamacpp.adapter.ts) lets users register the service as a connector and sync READY models.
• Chat service: callLlamacpp dispatch in ChatExecutionManager routes both local-llamacpp and LLAMACPP selected providers to ${LLAMACPP_SERVICE_URL}/api/v1/v1/chat/completions.
• Routing service: LlamacppHealthManager polls /api/v1/health every 30 s; subscribes to llamacpp.model.{loaded,unloaded,crashed} events to update runtimeHealth['LLAMACPP'] for fallback decisions.
• Audit service: LlamacppAuditConsumer subscribes to all 11 LLAMACPP_* event patterns; writes audit rows under entityType='llamacpp_model'. Progress events are intentionally suppressed (high frequency); summary captured on COMPLETED/FAILED.
• Frontend: /models/local-frontier page with hardware panel, filter bar, downloads drawer (live SSE), 3 dialogs (delete, override, runtime config). local-llamacpp group appears in chat ModelSelector once a model is READY.

Events Published (11):

• llamacpp.binary.installed, llamacpp.binary.updated
• llamacpp.pull.started, llamacpp.pull.progress, llamacpp.pull.completed, llamacpp.pull.failed
• llamacpp.model.loaded, llamacpp.model.unloaded, llamacpp.model.crashed
• llamacpp.weights.deleted
• llamacpp.preflight.overridden

Dependencies:

• PostgreSQL claw_llamacpp -- catalog, pull jobs, runtime config, hardware snapshots, binary releases, preflight overrides
• llamacpp-data Docker volume -- binary at /data/llamacpp/bin/llama-server, weights at /data/llamacpp/models/<name>/<tag>/
• HuggingFace API + GitHub Releases API (binary install + manifest enrichment)
• RabbitMQ -- 11 published events
• Auth Service -- JWT auth via shared-auth (inference endpoints are @Public for service-to-service calls)

GPU passthrough: Auto-detected by ./scripts/claw.sh up; layers the matching overlay (docker/docker-compose.dev.gpu-{nvidia,rocm,vulkan}.yml) when the host has the corresponding GPU. macOS warns (Docker can't access Metal). Run ./scripts/claw.sh gpu to probe without starting anything.

Health Endpoint: GET /api/v1/health -- returns binary install state, active loaded model, DB status.

---

Event Bus Summary

All events flow through the claw.events topic exchange on RabbitMQ with durable queues, 3 retries with exponential backoff, and dead-letter queues.

Event Pattern	Publisher	Consumers
user.created	Auth	--
user.login	Auth	Audit
user.logout	Auth	Audit
user.role_changed	Auth	--
user.deactivated	Auth	--
message.created	Chat	Routing
message.routed	Routing	Chat
message.completed	Chat	Audit, Memory
connector.created	Connector	Audit
connector.updated	Connector	Audit
connector.deleted	Connector	Audit
connector.synced	Connector	Audit, Routing
connector.health_checked	Connector	Audit, Routing
routing.decision_made	Routing	Audit
file.uploaded	File	--
file.chunked	File	--
memory.extracted	Memory	Audit
image.generated	Image	--
image.failed	Image	--
agent.session.connected	Agent	--
agent.session.disconnected	Agent	--
health.check	Health	--
log.server	All services	Server Logs
threads.generation_requested	Thread Generation	Thread Generation

---

Inter-Service HTTP Dependencies

Chat Service
  -> Connector Service  (GET /internal/connectors/config)
  -> Memory Service     (GET /internal/memories/for-context)
  -> Memory Service     (GET /internal/context-packs/:id/items)
  -> Workspace Service  (POST /internal/workspace/search)
  -> File Service       (GET /internal/files/:id/chunks)
  -> File Service       (GET /internal/files/:id/content)
  -> Ollama Service     (GET /internal/ollama/router-model)
  -> Image Service      (POST /internal/images/generate)
  -> File Gen Service   (POST /internal/file-generations/generate)

Routing Service
  -> Connector Service  (GET /internal/connectors/config)
  -> Ollama Service     (POST /ollama/generate)

Memory Service
  -> Ollama Service     (POST /ollama/generate)

Image Service
  -> Connector Service  (GET /internal/connectors/config)
  -> File Service       (POST /internal/files/store-image)

File Generation Service
  -> File Service       (POST /internal/files/store-image)

Agent Service
  -> Auth Service       (JWT validation via shared-auth)
  -> RabbitMQ           (publishes agent.session.connected / disconnected)

Workspace Service
  -> Provider APIs      (sync / search via provider-specific connectors)

Agent Service
  -> RabbitMQ           (publishes agent session lifecycle)

Health Service
  -> All 14 downstream services (GET /health)

---

Common Patterns Across All Services

Every backend service shares these characteristics:

1. Global Prefix: All routes prefixed with /api/v1/
2. Auth Guard: JWT-based AuthGuard applied globally, opt-out via @Public()
3. Roles Guard: RolesGuard for RBAC (@Roles(UserRole.ADMIN))
4. Rate Limiting: @nestjs/throttler (100 req/min default, SSE endpoints skip throttle)
5. Helmet: Security headers on all services
6. Zod Validation: All input validated via ZodValidationPipe
7. Error Handling: GlobalExceptionFilter with BusinessException
8. Logging: NestJS Logger + Pino structured logging + RabbitMQ log events
9. Health Check: Every service exposes GET /api/v1/health
10. CORS: Configured via CORS_ORIGINS environment variable