# Multi-Cloud Orchestration Portal - TypeScript Version

## 🚀 Quick Start

### Prerequisites
- Node.js >= 18.0.0
- pnpm >= 8.0.0

### Installation

```bash
# Install pnpm globally (if not already installed)
npm install -g pnpm

# Or using corepack (recommended)
corepack enable
corepack prepare pnpm@latest --activate

# Install dependencies
cd orchestration/portal
pnpm install
```

### Development

```bash
# Run in development mode with hot reload
pnpm dev

# Or build and run
pnpm build
pnpm start
```

### Access Portals

- **Main Dashboard**: http://localhost:5000
- **Health Dashboard**: http://localhost:5000/dashboard/health
- **Cost Dashboard**: http://localhost:5000/dashboard/costs

## 📁 Project Structure

```
orchestration/portal/
├── src/
│   ├── server.ts          # Main Express server
│   ├── config.ts          # Configuration management
│   ├── database.ts         # Database operations
│   └── types/
│       └── index.ts       # TypeScript type definitions
├── templates/             # EJS templates (HTML)
├── static/               # Static assets (CSS, JS, images)
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── .eslintrc.json        # ESLint configuration
```

## 🔧 Scripts

- `pnpm build` - Compile TypeScript to JavaScript
- `pnpm start` - Run compiled server
- `pnpm dev` - Run in development mode with hot reload
- `pnpm watch` - Watch for changes and rebuild
- `pnpm lint` - Run ESLint
- `pnpm type-check` - Type check without emitting files

## 📦 Dependencies

### Runtime
- **express** - Web framework
- **cors** - CORS middleware
- **yaml** - YAML parser
- **better-sqlite3** - SQLite database
- **ejs** - Template engine
- **dotenv** - Environment variables

### Development
- **typescript** - TypeScript compiler
- **ts-node-dev** - Development server with hot reload
- **eslint** - Linting
- **@typescript-eslint/** - TypeScript ESLint plugins

## 🎯 Features

### Type Safety
- Full TypeScript support
- Type definitions for all data structures
- Compile-time type checking

### Database
- SQLite with better-sqlite3
- Synchronous operations for simplicity
- WAL mode for better performance

### API Endpoints
All endpoints from Python version are available:
- `GET /api/environments` - List all environments
- `GET /api/environments/:name` - Get environment details
- `POST /api/environments/:name/deploy` - Trigger deployment
- `GET /api/environments/:name/status` - Get status
- `GET /api/environments/:name/metrics` - Get metrics
- `GET /api/environments/:name/alerts` - Get alerts
- `POST /api/alerts/:id/acknowledge` - Acknowledge alert
- `GET /api/costs` - Get cost data
- `GET /api/deployments` - List deployments
- `GET /api/deployments/:id/logs` - Get deployment logs

## 🔄 Migration from Python

### Key Changes
1. **Flask → Express**: Web framework migration
2. **sqlite3 → better-sqlite3**: Database library
3. **PyYAML → yaml**: YAML parsing
4. **Jinja2 → EJS**: Template engine (templates need minor updates)

### Template Updates Needed
Templates use EJS syntax instead of Jinja2:
- `{{ variable }}` → `<%= variable %>`
- `{% if condition %}` → `<% if (condition) { %>`
- `{% for item in items %}` → `<% items.forEach(item => { %>`

## 🐛 Troubleshooting

### Build Errors
```bash
# Clear and rebuild
rm -rf dist node_modules
pnpm install
pnpm build
```

### Database Issues
- Ensure `logs/` directory exists
- Check file permissions on database file
- Database is created automatically on first run

### Port Already in Use
```bash
# Use different port
PORT=5001 npm start
```

## 📝 Development Tips

### Type Checking
```bash
# Check types without building
npm run type-check
```

### Linting
```bash
# Fix auto-fixable issues
pnpm lint --fix
```

### Hot Reload
Development mode automatically reloads on file changes:
```bash
pnpm dev
```

## 🚀 Production Deployment

### Build for Production
```bash
pnpm build
NODE_ENV=production pnpm start
```

### Using PM2
```bash
pnpm add -g pm2
pnpm build
pm2 start dist/server.js --name orchestration-portal
```

### Docker
```dockerfile
FROM node:18-alpine
RUN corepack enable && corepack prepare pnpm@latest --activate
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile --prod
COPY . .
RUN pnpm build
EXPOSE 5000
CMD ["pnpm", "start"]
```

## 📚 Type Definitions

All types are defined in `src/types/index.ts`:
- `Environment` - Environment configuration
- `DeploymentStatus` - Deployment status data
- `Deployment` - Deployment record
- `Alert` - Alert record
- `Cost` - Cost record
- `Metrics` - Metrics data structure

## 🔐 Environment Variables

```bash
# Optional: Custom port
PORT=5000

# Optional: Custom host
HOST=0.0.0.0

# Optional: Database path (default: ../../logs/orchestration.db)
DB_PATH=/path/to/db.db
```

## ✅ Benefits of TypeScript

1. **Type Safety**: Catch errors at compile time
2. **Better IDE Support**: Autocomplete, refactoring
3. **Self-Documenting**: Types serve as documentation
4. **Refactoring**: Safe refactoring with type checking
5. **Modern JavaScript**: Use latest ES features

## 🤝 Contributing

1. Follow TypeScript best practices
2. Add types for all new data structures
3. Run `pnpm lint` before committing
4. Write self-documenting code with types

## 📄 License

Same as main project license.

