stack/docs/JARVIS_R1_BACKEND_MIGRATION.md

Jarvis r1 Backend Migration Plan

Overview

Migrate production-ready backend features from ~/src/jarvis (r1) to ~/src/mosaic-stack (r2) to accelerate development and leverage proven patterns.

Source: ~/src/jarvis/backend/src/ Target: ~/src/mosaic-stack/apps/api/src/ Related Issue: #30 (Migration scripts from jarvis-brain)

Stack Compatibility

Aspect	Jarvis r1	Mosaic Stack	Compatible	Notes
Framework	NestJS 10	NestJS 11	✅	Minor version bump
ORM	Prisma	Prisma 6.19.2	✅	Same tool
Database	PostgreSQL	PostgreSQL 17	✅	Version upgrade
Cache	Redis	Valkey	✅	Redis-compatible
Tracing	OpenTelemetry	None	⚠️	Need to add
LLM	Multi-provider	Ollama only	⚠️	Need abstraction
Config	Database-backed	YAML files	⚠️	Architecture difference

Key Features to Migrate

1. Multi-Provider LLM Abstraction

Source: ~/src/jarvis/backend/src/llm/providers/

Value: Supports Ollama, Claude (Anthropic), OpenAI, and Z.ai with unified interface.

Core Components:

• base-llm-provider.interface.ts - Abstract provider interface
• ollama.provider.ts - Local LLM provider with retry/backoff
• claude.provider.ts - Anthropic API provider
• openai.provider.ts - OpenAI API provider
• llm.manager.ts - Provider instance management
• llm.service.ts - High-level service orchestration

Target Location: apps/api/src/llm/providers/

