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)