bert.hausmans/cmdb-insight
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f3637b85e1b94c31d0391a11ee519b60d23f986f
cmdb-insight/CLAUDE.md
Bert Hausmans ca21b9538d Improve Team-indeling dashboard UI and cache invalidation 
- Replace 'TEAM' label with Type attribute (Business/Enabling/Staf) in team blocks
- Make Type labels larger (text-sm) and brighter colors
- Make SUBTEAM label less bright (indigo-300) and smaller (text-[10px])
- Add 'FTE' suffix to bandbreedte values in header and application blocks
- Add Platform and Connected Device labels to application blocks
- Show Platform FTE and Workloads FTE separately in Platform blocks
- Add spacing between Regiemodel letter and count value
- Add cache invalidation for Team Dashboard when applications are updated
- Enrich team references with Type attribute in getSubteamToTeamMapping
2026-01-10 02:16:55 +01:00

283 lines
10 KiB
Markdown
Raw Blame History

# 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
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 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
Reference in New Issue View Git Blame Copy Permalink