smom-dbis-138/orchestration/portal/FRONTEND_SETUP.md

Frontend Setup - Vue, React & TailwindCSS

🎨 Modern Frontend Stack

The orchestration portal now includes:

• ✅ Vue.js 3 - Progressive JavaScript framework
• ✅ React 18 - UI library (alternative option)
• ✅ TailwindCSS 3 - Utility-first CSS framework
• ✅ Vite - Next-generation frontend build tool

📁 Project Structure

orchestration/portal/
├── client/                    # Frontend application
│   ├── index.html            # Entry HTML
│   └── src/
│       ├── main.ts           # Main entry point
│       ├── styles/
│       │   └── main.css      # TailwindCSS styles
│       ├── types/            # Shared TypeScript types
│       ├── vue/              # Vue.js implementation
│       │   ├── App.vue
│       │   ├── router/
│       │   ├── views/
│       │   └── components/
│       └── react/            # React implementation
│           ├── App.tsx
│           ├── views/
│           └── components/
├── vite.config.ts            # Vite configuration
├── tailwind.config.js        # TailwindCSS configuration
└── postcss.config.js         # PostCSS configuration

🚀 Quick Start

Development Mode

# Start both server and client with hot reload
pnpm dev

# Or start separately:
pnpm dev:server  # Express server on :5000
pnpm dev:client  # Vite dev server on :5173

Production Build

# Build both server and client
pnpm build

# Or build separately:
pnpm build:server  # TypeScript compilation
pnpm build:client  # Vite build

🎯 Framework Selection

Using Vue (Default)

The default implementation uses Vue.js. Edit client/src/main.ts:

// Vue version (default)
import { createApp } from 'vue';
import App from './vue/App.vue';
import router from './vue/router';
import './styles/main.css';

const app = createApp(App);
app.use(router);
app.mount('#app');

Using React (Alternative)

To switch to React, edit client/src/main.ts:

// React version
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './react/App';
import './styles/main.css';

ReactDOM.createRoot(document.getElementById('app')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

🎨 TailwindCSS

Configuration

TailwindCSS is configured in tailwind.config.js with:

• Custom primary color palette
• Form and typography plugins
• Content paths for Vue and React files

Usage

Use Tailwind classes directly in components:

<!-- Vue -->
<div class="bg-primary-500 text-white p-4 rounded-lg">
  Content
</div>

{/* React */}
<div className="bg-primary-500 text-white p-4 rounded-lg">
  Content
</div>

Custom Components

Pre-defined component classes in client/src/styles/main.css:

• .btn, .btn-primary, .btn-secondary
• .card, .stat-card
• .status-badge with variants

📦 Dependencies

Production

• vue@^3.4.21 - Vue.js framework
• vue-router@^4.3.0 - Vue routing
• react@^18.3.1 - React library
• react-dom@^18.3.1 - React DOM
• react-router-dom@^6.22.3 - React routing

Development

• vite@^5.1.4 - Build tool
• @vitejs/plugin-vue@^5.0.4 - Vue plugin
• @vitejs/plugin-react@^4.2.1 - React plugin
• tailwindcss@^3.4.1 - CSS framework
• autoprefixer@^10.4.18 - CSS post-processor
• postcss@^8.4.35 - CSS transformer
• @tailwindcss/forms@^0.5.7 - Form styles
• @tailwindcss/typography@^0.5.13 - Typography plugin
• concurrently@^8.2.2 - Run multiple commands

🔧 Development Workflow

1. Start Development

pnpm dev

This starts:

• Express server on http://localhost:5000
• Vite dev server on http://localhost:5173

2. Access Application

• Frontend (Vite): http://localhost:5173
• Backend API: http://localhost:5000/api
• EJS Templates (fallback): http://localhost:5000

3. Hot Module Replacement

Both Vue and React support HMR:

• Edit Vue components → Auto-reload
• Edit React components → Auto-reload
• Edit CSS → Auto-reload

🏗️ Build Process

Development Build

pnpm dev

• TypeScript compiled on-the-fly
• Vite serves with HMR
• No optimization

Production Build

pnpm build

This runs:

1. tsc - Compile TypeScript server code
2. vite build - Build and optimize frontend

Output:

• dist/server.js - Compiled server
• dist/client/ - Optimized frontend assets

🎯 Features

Vue Implementation

• ✅ Vue 3 Composition API
• ✅ Vue Router for navigation
• ✅ TypeScript support
• ✅ Component-based architecture

React Implementation

• ✅ React 18 with hooks
• ✅ React Router for navigation
• ✅ TypeScript support
• ✅ Component-based architecture

Shared Features

• ✅ TailwindCSS styling
• ✅ Responsive design
• ✅ Type-safe API calls
• ✅ Real-time data updates
• ✅ Modern UI components

📝 Component Examples

Vue Component

<template>
  <div class="card">
    <h2>{{ title }}</h2>
    <button @click="handleClick" class="btn btn-primary">
      Click me
    </button>
  </div>
</template>

<script setup lang="ts">
defineProps<{ title: string }>();
const emit = defineEmits<{ click: [] }>();

const handleClick = () => {
  emit('click');
};
</script>

React Component

import React from 'react';

interface Props {
  title: string;
  onClick: () => void;
}

const Component: React.FC<Props> = ({ title, onClick }) => {
  return (
    <div className="card">
      <h2>{title}</h2>
      <button onClick={onClick} className="btn btn-primary">
        Click me
      </button>
    </div>
  );
};

export default Component;

🔄 API Integration

Both frameworks use the same API endpoints:

// Fetch environments
const response = await fetch('/api/environments');
const environments = await response.json();

// Deploy to environment
await fetch(`/api/environments/${name}/deploy`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ strategy: 'blue-green', version: 'latest' }),
});

🎨 Styling Guide

TailwindCSS Classes

<!-- Layout -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">

<!-- Colors -->
<div class="bg-primary-500 text-white">

<!-- Spacing -->
<div class="p-4 m-2">

<!-- Responsive -->
<div class="text-sm md:text-base lg:text-lg">

Custom Components

Use pre-defined classes:

• .btn, .btn-primary, .btn-secondary
• .card, .stat-card
• .status-badge, .status-badge.healthy

🚀 Deployment

Build for Production

pnpm build

Serve Production Build

NODE_ENV=production pnpm start

The server will:

• Serve API at /api/*
• Serve built frontend at /*
• Fallback to index.html for SPA routing

📚 Resources

• Vue.js Documentation
• React Documentation
• TailwindCSS Documentation
• Vite Documentation

🎉 Next Steps

1. Choose Framework: Vue (default) or React
2. Customize Components: Edit components in client/src/vue/ or client/src/react/
3. Add Features: Create new views and components
4. Style with Tailwind: Use utility classes or extend theme
5. Build & Deploy: Run pnpm build for production

---

Status: ✅ Vue, React, and TailwindCSS integrated and ready!