Worker Frontend

Worker Frontend Knowledge

Repository

GitLab (Source of Truth)

• IMPORTANT: Name is flowmaster-frontend-nextjs (not frontend-nextjs)

GitHub (Public Mirror)

• Org: HCB-Consulting-ME
• Access: Standard SSH or HTTPS (no special credentials needed)

Local Clone

• Location: ~/projects/flowmaster/repos/flowmaster-frontend-nextjs/
• Branch: typically main or develop

Tech Stack

• Framework: Next.js 15 with App Router (NOT Pages Router)
• Language: TypeScript
• CSS: Tailwind CSS
• UI Components: shadcn/ui
• Package Manager: npm or yarn

Directory Structure

src/
├── app/              # Next.js app routes (pages)
│   ├── page.tsx
│   ├── dashboard/
│   └── [dynamic]/
├── features/         # Domain-specific logic (components, hooks, utils)
│   ├── processes/
│   ├── workflows/
│   └── auth/
├── components/       # Shared UI components
│   └── ui/          # shadcn/ui components
└── lib/             # Utilities (API clients, helpers)

Development

Local Development

cd ~/projects/flowmaster/repos/flowmaster-frontend-nextjs/
npm install
npm run dev
# Opens on http://localhost:3000

Build

npm run build

Lint & Format

npm run lint
npm run format

Docker Build and Deployment

Build Docker Image

docker build --platform linux/amd64 \
  -t localhost:30500/flowmaster/frontend-nextjs:<tag> \
  --build-arg API_GATEWAY_URL=http://api-gateway:9000 \
  .

Push to K3S Registry

docker push localhost:30500/flowmaster/frontend-nextjs:<tag>

Deploy to K3S

ssh dev-01-root "kubectl set image -n flowmaster \
  deploy/frontend \
  frontend=localhost:30500/flowmaster/frontend-nextjs:<tag>"

Build Arguments

These are passed during Docker build and embedded in the image:

• API_GATEWAY_URL: http://api-gateway:9000 (K8S internal URL, not used by browser)
• NEXT_PUBLIC_API_URL: (empty) — Browser uses Nginx /api/ proxy
• NEXT_PUBLIC_WS_URL: ws://<server-ip>/ws (WebSocket URL for real-time features — get IP from commander-mcp)
• NEXT_PUBLIC_NODE_ENV: production (or development)

Build Argument Sources

• .gitlab-ci.yml - Defines all build args for CI/CD
• deploy-demo-template.yml - Kubernetes deployment template with DOCKER_BUILD_ARGS variable

K3S Deployment

Deployment Details

• Service: frontend
• Port: 3000 (Next.js internal)
• Namespace: flowmaster
• imagePullPolicy: Always

Check Deployment Status

ssh dev-01-root "kubectl -n flowmaster get deploy frontend"
ssh dev-01-root "kubectl -n flowmaster describe deploy frontend"

View Logs

ssh dev-01-root "kubectl logs -n flowmaster deploy/frontend --tail=50"

Check Health

ssh dev-01-root "kubectl exec -n flowmaster deploy/frontend -- wget -qO- http://localhost:3000/"

Authentication

Authentication Flow

1. User enters credentials on login page
2. Frontend sends request to /api/v1/auth/login
3. Gateway routes to auth-service
4. Token returned and stored in browser session/localStorage

Note: Login page shows admin@flowmaster.dev but API gateway may use admin@flowmaster.ai - this is a known mismatch.

Nginx Configuration

Frontend is accessed via:

• Route: / (root path)
• Nginx proxy: frontend ClusterIP (look up live via kubectl -n flowmaster get svc)
• Config file: /etc/nginx/sites-enabled/flowmaster

API Integration

API Routes in Frontend

All API calls use /api/ prefix:

// In frontend code
const response = await fetch('/api/v1/processes');

// Browser sends: GET /api/v1/processes
// Nginx routes to: api-gateway:9000/api/v1/processes
// Gateway routes to: process-design:9003/api/v1/processes

WebSocket Connection

const ws = new WebSocket('ws://<server-ip>/ws');

Common Issues

Build Fails

• Check npm install succeeds locally
• Verify build args are passed to docker build
• Check Docker platform matches (linux/amd64)

Page Not Loading

• Verify Nginx is routing to the correct frontend ClusterIP
• Check frontend pod is running: kubectl -n flowmaster get pods | grep frontend
• Check frontend logs: kubectl logs -n flowmaster deploy/frontend

API Not Responding

• Verify Nginx /api/ route works: Check /etc/nginx/sites-enabled/flowmaster
• Verify API Gateway is running: kubectl -n flowmaster get pods | grep api-gateway
• Check Gateway logs: kubectl logs -n flowmaster deploy/api-gateway

Key Facts

• Repository name on GitLab is flowmaster-frontend-nextjs (critical)
• Uses Next.js 15 App Router (modern, not legacy Pages)
• API calls use /api/ prefix proxied through Nginx
• WebSocket uses ws:// to websocket-gateway service
• ClusterIPs are dynamic (look them up live if services are recreated)
• Build args control environment at Docker build time
• No sensitive data in frontend code (auth tokens in browser storage/session)

For live credentials, ClusterIPs, and build args, use commander-mcp: get_credential("admin"), get_context_services