cmdb-insight/CLAUDE.md

# CLAUDE.md - ZiRA Classificatie Tool

## Project Overview

**Project:** ZiRA Classificatie Tool (Zuyderland CMDB Editor)
**Organization:** Zuyderland Medisch Centrum - ICMT
**Purpose:** Interactive tool for classifying ~500 application components into ZiRA (Ziekenhuis Referentie Architectuur) application functions with Jira Assets CMDB integration.

## Current Status

**Phase:** v1.0 - First Implementation Complete

The project has a working implementation with:
- Full backend API with Express + TypeScript
- React frontend with Dashboard, Application List, and Detail views
- Mock data service for development (can be switched to Jira Assets)
- AI classification integration with Claude API
- SQLite database for classification history

Key files:
- `zira-classificatie-tool-specificatie.md` - Complete technical specification
- `zira-taxonomy.json` - ZiRA taxonomy with 90+ application functions across 10 domains
- `management-parameters.json` - Reference data for dynamics, complexity, users, governance models

## Technology Stack

### Frontend
- React + TypeScript
- Vite (build tool)
- TailwindCSS

### Backend
- Node.js + Express + TypeScript
- SQLite (local caching)

### External Integrations
- **Jira Data Center REST API** (Assets CMDB) - source of truth for application data
- **Anthropic Claude API** (claude-sonnet-4-20250514) - AI classification suggestions

## Commands

```bash
# Backend development
cd backend && npm install && npm run dev

# Frontend development
cd frontend && npm install && npm run dev

# Docker (full stack)
docker-compose up

# Build for production
cd backend && npm run build
cd frontend && npm run build
```

## Project Structure

```
zira-classificatie-tool/
├── package.json                  # Root workspace package
├── docker-compose.yml            # Docker development setup
├── .env.example                  # Environment template
├── backend/
│   ├── package.json
│   ├── tsconfig.json
│   ├── Dockerfile
│   └── src/
│       ├── index.ts              # Express server entry
│       ├── config/env.ts         # Environment configuration
│       ├── services/
│       │   ├── jiraAssets.ts     # Jira Assets API client
│       │   ├── claude.ts         # Claude AI integration
│       │   ├── mockData.ts       # Mock data for development
│       │   ├── database.ts       # SQLite database service
│       │   └── logger.ts         # Winston logger
│       ├── routes/
│       │   ├── applications.ts   # Application CRUD endpoints
│       │   ├── classifications.ts # AI classification endpoints
│       │   ├── referenceData.ts  # Reference data endpoints
│       │   └── dashboard.ts      # Dashboard statistics
│       ├── data/
│       │   ├── zira-taxonomy.json
│       │   └── management-parameters.json
│       └── types/index.ts        # TypeScript interfaces
├── frontend/
│   ├── package.json
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   ├── Dockerfile
│   └── src/
│       ├── main.tsx              # React entry point
│       ├── App.tsx               # Main component with routing
│       ├── index.css             # Tailwind CSS imports
│       ├── components/
│       │   ├── Dashboard.tsx     # Overview statistics
│       │   ├── ApplicationList.tsx # Search & filter view
│       │   └── ApplicationDetail.tsx # Edit & AI classify
│       ├── services/api.ts       # API client
│       ├── stores/
│       │   ├── searchStore.ts    # Filter state (Zustand)
│       │   └── navigationStore.ts # Navigation state
│       └── types/index.ts        # TypeScript interfaces
└── data/
    ├── zira-taxonomy.json
    └── management-parameters.json
```

## Key Domain Concepts

### ZiRA (Ziekenhuis Referentie Architectuur)
Dutch hospital reference architecture with 90+ application functions organized in 10 domains:
- Sturing (Governance)
- Onderzoek (Research)
- Zorg-SAM, Zorg-CON, Zorg-AOZ, Zorg-ZON (Care delivery)
- Onderwijs (Education)
- Bedrijfsondersteuning (Business support)
- Generieke ICT (IT infrastructure)

### Editable Classification Fields
- **ApplicationFunction** - ZiRA taxonomy match
- **Dynamics Factor** - 1-4 scale (Stabiel to Zeer hoog)
- **Complexity Factor** - 1-4 scale (Laag to Zeer hoog)
- **Number of Users** - 7 ranges (< 100 to > 15.000)
- **Governance Model** - A-E (Centraal to Volledig Decentraal)

### AI Classification Confidence
- HOOG (high) - Strong match, can auto-apply
- MIDDEN (medium) - Reasonable match, needs review
- LAAG (low) - Uncertain, requires manual classification

## Environment Variables

```env
# Jira Data Center
JIRA_HOST=https://jira.zuyderland.nl
JIRA_PAT=<personal_access_token>
JIRA_SCHEMA_ID=<schema_id>

# Jira Object Type IDs
JIRA_APPLICATION_COMPONENT_TYPE_ID=<type_id>
JIRA_APPLICATION_FUNCTION_TYPE_ID=<type_id>
JIRA_DYNAMICS_FACTOR_TYPE_ID=<type_id>
JIRA_COMPLEXITY_FACTOR_TYPE_ID=<type_id>
JIRA_NUMBER_OF_USERS_TYPE_ID=<type_id>
JIRA_GOVERNANCE_MODEL_TYPE_ID=<type_id>
JIRA_APPLICATION_CLUSTER_TYPE_ID=<type_id>
JIRA_APPLICATION_TYPE_TYPE_ID=<type_id>

# Jira Attribute IDs
JIRA_ATTR_APPLICATION_FUNCTION=<attr_id>
JIRA_ATTR_DYNAMICS_FACTOR=<attr_id>
JIRA_ATTR_COMPLEXITY_FACTOR=<attr_id>
JIRA_ATTR_NUMBER_OF_USERS=<attr_id>
JIRA_ATTR_GOVERNANCE_MODEL=<attr_id>
JIRA_ATTR_APPLICATION_CLUSTER=<attr_id>
JIRA_ATTR_APPLICATION_TYPE=<attr_id>

# Claude AI
ANTHROPIC_API_KEY=<claude_api_key>

# Server
PORT=3001
NODE_ENV=development
```

## Implementation Notes

1. **Never commit PAT tokens** - Always use .env files (add to .gitignore)
2. **Jira Assets is source of truth** - SQLite is for local caching only
3. **Rate limiting** - Implement exponential backoff for Jira API calls
4. **Validation** - Verify ApplicationFunction objects exist before updating
5. **Audit trail** - Comprehensive logging for all classifications
6. **Reference data sync** - Fetch from Jira Assets on startup
7. **Navigation state** - Maintain filter state when navigating between screens

## Development Roadmap

1. **Phase 1 - Setup:** Project initialization, Vite + Express, Jira API connection test
2. **Phase 2 - Backend:** Services, API endpoints, error handling
3. **Phase 3 - Frontend:** Dashboard, classification workflow, state management
4. **Phase 4 - Integration:** E2E testing, bulk operations, reporting/export
5. **Phase 5 - Deployment:** Tests, documentation, deployment setup

## Key Files Reference

| File | Purpose |
|------|---------|
| `zira-classificatie-tool-specificatie.md` | Complete technical specification |
| `zira-taxonomy.json` | 90+ ZiRA application functions |
| `management-parameters.json` | Dropdown options and reference data |

## Language

- Code: English
- UI/Documentation: Dutch (user-facing content is in Dutch)
- Comments: English preferred