cmdb-insight/docs/DATABASE-DRIVEN-SCHEMA-IMPLEMENTATION-PLAN.md

Database-Driven Schema Implementation Plan

Overzicht

Dit plan beschrijft de migratie van statische schema files naar een volledig database-driven aanpak waarbij:

1. Schema wordt dynamisch opgehaald van Jira Assets API
2. Schema wordt opgeslagen in PostgreSQL database
3. Datamodel en datavalidatie pagina's worden opgebouwd vanuit database
4. TypeScript types worden gegenereerd vanuit database (handmatig)

Architectuur

┌─────────────────┐
│ Jira Assets API │ (Authoritative Source)
└────────┬────────┘
         │
         │ Schema Discovery
         ▼
┌─────────────────┐
│ Schema Discovery│ (Jira API → Database)
│    Service      │
└────────┬────────┘
         │
         │ Store in DB
         ▼
┌─────────────────┐
│  PostgreSQL DB  │ (Cached Schema)
│  - object_types │
│  - attributes   │
└────────┬────────┘
         │
         │ Serve to Frontend
         ▼
┌─────────────────┐
│  API Endpoints   │ (/api/schema)
└────────┬────────┘
         │
         │ Code Generation
         ▼
┌─────────────────┐
│ TypeScript Types │ (Handmatig gegenereerd)
└─────────────────┘

Database Schema

De database heeft al de benodigde tabellen in normalized-schema.ts:

• object_types - Object type definities
• attributes - Attribute definities per object type

Geen extra tabellen nodig! We gebruiken de bestaande structuur.

Implementatie Stappen

Stap 1: Schema Discovery Service Aanpassen ✅

Huidige situatie:

• schemaDiscoveryService haalt data uit statische OBJECT_TYPES file

Nieuwe situatie:

• schemaDiscoveryService haalt schema direct van Jira Assets API
• Gebruikt JiraSchemaFetcher logica (uit generate-schema.ts)
• Slaat schema op in database tabellen

Bestanden:

• backend/src/services/schemaDiscoveryService.ts - Aanpassen om API calls te maken

Stap 2: Schema Cache Service ✅

Nieuwe service:

• In-memory cache met 5 minuten TTL
• Cache invalidation bij schema updates
• Snelle response voor /api/schema endpoint

Bestanden:

• backend/src/services/schemaCacheService.ts - Nieuw bestand

Stap 3: Schema API Endpoint Migreren ✅

Huidige situatie:

• /api/schema endpoint leest van statische OBJECT_TYPES file

Nieuwe situatie:

• /api/schema endpoint leest van database (via cache)
• Gebruikt schemaCacheService voor performance

Bestanden:

• backend/src/routes/schema.ts - Aanpassen om database te gebruiken

Stap 4: Code Generation Script ✅

Nieuwe functionaliteit:

• Script dat database schema → TypeScript types genereert
• Handmatig uitvoerbaar via CLI command
• Genereert: jira-schema.ts, jira-types.ts

Bestanden:

• backend/scripts/generate-types-from-db.ts - Nieuw bestand
• package.json - NPM script toevoegen

Stap 5: Datavalidatie Pagina Migreren ✅

Huidige situatie:

• Gebruikt mogelijk statische schema files

Nieuwe situatie:

• Volledig database-driven
• Gebruikt schemaDiscoveryService voor schema data

Bestanden:

• backend/src/routes/dataValidation.ts - Controleren en aanpassen indien nodig

Stap 6: Database Indexes ✅

Toevoegen:

• Indexes voor snelle schema queries
• Performance optimalisatie

Bestanden:

• backend/src/services/database/normalized-schema.ts - Indexes toevoegen

Stap 7: CLI Command voor Schema Discovery ✅

Nieuwe functionaliteit:

• Handmatige trigger voor schema discovery
• Bijvoorbeeld: npm run discover-schema

Bestanden:

• backend/scripts/discover-schema.ts - Nieuw bestand
• package.json - NPM script toevoegen

API Endpoints

GET /api/schema

Huidig: Leest van statische files
Nieuw: Leest van database (via cache)

Response format: Ongewijzigd (backward compatible)

POST /api/schema/discover (Nieuw)

Functionaliteit: Handmatige trigger voor schema discovery
Gebruik: Admin endpoint voor handmatige schema refresh

Code Generation

Script: generate-types-from-db.ts

Input: Database schema (object_types, attributes)
Output:

• backend/src/generated/jira-schema.ts
• backend/src/generated/jira-types.ts

Uitvoering: Handmatig via npm run generate-types

Migratie Strategie

1. Parallelle implementatie: Nieuwe code naast oude code
2. Feature flag: Optioneel om tussen oude/nieuwe aanpak te switchen
3. Testing: Uitgebreide tests voor schema discovery
4. Handmatige migratie: Breaking changes worden handmatig opgelost

Performance Overwegingen

• In-memory cache: 5 minuten TTL voor schema endpoints
• Database indexes: Voor snelle queries op object_types en attributes
• Lazy loading: Schema wordt alleen geladen wanneer nodig

Breaking Changes

• Geen fallback: Als database schema niet beschikbaar is, werkt niets
• TypeScript errors: Bij schema wijzigingen ontstaan compile errors
• Handmatige fix: Developers lossen errors handmatig op

Testing Checklist

• Schema discovery van Jira API werkt
• Schema wordt correct opgeslagen in database
• /api/schema endpoint retourneert database data
• Cache werkt correct (TTL, invalidation)
• Code generation script werkt
• Datamodel pagina toont database data
• Datavalidatie pagina toont database data
• Handmatige schema discovery trigger werkt

Rollout Plan

1. Fase 1: Schema discovery service aanpassen (API calls)
2. Fase 2: Schema cache service implementeren
3. Fase 3: API endpoints migreren
4. Fase 4: Code generation script maken
5. Fase 5: Testing en validatie
6. Fase 6: Oude statische files verwijderen (na handmatige migratie)

Risico's en Mitigatie

Risico	Impact	Mitigatie
Jira API niet beschikbaar	Hoog	Geen fallback - downtime acceptabel
Schema wijzigingen	Medium	TypeScript errors - handmatig oplossen
Performance issues	Laag	Cache + indexes
Data migratie fouten	Medium	Uitgebreide tests

Success Criteria

✅ Schema wordt dynamisch opgehaald van Jira API
✅ Schema wordt opgeslagen in database
✅ Datamodel pagina toont database data
✅ Datavalidatie pagina toont database data
✅ Code generation script werkt
✅ Handmatige schema discovery werkt
✅ Performance is acceptabel (< 1s voor schema endpoint)