alexei.dolgolyov
50e8519220
- Add 6 renderer components: StatCard, Gauge, List, Progress, AlertBanner, Chart - Add IntegrationWidget container with auto-refresh, loading, error states - Add IntegrationAlertOverlay for layout-level critical alerts - Add IntegrationConfigFields for dynamic form generation from Zod schemas - Register integration type in WidgetRenderer - Extend WidgetCreationForm with integration app/endpoint pickers - Extend AppForm with integration config section and test connection button - Add /api/integrations/alerts endpoint
63 lines
4.6 KiB
Markdown
63 lines
4.6 KiB
Markdown
# 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 -->
|