pos-system/docs/en/guides/iam-migration.md

# Migration Guide: Auth Service → IAM Service

This document guides you through migrating from `auth-service` to `iam-service`.

## Overview

IAM Service is an extended version of Auth Service with additional features for Identity Management, Access Management, and Governance & Compliance. All Auth Service API endpoints remain unchanged to ensure backward compatibility.

## Migration Workflow

```mermaid
graph LR
 Start([Start Migration]) --> Backup[ Backup]
 Backup --> DBMigrate[ Database Migration]
 DBMigrate --> UpdateDeps[ Update Dependencies]
 UpdateDeps --> Deploy[ Deploy]
 Deploy --> Verify[ Verify]
 Verify --> Decision{All Tests Pass?}
 Decision -->|Yes| Rollout[ Gradual Rollout]
 Decision -->|No| Rollback[⏮ Rollback]
 Rollback --> Debug[ Debug Issues]
 Debug --> DBMigrate
 Rollout --> Monitor[ Monitor]
 Monitor --> Complete([ Complete])

 style Start fill:#2d4263,stroke:#c69b7b,stroke-width:2px,color:#f5f5f5
 style Backup fill:#191e29,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style DBMigrate fill:#191e29,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style UpdateDeps fill:#191e29,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style Deploy fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Verify fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Decision fill:#4a5568,stroke:#c69b7b,stroke-width:2px,color:#f5f5f5
 style Rollout fill:#1a472a,stroke:#48bb78,stroke-width:2px,color:#f5f5f5
 style Rollback fill:#742a2a,stroke:#f56565,stroke-width:2px,color:#f5f5f5
 style Debug fill:#742a2a,stroke:#f56565,stroke-width:2px,color:#f5f5f5
 style Monitor fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Complete fill:#1a472a,stroke:#48bb78,stroke-width:2px,color:#f5f5f5
```

## Backward Compatibility

 **All existing endpoints continue to work normally:**

- `/api/v1/auth/*` - Authentication endpoints
- `/api/v1/rbac/*` - RBAC endpoints
- `/api/v1/mfa/*` - MFA endpoints
- `/api/v1/sessions/*` - Session management endpoints
- `/api/v1/oidc/*` - OIDC endpoints

No breaking changes. Existing clients can continue using these endpoints without any modifications.

## Architecture Comparison

```mermaid
graph TB
 subgraph "Auth Service (Old)"
 A1[Authentication]
 A2[RBAC]
 A3[MFA]
 A4[Sessions]
 A5[OIDC]
 end

 subgraph "IAM Service (New)"
 B1[Authentication]
 B2[RBAC]
 B3[MFA]
 B4[Sessions]
 B5[OIDC]
 B6[Identity Management]
 B7[Access Management]
 B8[Governance]
 end

 A1 -.->|Unchanged| B1
 A2 -.->|Unchanged| B2
 A3 -.->|Unchanged| B3
 A4 -.->|Unchanged| B4
 A5 -.->|Unchanged| B5

 style A1 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style A2 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style A3 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style A4 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style A5 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5

 style B1 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style B2 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style B3 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style B4 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style B5 fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style B6 fill:#1a472a,stroke:#48bb78,stroke-width:2px,color:#f5f5f5
 style B7 fill:#1a472a,stroke:#48bb78,stroke-width:2px,color:#f5f5f5
 style B8 fill:#1a472a,stroke:#48bb78,stroke-width:2px,color:#f5f5f5
```

## Changes

### 1. Service Name

- **Old**: `auth-service`
- **New**: `iam-service`

### 2. Package Name

- **Old**: `@goodgo/auth-service`
- **New**: `@goodgo/iam-service`

### 3. Database Schema

Database schema is extended with new models but **does not delete or modify** existing models:

**New models added:**
- `Organization` - Organization management
- `Group` - Group management
- `GroupMember` - Group members
- `GroupPermission` - Group permissions
- `UserProfile` - Extended profile
- `IdentityVerification` - Identity verification
- `AccessRequest` - Access requests
- `AccessReview` - Access reviews
- `ComplianceReport` - Compliance reports
- `PolicyTemplate` - Policy templates
- `RiskScore` - Risk scores

