cmdb-insight/CLAUDE.md

CLAUDE.md - CMDB Insight

Project Overview

Project: CMDB Insight (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:

• cmdb-insight-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

cmdb-insight/
├── 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/
│       │   ├── SearchDashboard.tsx    # Main dashboard with CMDB search
│       │   ├── Dashboard.tsx          # App Component statistics
│       │   ├── ApplicationList.tsx    # Application overview & filter
│       │   ├── ApplicationDetail.tsx  # Edit & AI classify
│       │   ├── TeamDashboard.tsx      # Team FTE dashboard
│       │   ├── ConfigurationV25.tsx   # FTE configuration
│       │   └── ReportsDashboard.tsx   # Reports overview
│       ├── services/api.ts       # API client
│       ├── stores/
│       │   ├── searchStore.ts    # Filter state (Zustand)
│       │   ├── navigationStore.ts # Navigation state
│       │   └── authStore.ts      # Authentication state
│       └── types/index.ts        # TypeScript interfaces
└── data/
    ├── zira-taxonomy.json
    └── management-parameters.json

Navigation Structure

The application uses a hierarchical menu structure:

Dashboard (/)                          # CMDB search page
│
├── Application Component (/app-components)
│   ├── Dashboard (/app-components)           # Statistics & overview
│   ├── Overzicht (/app-components/overview)  # Application list & filter
│   └── FTE Config (/app-components/fte-config) # FTE calculation config
│
└── Rapporten (/reports)
    ├── Overzicht (/reports)                  # Reports dashboard
    └── Team-indeling (/reports/team-dashboard) # Team FTE dashboard

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_SCHEMA_ID=<schema_id>

# Jira Authentication Method: 'pat' or 'oauth'
JIRA_AUTH_METHOD=pat                    # Choose: 'pat' (Personal Access Token) or 'oauth' (OAuth 2.0)

# For PAT authentication (JIRA_AUTH_METHOD=pat)
JIRA_PAT=<personal_access_token>        # Personal Access Token for Jira API access

# For OAuth 2.0 authentication (JIRA_AUTH_METHOD=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 (required for OAuth)
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
# Note: AI API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, TAVILY_API_KEY),
# default AI provider, and web search are configured per-user in profile settings,
# not in environment variables

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

Authentication

The application supports two authentication methods, configured via JIRA_AUTH_METHOD:

1. Personal Access Token (PAT) Mode (JIRA_AUTH_METHOD=pat)

• Default mode - Uses a single PAT for all Jira API calls
• Users don't need to log in
• All changes are attributed to the service account
• Best for: Development, internal tools, or when user attribution isn't required

Configuration:

JIRA_AUTH_METHOD=pat
JIRA_PAT=your_personal_access_token

2. OAuth 2.0 Mode (JIRA_AUTH_METHOD=oauth)

• Each user logs in with their own Jira credentials
• API calls are made under the user's account
• Better audit trail and access control
• Best for: Production environments where user attribution matters

Configuration:

JIRA_AUTH_METHOD=oauth
JIRA_OAUTH_CLIENT_ID=your_client_id
JIRA_OAUTH_CLIENT_SECRET=your_client_secret
JIRA_OAUTH_CALLBACK_URL=http://localhost:3001/api/auth/callback
SESSION_SECRET=your_secure_random_string

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 Variables (see above)

3. For Production:

   • Update callback URL to production domain
   • Set SESSION_SECRET to a cryptographically secure 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
cmdb-insight-specificatie.md	Complete technical specification
zira-taxonomy.json	90+ ZiRA application functions
management-parameters.json	Dropdown options and reference data
docs/refactor-plan.md	Architecture refactoring plan (Phase 1: Analysis)

Architecture Refactoring

Status: Phase 1 Complete - Analysis and Planning

A comprehensive refactoring plan has been created to improve maintainability, reduce duplication, and establish clearer separation of concerns. See docs/refactor-plan.md for:

• Current architecture map (files/folders/modules)
• Pain points and duplication analysis
• Target architecture (domain/infrastructure/services/api)
• Migration steps in order
• Explicit deletion list (files to remove later)
• API payload contract and recursion insights

⚠️ Note: Phase 1 is analysis only - no functional changes have been made yet.

Language

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