mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: Add jarvis r1 backend migration specification
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
Details

Browse Source 
- Multi-provider LLM abstraction plan
- OpenTelemetry tracing integration
- Personality system backend implementation
- MCP infrastructure migration
- Database-backed configuration pattern
- 5-phase migration plan with milestones
- Maps to existing issues #21, #22-27, #30-32, #82

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
2026-01-30 15:24:12 -06:00
parent a2715d1925
commit d10b3a163e
1 changed files with 644 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

644
docs/JARVIS_R1_BACKEND_MIGRATION.md Normal file
View File

@@ -0,0 +1,644 @@
# 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:**
```prisma
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:**
```prisma
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:**
```prisma
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](./JARVIS_FE_MIGRATION.md)
- [Roadmap](./ROADMAP.md)
- [Federation Architecture](./design/federation-architecture.md)
- [Agent Orchestration](./design/agent-orchestration.md)