Milestone: M3-Features (#21 Ollama integration) + M4-MoltBot (agent support)

Adapter Needed:

• Refactor existing LlmService to use provider pattern
• Move Ollama-specific code into OllamaProvider
• Add provider registration/discovery

---

2. Database-Backed Configuration Pattern

Source: ~/src/jarvis/backend/src/prisma/schema.prisma (llm_provider_instances table)

Value: Single source of truth for all service instances. No YAML duplication, hot reload without restart.

Schema Pattern:

model LlmProviderInstance {
  id            String   @id @default(uuid())
  provider_type String   // 'ollama' | 'claude' | 'openai' | 'zai'
  display_name  String   @db.VarChar(100)
  user_id       String?  @db.Uuid  // NULL = system-level
  config        Json     // Provider-specific settings
  is_default    Boolean  @default(false)
  is_enabled    Boolean  @default(true)
  created_at    DateTime @default(now())
  updated_at    DateTime @updatedAt

  user User? @relation(fields: [user_id], references: [id], onDelete: Cascade)

  @@index([user_id])
  @@index([is_default, is_enabled])
}

Target Location: apps/api/prisma/schema.prisma

Milestone: M3-Features (#21 Ollama integration)

Extension Opportunity: Generalize to ServiceInstance for database, cache, etc.

---

3. OpenTelemetry Tracing Infrastructure

Source: ~/src/jarvis/backend/src/telemetry/

Value: Distributed tracing, performance monitoring, GenAI semantic conventions.

Core Components:

• telemetry.service.ts - OTEL SDK initialization
• telemetry.interceptor.ts - Automatic span creation for HTTP/GraphQL
• llm-telemetry.decorator.ts - GenAI-specific spans
• span-context.service.ts - Context propagation

Features:

• Automatic request tracing
• LLM call instrumentation (token counts, latency, costs)
• Error tracking with stack traces
• Jaeger/Zipkin export
• GenAI semantic conventions (gen_ai.request.model, gen_ai.response.finish_reasons)

Target Location: apps/api/src/telemetry/

Milestone: M3-Features (new infrastructure)

Integration Points:

• Instrument all LLM provider calls
• Add to MoltBot agent execution
• Connect to existing logging

---

4. Personality System Backend

Source: ~/src/jarvis/backend/src/personality/

Value: Dynamic personality/assistant configuration with prompt templates.

Status in Mosaic Stack:

• ✅ UI exists (apps/web/src/app/admin/personality/page.tsx)
• ❌ Backend implementation missing

Core Components:

• personality.entity.ts - Personality model
• personality.service.ts - CRUD + template rendering
• personality-prompt.builder.ts - Context injection

Schema:

model Personality {
  id              String   @id @default(uuid())
  name            String   @unique @db.VarChar(100)
  display_name    String   @db.VarChar(200)
  system_prompt   String   @db.Text
  temperature     Float    @default(0.7)
  max_tokens      Int      @default(4000)
  llm_provider_id String?  @db.Uuid
  is_active       Boolean  @default(true)
  created_at      DateTime @default(now())
  updated_at      DateTime @updatedAt

  llm_provider LlmProviderInstance? @relation(fields: [llm_provider_id], references: [id])
  conversations Conversation[]
}

Target Location: apps/api/src/personality/

Milestone: M3-Features (#82 Personality Module)

---

5. Workspace-Scoped LLM Configuration

Source: ~/src/jarvis/backend/src/workspaces/workspace-llm.service.ts

Value: Per-workspace LLM provider selection and settings.

Pattern:

• System-level providers (user_id = NULL)
• User-level providers (user_id = UUID)
• Workspace-level overrides (via WorkspaceSettings)

Target Schema Addition:

model WorkspaceSettings {
  id                    String   @id @default(uuid())
  workspace_id          String   @unique @db.Uuid
  default_llm_provider  String?  @db.Uuid
  default_personality   String?  @db.Uuid
  settings              Json     // Other workspace preferences

  workspace     Workspace            @relation(fields: [workspace_id], references: [id], onDelete: Cascade)
  llm_provider  LlmProviderInstance? @relation(fields: [default_llm_provider], references: [id])
  personality   Personality?         @relation(fields: [default_personality], references: [id])
}

Target Location: Extend existing Workspace model

Milestone: M3-Features

---

6. MCP (Model Context Protocol) Infrastructure

Source: ~/src/jarvis/backend/src/mcp/

Status: Phase 1 complete (hub, stdio transport, 26 passing tests)

Value: Agent tool integration framework.

Core Components:

• mcp-hub.service.ts - Central registry for MCP servers
• mcp-server.interface.ts - Server lifecycle management
• stdio-transport.ts - Process-based communication
• tool-registry.ts - Available tools catalog

Target Location: apps/api/src/mcp/

Milestone: M4-MoltBot (agent skills)

Integration Points:

• Connect to Brain query API (#22)
• Provide tools for agent sessions
• Enable skill discovery

---

Migration Phases

Phase 1: LLM Abstraction (5-7 days)

Milestone: M3-Features

Task	Files	Priority
Create provider interface	llm/providers/base-llm-provider.interface.ts	P0
Port Ollama provider	llm/providers/ollama.provider.ts	P0
Add OpenAI provider	llm/providers/openai.provider.ts	P1
Add Claude provider	llm/providers/claude.provider.ts	P1
Create LLM manager	llm/llm.manager.ts	P0
Refactor existing LlmService	llm/llm.service.ts	P0
Add Prisma schema	prisma/schema.prisma (LlmProviderInstance)	P0
Create admin API endpoints	llm/llm.controller.ts	P1
Update tests	llm/*.spec.ts	P1

Success Criteria:

• ✅ All existing Ollama functionality works
• ✅ Can add/remove/switch providers via API
• ✅ No YAML configuration needed
• ✅ Tests pass

---

Phase 2: Personality Backend (2-3 days)

Milestone: M3-Features (#82)

Task	Files	Priority
Add Prisma schema	prisma/schema.prisma (Personality)	P0
Create personality service	personality/personality.service.ts	P0
Create CRUD endpoints	personality/personality.controller.ts	P0
Build prompt builder	personality/personality-prompt.builder.ts	P1
Connect to existing UI	Wire up API calls	P0
Add tests	personality/*.spec.ts	P1

Success Criteria:

• ✅ UI can create/edit personalities
• ✅ Personalities persist to database
• ✅ Chat uses selected personality
• ✅ Prompt templates render correctly

---

Phase 3: OpenTelemetry (3-4 days)

Milestone: M3-Features (infrastructure)

Task	Files	Priority
Add OTEL dependencies	package.json	P0
Create telemetry service	telemetry/telemetry.service.ts	P0
Add HTTP interceptor	telemetry/telemetry.interceptor.ts	P0
Create LLM decorator	telemetry/llm-telemetry.decorator.ts	P1
Instrument LLM providers	All provider files	P1
Configure Jaeger export	main.ts	P2
Add trace context to logs	Update logging	P2
Documentation	docs/3-architecture/telemetry.md	P1

Success Criteria:

• ✅ All HTTP requests create spans
• ✅ LLM calls instrumented with token counts
• ✅ Traces viewable in Jaeger
• ✅ No performance degradation

---

Phase 4: MCP Integration (2-3 days)

Milestone: M4-MoltBot

Task	Files	Priority
Port MCP hub	mcp/mcp-hub.service.ts	P0
Port stdio transport	mcp/stdio-transport.ts	P0
Create tool registry	mcp/tool-registry.ts	P0
Connect to Brain API	Integration with #22	P0
Add MCP endpoints	mcp/mcp.controller.ts	P1
Port tests	mcp/*.spec.ts	P1

Success Criteria:

• ✅ MCP servers can register
• ✅ Tools discoverable by agents
• ✅ Brain query accessible via MCP
• ✅ Tests pass

---

Phase 5: Workspace LLM Config (1-2 days)

Milestone: M3-Features

Task	Files	Priority
Extend workspace schema	prisma/schema.prisma (WorkspaceSettings)	P0
Add settings service	workspaces/workspace-settings.service.ts	P0
Update workspace UI	Frontend settings page	P1
Add provider selection API	workspaces/workspaces.controller.ts	P0

Success Criteria:

• ✅ Workspaces can select LLM provider
• ✅ Workspaces can set default personality
• ✅ Settings persist correctly
• ✅ Multi-tenant isolation maintained

---

Gap Analysis

What Mosaic Stack Already Has ✅

• Workspace isolation (RLS)
• Teams and RBAC
• Knowledge management with pgvector
• Kanban, Gantt, Dashboard widgets
• Basic Ollama integration
• BetterAuth + Authentik ready
• Socket.io real-time updates

What jarvis r1 Provides ✅

• Multi-provider LLM (Ollama, Claude, OpenAI)
• Database-backed configuration (no YAML)
• OpenTelemetry tracing
• Personality system backend
• MCP Phase 1 infrastructure
• Hot reload capability
• Multi-instance pattern (system + user-scoped)

Combined Platform Advantages 🚀

• Enterprise multi-tenancy + flexible LLM
• Semantic search + multi-provider chat
• Agent orchestration + MCP tools
• Observability from day one
• Workspace-scoped AI configuration

---

Data Migration

Source: ~/src/jarvis-brain/data/*.json (JSON files) Target: Mosaic Stack PostgreSQL database

Migration Script Location: apps/api/src/scripts/migrate-jarvis-brain.ts

Mapping:

jarvis-brain	Mosaic Stack	Notes
tasks.json	Task table	Map domain → workspace
events.json	Event table	Calendar integration
projects.json	Project table	Direct mapping
agents.json	Agent/AgentSession	Active sessions
tickets.json	Custom Ticket table	GLPI sync
verizon-*.json	KnowledgeEntry	Flatten to knowledge items

Related Issues:

• #30 Migration scripts from jarvis-brain
• #31 Data validation and integrity checks
• #32 Parallel operation testing

Milestone: M5-Migration (0.1.0 MVP)

---

Integration with Existing Milestones

Migration Phase	Milestone	Issues
LLM Abstraction	M3-Features	#21 Ollama integration
Personality Backend	M3-Features	#82 Personality Module
OpenTelemetry	M3-Features	(New infrastructure)
MCP Integration	M4-MoltBot	#22 Brain API, #23-27 Skills
Workspace LLM Config	M3-Features	(Workspace enhancement)
Data Migration	M5-Migration	#30, #31, #32

---

Recommended Execution Strategy

Option A: Sequential (Conservative)

1. Phase 1 (LLM) → Phase 2 (Personality) → Phase 3 (OTEL) → Phase 4 (MCP) → Phase 5 (Workspace)
2. Timeline: ~15-18 days
3. Advantage: Each phase fully tested before next
4. Disadvantage: Slower overall

Option B: Parallel (Aggressive)

1. Agent 1: Phase 1 (LLM Abstraction)
2. Agent 2: Phase 2 (Personality Backend)
3. Agent 3: Phase 3 (OpenTelemetry)
4. Agent 4: Phase 4 (MCP Integration)
5. Timeline: ~7-10 days
6. Advantage: Fast completion
7. Disadvantage: Integration complexity, merge conflicts

Option C: Hybrid (Recommended)

1. Week 1: Phase 1 (LLM) + Phase 2 (Personality) in parallel
2. Week 2: Phase 3 (OTEL) + Phase 4 (MCP) in parallel
3. Week 3: Phase 5 (Workspace) + Integration testing
4. Timeline: ~12-14 days
5. Advantage: Balanced speed and stability

---

Dependencies

┌─────────────────────────────┐
│   Phase 1: LLM Abstraction  │
│         (Foundation)        │
└──────────┬──────────────────┘
           │
     ┌─────┴─────┐
     │           │
     ▼           ▼
┌─────────┐  ┌──────────┐
│Phase 2  │  │ Phase 3  │
│Persona  │  │  OTEL    │
│lity     │  │          │
└─────────┘  └────┬─────┘
                  │
                  ▼
          ┌──────────────┐
          │   Phase 4    │
          │     MCP      │
          └──────┬───────┘
                 │
                 ▼
          ┌──────────────┐
          │   Phase 5    │
          │  Workspace   │
          │    Config    │
          └──────────────┘

Key Dependencies:

• Phase 2, 3 depend on Phase 1 (LLM providers must exist)
• Phase 4 can parallel with Phase 3 (independent)
• Phase 5 depends on Phase 1, 2 (needs providers + personalities)

---

Testing Strategy

Unit Tests

• All providers implement interface correctly
• Manager handles provider selection
• Personality templates render
• OTEL spans created/exported

Integration Tests

• End-to-end LLM calls through manager
• Workspace settings override system defaults
• MCP tools callable from agents
• Telemetry spans link correctly

Migration Tests

• All jarvis-brain data imports without errors
• Referential integrity maintained
• No data loss
• Domain → Workspace mapping correct

---

Risks & Mitigations

Risk	Impact	Mitigation
API breaking changes between NestJS 10→11	High	Review migration guide, test thoroughly
Prisma schema conflicts	Medium	Use separate migration for new tables
Performance regression from OTEL	Medium	Benchmark before/after, make OTEL optional
jarvis-brain data corruption on migration	High	Backup all JSON files, dry-run script first
Provider API rate limits during testing	Low	Use mocks in tests, real providers in E2E only

---

Success Criteria

Phase 1 Complete ✅

• Can switch between Ollama, Claude, OpenAI via UI
• No hardcoded provider configurations
• All providers pass test suite
• Existing chat functionality unbroken

Phase 2 Complete ✅

• Personality UI functional end-to-end
• Personalities persist to database
• Chat uses selected personality
• Prompt templates support variables

Phase 3 Complete ✅

• Traces visible in Jaeger
• LLM calls show token counts
• HTTP requests traced automatically
• No >5% performance overhead

Phase 4 Complete ✅

• MCP servers can register
• Brain query accessible via MCP
• Agents can discover tools
• All jarvis r1 MCP tests pass

Phase 5 Complete ✅

• Workspaces can configure LLM provider
• Settings isolated per workspace
• Multi-tenant configuration verified
• No cross-workspace data leakage

Migration Complete ✅

• All jarvis-brain data in PostgreSQL
• Data validation passes (#31)
• Parallel operation verified (#32)
• Ready for 0.1.0 MVP release

---

Files to Create

Backend (apps/api/src/)

llm/
├─ providers/
│  ├─ base-llm-provider.interface.ts
│  ├─ ollama.provider.ts
│  ├─ openai.provider.ts
│  └─ claude.provider.ts
├─ llm.manager.ts
├─ llm.service.ts (refactor existing)
└─ llm.controller.ts

personality/
├─ personality.entity.ts
├─ personality.service.ts
├─ personality.controller.ts
├─ personality-prompt.builder.ts
└─ dto/
   ├─ create-personality.dto.ts
   └─ update-personality.dto.ts

telemetry/
├─ telemetry.service.ts
├─ telemetry.interceptor.ts
├─ llm-telemetry.decorator.ts
└─ span-context.service.ts

mcp/
├─ mcp-hub.service.ts
├─ mcp-server.interface.ts
├─ stdio-transport.ts
└─ tool-registry.ts

workspaces/
└─ workspace-settings.service.ts (extend existing)

scripts/
└─ migrate-jarvis-brain.ts

Schema (apps/api/prisma/)

migrations/
└─ YYYYMMDDHHMMSS_add_llm_and_personality/
   └─ migration.sql

schema.prisma
└─ Add models: LlmProviderInstance, Personality, WorkspaceSettings

Documentation (docs/)

3-architecture/
├─ llm-provider-architecture.md
├─ telemetry.md
└─ mcp-integration.md

2-development/
└─ testing-llm-providers.md

---

Changelog

Date	Change
2026-01-30	Created migration plan from jarvis r1 exploration

---

Related Documents

• Frontend Migration
• Roadmap
• Federation Architecture
• Agent Orchestration