warehouse13/docs/FRONTEND_USAGE.md

Frontend Usage Guide

The Test Artifact Data Lake now features a modern Angular frontend with Material Design components. This guide explains how to run the application in different modes.

Quick Start Options

1. Development Mode (Recommended for Development)

Hot reload enabled, fastest for development

Linux/macOS:

./dev-start.sh

Windows:

dev-start.bat

• Backend services: http://localhost:8000
• Frontend: http://localhost:4200 (with hot reload)
• API Docs: http://localhost:8000/docs
• MinIO Console: http://localhost:9001

2. Production Mode (Complete Docker Stack)

Pre-built frontend served via Nginx

Linux/macOS:

./quickstart-build.sh

Windows: (Manual steps)

cd frontend
npm install
npm run build
cd ..
docker-compose -f docker-compose.production.yml up -d

• Complete application: http://localhost:80
• API (proxied): http://localhost:80/api/
• API Docs: http://localhost:80/docs
• MinIO Console: http://localhost:9001

3. Backend Only Mode

For API-only usage or custom frontend setup

Any platform:

./quickstart.sh    # Linux/macOS
quickstart.bat     # Windows
quickstart.ps1     # PowerShell

• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• MinIO Console: http://localhost:9001

Technical Details

Architecture

• Frontend: Angular 19 with Angular Material Design
• Backend: FastAPI with PostgreSQL and MinIO
• Development: Frontend dev server + Backend containers
• Production: Nginx serving Angular + Backend containers

Ports

• 80 - Production frontend (Nginx)
• 4200 - Development frontend (Angular dev server)
• 8000 - Backend API (FastAPI)
• 5432 - PostgreSQL database
• 9000 - MinIO storage
• 9001 - MinIO console

Development Workflow

1. Use dev-start.sh or dev-start.bat for daily development
2. Frontend changes automatically reload at http://localhost:4200
3. Backend API available at http://localhost:8000
4. Use browser dev tools for debugging

Production Deployment

1. Build frontend: npm run build in frontend/ directory
2. Use docker-compose.production.yml for complete stack
3. Nginx proxies API requests to backend
4. Static assets served efficiently by Nginx

Troubleshooting

Frontend Build Issues

If you encounter esbuild platform errors:

1. Delete frontend/node_modules
2. Run npm install in frontend/ directory
3. Try the development mode first: ./dev-start.sh

Port Conflicts

• Development: Change Angular port in angular.json
• Production: Modify docker-compose.production.yml ports

Docker Issues

• Ensure Docker Desktop is running
• Try docker-compose down and restart
• Check logs: docker-compose logs -f api

Features

• Modern Material Design interface
• Responsive design for mobile/tablet
• File upload with drag-and-drop
• Advanced search and filtering
• Tag management system
• Real-time notifications
• Data visualization
• Export capabilities