---
description: Debug a failing service or endpoint (identify root cause, fix, test)
---

## Debug a Service

Follow these steps to diagnose and fix a failing service or endpoint.

### 1. Identify the failing service

Check which service is affected:
- Backend API (Python/FastAPI) → `backend/src/`
- Platform Service (Fastify) → `../learning_ai_common_plat/services/platform-service/src/`
- Extraction Service (Fastify) → `../learning_ai_common_plat/services/extraction-service/src/`
- Admin Dashboard (Next.js) → `../learning_ai_common_plat/dashboards/admin-web/src/`
- User Dashboard (Next.js) → `user-dashboard-web/src/`
- Tracker Dashboard (Next.js) → `../learning_ai_common_plat/dashboards/tracker-web/src/`

### 2. Check health

// turbo
Run `curl -s http://localhost:8000/health && curl -s http://localhost:4003/health && curl -s http://localhost:4005/health`

### 3. Check logs

For local dev:
// turbo
Run `tail -50 .logs/backend.log .logs/platform-service.log 2>/dev/null | head -100`

For Docker:
```bash
docker compose logs --tail=50 <service-name>
```

### 4. Reproduce the issue

- For API errors: use `curl` with verbose output (`curl -v`)
- For UI errors: check browser console + network tab
- For test failures: run the specific test with `-v -x` (Python) or `--reporter=verbose` (Vitest)

### 5. Fix methodology

1. **Read the test first** — understand what it expects
2. **Read the source** — trace the code path
3. **Fix the source, NOT the test** (unless the test is wrong)
4. **Add a regression test** if none exists
5. **Run the full test suite** to ensure no regressions

### 6. Verify fix

// turbo
Run `python -m pytest tests/ backend/tests/ -v --tb=short -x`

For TypeScript services:
```bash
cd ../learning_ai_common_plat && pnpm --filter @lysnrai/<service-name> test
```

### 7. Commit

Use format: `fix(<scope>): <description>`

Example: `fix(billing): handle null subscription in usage endpoint`
