Initial commit: ZiRA Classification Tool for Zuyderland CMDB
This commit is contained in:
197
CLAUDE.md
Normal file
197
CLAUDE.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user