bert.hausmans/cmdb-insight
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ea1c84262c0a4231f407ad01fc398bb5bd407bb6
cmdb-insight/CLAUDE.md
Bert Hausmans ea1c84262c Add OAuth 2.0 authentication support for Jira Data Center 
- Add OAuth 2.0 configuration options in backend env.ts
- Create authService.ts for OAuth flow, token management, and sessions
- Create auth.ts routes for login, callback, logout, and user info
- Update JiraAssets service to use user tokens when OAuth is enabled
- Add cookie-parser for session handling
- Create Login.tsx component with Jira OAuth login button
- Add authStore.ts (Zustand) for frontend auth state management
- Update App.tsx to show login page when OAuth is enabled
- Add user menu with logout functionality
- Document OAuth setup in CLAUDE.md

Supports two modes:
1. Service Account: Uses JIRA_PAT for all requests (default)
2. OAuth 2.0: Each user authenticates with their Jira credentials
2026-01-06 15:40:52 +01:00

246 lines
8.6 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/
│ │ ├── 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> # 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:**
```env
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
Reference in New Issue View Git Blame Copy Permalink