# 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/
│       │   ├── 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

```env
# 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:**
```env
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:**
```env
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 |
|------|---------|
| `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