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

# 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

# Jira Data Center
JIRA_HOST=https://jira.zuyderland.nl
JIRA_PAT=<personal_access_token>        # Service account PAT (fallback when OAuth disabled)
JIRA_SCHEMA_ID=<schema_id>

# Jira OAuth 2.0 (optional - enables user authentication)
JIRA_OAUTH_ENABLED=false                # Set to 'true' to enable OAuth
JIRA_OAUTH_CLIENT_ID=<oauth_client_id>  # From Jira Application Link
JIRA_OAUTH_CLIENT_SECRET=<oauth_secret> # From Jira Application Link
JIRA_OAUTH_CALLBACK_URL=http://localhost:3001/api/auth/callback
JIRA_OAUTH_SCOPES=READ WRITE

# Session Configuration
SESSION_SECRET=<random_secret_string>   # Change in production!

# 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>

# AI Classification
ANTHROPIC_API_KEY=<claude_api_key>
OPENAI_API_KEY=<openai_api_key>         # Optional: alternative to Claude
DEFAULT_AI_PROVIDER=claude              # 'claude' or 'openai'

# Server
PORT=3001
NODE_ENV=development
FRONTEND_URL=http://localhost:5173

Authentication

The application supports two authentication modes:

1. Service Account Mode (Default)

• Uses a single PAT (JIRA_PAT) for all Jira API calls
• Users don't need to log in
• All changes are attributed to the service account

2. OAuth 2.0 Mode

• Each user logs in with their own Jira credentials
• API calls are made under the user's account
• Better audit trail and access control

Setting up OAuth 2.0 (Jira Data Center 8.14+)

1. Create Application Link in Jira:

   • Go to Jira Admin → Application Links
   • Create a new "Incoming Link"
   • Set Redirect URL: http://localhost:3001/api/auth/callback
   • Note the Client ID and Secret

2. Configure Environment:

   JIRA_OAUTH_ENABLED=true
   JIRA_OAUTH_CLIENT_ID=your_client_id
   JIRA_OAUTH_CLIENT_SECRET=your_client_secret
   JIRA_OAUTH_CALLBACK_URL=http://localhost:3001/api/auth/callback
   

3. For Production:

   • Update callback URL to production domain
   • Set SESSION_SECRET to a random string
   • Use HTTPS

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