**User model extended:**
- Added `organizationId` field (optional)
- Added new relations (optional)

```mermaid
erDiagram
 User ||--o{ UserProfile : has
 User ||--o{ AccessRequest : creates
 User }o--|| Organization : "belongs to"
 User ||--o{ GroupMember : "member of"

 Organization ||--o{ Group : contains
 Group ||--o{ GroupMember : has
 Group ||--o{ GroupPermission : has

 AccessRequest ||--|| AccessReview : "reviewed by"
 Organization ||--o{ ComplianceReport : generates

 User {
 string id PK
 string email
 string organizationId FK
 }

 Organization {
 string id PK
 string name
 }

 Group {
 string id PK
 string organizationId FK
 }

 UserProfile {
 string userId FK
 json metadata
 }

 AccessRequest {
 string id PK
 string userId FK
 }
```

### 4. New API Endpoints

#### Identity Management
- `/api/v1/identity/users/*` - User lifecycle management
- `/api/v1/identity/users/:id/profile` - Profile management
- `/api/v1/identity/verification/*` - Identity verification
- `/api/v1/identity/organizations/*` - Organization management
- `/api/v1/identity/groups/*` - Group management

#### Access Management
- `/api/v1/access/requests/*` - Access requests
- `/api/v1/access/reviews/*` - Access reviews
- `/api/v1/access/analytics/*` - Access analytics

#### Governance
- `/api/v1/governance/compliance/*` - Compliance reports
- `/api/v1/governance/policies/*` - Policy governance
- `/api/v1/governance/risk/*` - Risk management
- `/api/v1/governance/reports/*` - Reporting dashboard

### 5. Environment Variables

Some new environment variables may be added in the future for advanced IAM features (email service, SMS service, file storage), but they will not affect existing variables.

### 6. Deployment Configuration

**Docker Compose:**
- Service name: `auth-service` → `iam-service`
- Container name: `auth-service-local` → `iam-service-local`
- Traefik labels: Add new routes for `/api/v1/identity/*`, `/api/v1/access/*`, `/api/v1/governance/*`

**Kubernetes:**
- Deployment name: `auth-service` → `iam-service`
- Service name: `auth-service` → `iam-service`
- ConfigMap: `auth-service-config` → `iam-service-config`
- Secrets: `auth-service-secrets` → `iam-service-secrets`

## Migration Steps

### Step 1: Backup

```bash
# Backup database
pg_dump $DATABASE_URL > auth-service-backup.sql

# Backup code
cp -r services/auth-service services/auth-service.backup
```

### Step 2: Database Migration

```bash
cd services/iam-service

# Generate Prisma client with new schema
pnpm prisma generate

# Create migration
pnpm prisma migrate dev --name add_iam_models

# Verify migration
pnpm prisma studio # Check database structure
```

### Step 3: Update Dependencies

```bash
# Install dependencies (if new packages exist)
pnpm install

# Verify types compile
pnpm typecheck
```

### Step 4: Update Deployment

**Local Development:**
```bash
cd deployments/local
# Update docker-compose.yml (already updated)
docker-compose up -d iam-service
```

**Staging/Production:**
- Update Kubernetes manifests
- Update ingress routes
- Update ConfigMaps and Secrets

### Step 5: Verify Backward Compatibility

Test that all old endpoints still work:

```bash
# Test auth endpoints
curl http://localhost/api/v1/auth/me

# Test RBAC endpoints
curl http://localhost/api/v1/rbac/permissions

# Test MFA endpoints
curl http://localhost/api/v1/mfa/devices
```

### Step 6: Gradual Rollout

1. **Dual Deployment** (Optional):
 - Deploy both `auth-service` and `iam-service` simultaneously
 - Gradually route traffic to `iam-service`
 - Monitor errors and performance

2. **Update Clients**:
 - Update clients to use new endpoints if needed
 - Clients don't need updates if only using old endpoints

