# Phase 1: Integration Architecture Foundation

**Status:** ⬜ Not Started
**Parent plan:** [PLAN.md](./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
<!-- Filled in after completion -->