Skip to content

Runbook: Frontend Application

Version Date Author Change Description
1.0 2025-09-15 AI Assistant Initial Draft

1. Service Overview

  • Purpose: The frontend application provides the user interface for interacting with the backend services.
  • Criticality: High. A full outage will prevent users from accessing the application.
  • Owners: Frontend Team (#frontend-oncall on Slack).
  • Key Dependencies:
    • Internal: API Gateway (for all backend communication).

2. On-Call & Escalation

  • Primary On-Call: PagerDuty schedule "Frontend On-Call".
  • Escalation: If the primary on-call does not acknowledge within 15 minutes, escalate to the "Frontend Lead" PagerDuty schedule.

3. Monitoring and Alerting

  • Primary Dashboard: [Link to Grafana Dashboard for Frontend]
  • Log Location: Logs are typically collected from the browser console and sent to a central logging platform. Use the following query: service:"frontend"
  • Key Metrics:
    • page_load_time_p99: 99th percentile page load time. High values indicate performance issues.
    • js_errors_total: Total number of JavaScript errors.
    • api_request_failures_total: Number of failed API requests from the frontend.

4. How to Run Unit and Integration Tests

To run the unit and integration tests for the frontend application, navigate to the src/frontend directory and execute the following commands:

cd src/frontend
npm install
npm test

This will execute all tests defined in the project and report the results.

5. How to Build and Deploy

Building the Frontend

To build the frontend application for production, navigate to the src/frontend directory and run:

cd src/frontend
npm install
npm run build

This will generate optimized static assets in the dist directory within src/frontend.

Deploying the Frontend

The frontend application is typically deployed as static files to a content delivery network (CDN) or a web server. The deployment process is automated via CI/CD pipelines.

Manual Deployment (for emergencies or specific environments):

  1. Ensure the application is built (see "Building the Frontend" above).
  2. Copy the contents of the src/frontend/dist directory to the target web server or CDN bucket.

For automated deployments, refer to the relevant CI/CD workflow (e.g., a GitHub Actions workflow for frontend deployment, if available).

6. How to Run Locally (Dev Env)

To run the frontend application locally in a development environment:

  1. Ensure Docker Compose services are running: The frontend depends on the backend services (API Gateway and Auth Service). Make sure they are up and running using docker-compose up -d.
  2. Navigate to the frontend directory: 
    cd src/frontend
  3. Install dependencies: 
    npm install
  4. Start the development server: 
    npm run dev
    The application will typically be available at http://localhost:5173 (or another port specified in the vite.config.ts).