web-app-launcher/plans/service-integrations/phase-1-architecture.md

Phase 1: Integration Architecture Foundation

Status: ⬜ Not Started Parent plan: PLAN.md Domain: backend

Objective

Build the core integration framework: TypeScript interfaces, registry pattern, shared cache, Prisma schema changes, API routes, and updated app service. This phase unlocks all subsequent integration phases.

Tasks

• Task 1: Create src/lib/server/integrations/types.ts — Define Integration, IntegrationEndpoint, IntegrationData, IntegrationConfig interfaces. Each integration has: id, name, icon, authConfigSchema (Zod), extraConfigSchema (optional Zod), endpoints array, testConnection method, fetchData method.
• Task 2: Create src/lib/server/integrations/registry.ts — Registry singleton with register(integration), get(id), list(), getForApp(app) methods. Auto-imports integrations from subdirectories.
• Task 3: Create src/lib/server/integrations/cache.ts — TTL-based cache for integration data. Key: ${appId}:${endpointId}, configurable TTL per endpoint. Reuse pattern from metricService.ts.
• Task 4: Create src/lib/server/integrations/encryption.ts — Encrypt/decrypt integration config JSON using AES-256-GCM with key from INTEGRATION_ENCRYPTION_KEY env var (fallback to JWT_SECRET for dev).
• Task 5: Update Prisma schema — Add integrationType String?, integrationConfig String?, integrationEnabled Boolean @default(false) to App model. Run npx prisma db push.
• Task 6: Update src/lib/types/app.ts — Add integration fields to AppRecord interface.
• Task 7: Update src/lib/server/services/appService.ts — Handle integration fields on create/update. Encrypt integrationConfig before storing, decrypt on read.
• Task 8: Update src/lib/utils/validators.ts — Add integration to WidgetType enum. Add Zod schema for integration widget config: { appId: string, endpointId: string, refreshInterval?: number }.
• Task 9: Create API route src/routes/api/integrations/+server.ts — GET returns list of available integration types with their endpoints and config schemas.
• Task 10: Create API route src/routes/api/integrations/test/+server.ts — POST { appId, integrationType, config } tests connection to the service.
• Task 11: Create API route src/routes/api/integrations/[appId]/data/[endpointId]/+server.ts — GET fetches live data from integration endpoint, uses cache.
• Task 12: Create src/lib/server/integrations/base.ts — Abstract base class or helper functions for common integration patterns (HTTP fetch with timeout, error wrapping, response parsing).

Files to Modify/Create

• src/lib/server/integrations/types.ts — new: core interfaces
• src/lib/server/integrations/registry.ts — new: integration registry
• src/lib/server/integrations/cache.ts — new: TTL cache
• src/lib/server/integrations/encryption.ts — new: config encryption
• src/lib/server/integrations/base.ts — new: shared helpers
• prisma/schema.prisma — modify: add 3 fields to App model
• src/lib/types/app.ts — modify: add integration fields
• src/lib/server/services/appService.ts — modify: handle integration fields
• src/lib/utils/validators.ts — modify: add integration widget type + config schema
• src/routes/api/integrations/+server.ts — new: list integrations
• src/routes/api/integrations/test/+server.ts — new: test connection
• src/routes/api/integrations/[appId]/data/[endpointId]/+server.ts — new: fetch data

Acceptance Criteria

• Integration interfaces are well-typed and extensible
• Registry can register and retrieve integrations
• Cache prevents repeated API calls within TTL
• Prisma schema has integration fields, migration runs clean
• App service encrypts/decrypts integration config transparently
• API routes return proper envelope responses
• All Zod schemas validate correctly

Notes

• Encryption key: use INTEGRATION_ENCRYPTION_KEY env var, fallback to JWT_SECRET for development simplicity
• The registry should be designed so adding a new integration is just: create a directory, implement the interface, register it
• Cache should handle concurrent requests to the same endpoint gracefully
• Big Bang strategy: build/tests may not pass after this phase since the integration widget type is registered but has no frontend renderer yet

Review Checklist

• All tasks completed
• Code follows project conventions
• No unintended side effects
• Types are comprehensive and well-documented
• Encryption is properly implemented (no plaintext secrets in DB)

Handoff to Next Phase