3. **Deprecate Old Service**:
 - After verifying everything works well, deprecate `auth-service`
 - Ensure all clients have migrated to `iam-service`

## Deployment Strategy

```mermaid
graph TB
 Current[Current: auth-service] --> Phase1[Phase 1: Dual Deploy]
 Phase1 --> Split{Traffic Split}
 Split -->|10%| IAM1[iam-service]
 Split -->|90%| Auth1[auth-service]

 Split --> Phase2[Phase 2: Increase]
 Phase2 --> Split2{Traffic Split}
 Split2 -->|50%| IAM2[iam-service]
 Split2 -->|50%| Auth2[auth-service]

 Split2 --> Phase3[Phase 3: Majority]
 Phase3 --> Split3{Traffic Split}
 Split3 -->|90%| IAM3[iam-service]
 Split3 -->|10%| Auth3[auth-service]

 Split3 --> Phase4[Phase 4: Complete]
 Phase4 --> Final[iam-service only]

 style Current fill:#2d4263,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
 style Phase1 fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Phase2 fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Phase3 fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Phase4 fill:#2d4263,stroke:#87a2a7,stroke-width:2px,color:#f5f5f5
 style Final fill:#1a472a,stroke:#48bb78,stroke-width:2px,color:#f5f5f5
 style Split fill:#4a5568,stroke:#c69b7b,stroke-width:2px,color:#f5f5f5
 style Split2 fill:#4a5568,stroke:#c69b7b,stroke-width:2px,color:#f5f5f5
 style Split3 fill:#4a5568,stroke:#c69b7b,stroke-width:2px,color:#f5f5f5
 style IAM1 fill:#1a472a,stroke:#48bb78,stroke-width:1px,color:#f5f5f5
 style IAM2 fill:#1a472a,stroke:#48bb78,stroke-width:1px,color:#f5f5f5
 style IAM3 fill:#1a472a,stroke:#48bb78,stroke-width:1px,color:#f5f5f5
 style Auth1 fill:#742a2a,stroke:#f56565,stroke-width:1px,color:#f5f5f5
 style Auth2 fill:#742a2a,stroke:#f56565,stroke-width:1px,color:#f5f5f5
 style Auth3 fill:#742a2a,stroke:#f56565,stroke-width:1px,color:#f5f5f5
```

## Rollback Plan

If rollback is needed:

1. **Database Rollback**:
 ```bash
 # Revert Prisma migration
 cd services/iam-service
 pnpm prisma migrate resolve --rolled-back <migration_name>

 # Or restore from backup
 psql $DATABASE_URL < auth-service-backup.sql
 ```

2. **Service Rollback**:
 ```bash
 # Switch back to auth-service in docker-compose
 # Or revert Kubernetes deployment
 kubectl rollout undo deployment/auth-service
 ```

## Breaking Changes

**No breaking changes** in this migration. All existing API endpoints and database models are preserved.

## Notes

- This migration is **additive** - only adds new features, does not remove or change existing ones
- Database migrations are **non-destructive** - do not delete or modify existing data
- Clients can continue using old endpoints without any changes

## Support

If you encounter issues during migration:
1. Check logs: `docker-compose logs iam-service`
2. Verify database connection
3. Check environment variables
4. Review error messages and stack traces

## Quick Tips

**Migration Checklist:**
- Backup database and code
- Run database migrations
- Update deployment configuration
- Test backward compatibility
- Monitor gradual rollout
- Prepare rollback plan

### Common Issues & Solutions

| Issue | Cause | Solution |
|-------|-------|----------|
| Migration failed | Database connection | Check `DATABASE_URL` in `.env` |
| Service won't start | Missing env vars | Verify all env vars are set |
| Slow performance | Database indexes | Run Prisma migrations completely |
| Connection timeout | Network issues | Check firewall & security groups |
| New endpoints 404 | Routing config | Update Traefik/Ingress config |

**Visual Indicators:**
- Old Components (Unchanged)
- New Components (Added)
- Components to Deprecate
- Requires Attention