Service Overview

Jan Server ships four core services plus shared infrastructure. Use this document to understand how they fit together and where to look in the codebase.

Core Services

Service	Purpose	Port(s)	Source	Primary Docs
LLM API	OpenAI-compatible chat completions, conversation storage, model management	8080 (direct), 8000 via Kong	`services/llm-api`	../api/llm-api/README.md
Response API	Multi-step orchestration, tool chaining, integration with MCP Tools	8082	`services/response-api`	../api/response-api/README.md
Media API	Binary ingestion, jan_* IDs, S3 storage and resolution	8285	`services/media-api`	../api/media-api/README.md
MCP Tools	Model Context Protocol tools (web search, scraping, file search, python exec)	8091	`services/mcp-tools`	../api/mcp-tools/README.md
Memory Tools	Semantic memory with BGE-M3 embeddings, conversation caching	8090	`services/memory-tools`	`services/memory-tools/README.md`
Realtime API	WebRTC session management via LiveKit for real-time audio/video	8186	`services/realtime-api`	`services/realtime-api/README.md`
Template API (scaffold)	Go microservice blueprint for new services (not deployed)	8185	`services/template-api`	../guides/services-template.md

Configuration

All services use the centralized configuration system at pkg/config/:

Type-safe: Go structs with compile-time validation
YAML defaults: config/defaults.yaml for base configuration
Environment overrides: Service-specific env vars (e.g., LLM_API_HTTP_PORT)
Kubernetes values: Auto-generated from configuration structs
CLI tool: jan-cli config for validation and inspection

See Configuration Documentation for details.

Infrastructure Components

For detailed infrastructure architecture (Kong, Keycloak, databases, observability), see System Design.

Creating a New Service

Quick Start

# Generate from template
scripts/new-service-from-template.ps1 -Name my-service

Configuration Setup

New services should use the centralized configuration system:

Define service config in pkg/config/types.go:

type ServiceConfig struct {
HTTP HTTPConfig `yaml:"http"`
Database DatabaseConfig `yaml:"database"`
// Add service-specific fields
}

Regenerate config files:

make config-generate

Load config in your service:

import "jan-server/pkg/config"

cfg, _:= config.Load()
serviceCfg, _:= cfg.GetServiceConfig("my-service")

Update deployment configs:

Add service to docker/services-api.yml
Generate K8s values: jan-cli config k8s-values --env production

See Configuration System and Service Template Guide for the scaffold and full instructions.

Documentation Requirements

Update docs/architecture/services.md (this file) with new service row
Create docs/api/<service>/README.md with API reference
Add service to docs/README.md navigation
Update k8s/jan-server/values.yaml if deploying to Kubernetes

Service Interactions

LLM API -> Media API: LLM API resolves jan_* IDs before sending payloads to vLLM or upstream providers (MEDIA_RESOLVE_URL env var).
Response API -> LLM API: Response API delegates final language generation to LLM API (LLM_API_URL).
Response API -> MCP Tools: orchestrated tool calls are issued via JSON-RPC (MCP_TOOLS_URL).
MCP Tools -> Infrastructure: uses SearXNG, Vector Store, and SandboxFusion to execute user requests.

Keep this document updated whenever a service is added, renamed, or retires.

Service Overview

On this page