# Frontend White Screen Analysis - 2026-06-07

## Summary

The `app.servicefinder.hu` page was loading as a blank/white screen.
**Root cause:** Missing `flag-icons` npm package inside the frontend container.

---

## 1. Investigation Steps

### 1.1 Docker Container Status
- `sf_public_frontend`: **Up** (running)
- `sf_api`: **Up** (running)
- Backend API reachable: `localhost:8000/api/v1/health` → responds

### 1.2 Frontend Container Logs
**Primary error (repetitive):**
```
[vite] Internal server error: Failed to resolve import "flag-icons/css/flag-icons.css" from "src/main.ts". Does the file exist?
  File: /app/src/main.ts:13:7
  11 |  import sk from "./i18n/sk";
  12 |  import "./assets/main.css";
  13 |  import "flag-icons/css/flag-icons.css";
     |          ^
```

### 1.3 Critical File Verification (all exist)
- `frontend/src/components/Logo.vue` - Exists
- `frontend/src/stores/vehicle.ts` - Exists
- `frontend/src/views/organization/CompanyOnboardingView.vue` - Exists
- `frontend/src/views/organization/CompanyGarageView.vue` - Exists

### 1.4 Dependency Check
- `frontend/package.json` contains `"flag-icons": "^7.5.0"` - OK
- Container `/app/node_modules/flag-icons`: **MISSING** - FAIL

---

## 2. Root Cause Analysis

### 2.1 System Architecture
From `docker-compose.yml:302-318`:
```yaml
sf_public_frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile.dev
    volumes:
      - ./frontend:/app
      - /app/node_modules    # Anonymous volume isolates node_modules
```

From `frontend/Dockerfile.dev:10`:
```dockerfile
RUN npm install   # Runs at BUILD time
```

### 2.2 Failure Mechanism
1. `flag-icons` was added to `package.json` (and `package-lock.json` updated)
2. The container was **not rebuilt** after the package.json change
3. The anonymous volume (`/app/node_modules`) **preserved the old node_modules state**
4. Since volumes take precedence over `COPY`/`RUN` instructions, `npm install` never ran
5. Vite couldn't find `flag-icons/css/flag-icons.css` at startup
6. Result: **Internal server error** → **White screen**

---

## 3. Fix Applied

### 3.1 Install Package Inside Container
```bash
docker exec sf_public_frontend npm install
```
Result: `added 6 packages, changed 15 packages, and audited 281 packages`

### 3.2 Restart Vite Dev Server
```bash
docker compose restart sf_public_frontend
```
Result: `VITE v5.4.21  ready in 341 ms` - **running without errors**

---

## 4. Secondary Observations (non-blocking)

### 4.1 ProfileView Address Display Issue
In `frontend/src/views/ProfileView.vue:370-382`, the read-only view uses:
```vue
<template v-if="person?.address?.address_zip || person?.address?.address_city">
```
This references a **nested** `address` object, but the new backend format sends address fields **flat** (e.g., `person.address_zip`, not `person.address.address_zip`). The edit mode correctly uses flat `editForm.address_zip`.

**Recommendation:** Change read-only display from `person?.address?.address_*` to `person?.address_*`.

### 4.2 Circular Dependency (safe)
- `router/index.ts` dynamically imports `stores/auth` in `beforeEach` guard
- `stores/auth.ts` statically imports `router`
- This is **safe** because the dynamic import runs only on navigation events, after the router is fully initialized.

---

## 5. Prevention Recommendations

### 5.1 Future Prevention
1. **Rebuild trigger**: When `package.json` changes, always rebuild the image:
   ```bash
   docker compose up -d --build sf_public_frontend
   ```
2. **Pre-start npm install**: Modify `CMD` to run `npm install` before starting:
   ```dockerfile
   CMD npm install && npm run dev -- --host 0.0.0.0
   ```
3. **Anonymous volume awareness**: The anonymous volume preserves old node_modules. When package.json changes, rebuild the container, don't just restart.