BanGUI/Docs/Tasks.md

## 27) Error response body shape is inconsistent
- Where found:
	- [backend/app/main.py](backend/app/main.py)
	- [backend/app/routers](backend/app/routers)
	- [frontend/src/api/client.ts](frontend/src/api/client.ts)
- Why this is needed:
	- Frontend cannot reliably branch on machine-readable error codes.
- Goal:
	- Standard error response schema with code + detail + metadata.
- What to do:
	- Add shared error model and update handlers.
- Possible traps and issues:
	- Legacy consumers parsing detail strings may break.
- Docs changes needed:
	- Add backend error schema and mapping table.
- Doc references:
	- [Docs/Backend-Development.md](Docs/Backend-Development.md)

---

## 28) Login failure delay can enable app-layer DoS
- Where found:
	- [backend/app/routers/auth.py](backend/app/routers/auth.py#L110)
- Why this is needed:
	- Fixed 10-second await for invalid login attempts can amplify load impact.
- Goal:
	- Keep brute-force resistance without exhausting request capacity.
- What to do:
	- Replace fixed sleep with limiter-backed penalty strategy and concurrency protection.
- Possible traps and issues:
	- Too little penalty weakens brute-force protection.
- Docs changes needed:
	- Document authentication throttling strategy.
- Doc references:
	- [backend/app/utils/rate_limiter.py](backend/app/utils/rate_limiter.py)

---

## 29) Blocklist URL validation has DNS-rebinding window
- Where found:
	- [backend/app/utils/ip_utils.py](backend/app/utils/ip_utils.py#L145)
	- [backend/app/services/blocklist_service.py](backend/app/services/blocklist_service.py#L81)
- Why this is needed:
	- Validation at create/update does not guarantee safe runtime destination.
- Goal:
	- Enforce SSRF safety at connect/request time as well.
- What to do:
	- Add runtime destination/IP allow-deny validation in HTTP layer.
- Possible traps and issues:
	- Resolver/cache behavior may vary across environments.
- Docs changes needed:
	- Add blocklist network security notes and runtime checks.
- Doc references:
	- [Docs/Architekture.md](Docs/Architekture.md)
	- https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html

---

## 30) Setup persistence is non-atomic across DB contexts
- Where found:
	- [backend/app/services/setup_service.py](backend/app/services/setup_service.py)
	- [backend/app/repositories/settings_repo.py](backend/app/repositories/settings_repo.py)
- Why this is needed:
	- Partial commits during setup can leave inconsistent state.
- Goal:
	- Make setup operations transactional and crash-safe.
- What to do:
	- Introduce staged setup state and transaction boundaries.
- Possible traps and issues:
	- SQLite transaction handling across multiple DB files is limited.
- Docs changes needed:
	- Add setup state machine and rollback behavior.
- Doc references:
	- [Docs/Architekture.md](Docs/Architekture.md)

---

## 31) Fire-and-forget reschedule may fail silently
- Where found:
	- [backend/app/tasks/blocklist_import.py](backend/app/tasks/blocklist_import.py#L108)
- Why this is needed:
	- Schedule update requests can succeed while background reschedule fails.
- Goal:
	- Make schedule updates deterministic and observable.
- What to do:
	- Await reschedule path or persist task outcome status and surface errors.
- Possible traps and issues:
	- Blocking request path might add latency if scheduler is busy.
- Docs changes needed:
	- Document scheduling reliability guarantees.
- Doc references:
	- [Docs/Features.md](Docs/Features.md)

---

## 32) RateLimiter cleanup function is not scheduled/used
- Where found:
	- [backend/app/utils/rate_limiter.py](backend/app/utils/rate_limiter.py#L84)
	- [backend/app/startup.py](backend/app/startup.py)
- Why this is needed:
	- Rate limiter state can grow over long runtimes.
- Goal:
	- Ensure periodic cleanup or bounded memory strategy.
- What to do:
	- Add scheduled cleanup or auto-eviction structure.
- Possible traps and issues:
	- Cleanup cadence too frequent can add overhead.
- Docs changes needed:
	- Add operational notes for auth throttling lifecycle.
- Doc references:
	- [backend/app/utils/rate_limiter.py](backend/app/utils/rate_limiter.py)

---

## 33) Trusted proxy configuration is hardcoded in auth router
- Where found:
	- [backend/app/routers/auth.py](backend/app/routers/auth.py#L46)
	- [backend/app/utils/client_ip.py](backend/app/utils/client_ip.py)
- Why this is needed:
	- Incorrect client IP extraction can break per-IP rate limiting behind proxies.
- Goal:
	- Move trusted proxies to validated runtime config.
- What to do:
	- Add settings for trusted proxy IPs/CIDRs.
	- Validate and use these in client IP extraction.
- Possible traps and issues:
	- Over-trusting headers can enable spoofing.
- Docs changes needed:
	- Add reverse-proxy deployment configuration section.
- Doc references:
	- [Docs/Instructions.md](Docs/Instructions.md)

---

## 34) Setup redirect allowlist uses broad prefix matching
- Where found:
	- [backend/app/main.py](backend/app/main.py#L434)
- Why this is needed:
	- Prefix-based allow rules are fragile for future route additions.
- Goal:
	- Use exact path or route-level allow policy.
- What to do:
	- Replace startswith matching with explicit allowlist checks.
- Possible traps and issues:
	- API docs and setup flow paths must remain reachable.
- Docs changes needed:
	- Add setup guard route policy documentation.
- Doc references:
	- [backend/app/main.py](backend/app/main.py)

---

## 35) API client sends JSON and CSRF header for every request method
- Where found:
	- [frontend/src/api/client.ts](frontend/src/api/client.ts)
- Why this is needed:
	- Extra headers on GET increase unnecessary CORS preflights and noise.
- Goal:
	- Apply headers by method/body requirements.
- What to do:
	- Only set Content-Type for requests with JSON body.
	- Send CSRF header for mutating cookie-authenticated requests only.
- Possible traps and issues:
	- CSRF protection assumptions must still hold for all mutating paths.
- Docs changes needed:
	- Update frontend API client contract and CSRF notes.
- Doc references:
	- [backend/app/middleware/csrf.py](backend/app/middleware/csrf.py)

---

## 36) Polling continues when tab is not visible
- Where found:
	- [frontend/src/hooks/usePolledData.ts](frontend/src/hooks/usePolledData.ts#L90)
	- [frontend/src/hooks/useBlocklistStatus.ts](frontend/src/hooks/useBlocklistStatus.ts)
- Why this is needed:
	- Unnecessary backend load and client resource usage in background tabs.
- Goal:
	- Pause/reduce polling when page is hidden.
- What to do:
	- Add visibility-aware polling strategy and optional backoff.
- Possible traps and issues:
	- Data may appear stale immediately after tab restore if refresh is delayed.
- Docs changes needed:
	- Add frontend polling lifecycle policy.
- Doc references:
	- [Docs/Web-Development.md](Docs/Web-Development.md)

---

## 37) Multi-worker safety check depends on one environment variable
- Where found:
	- [backend/app/startup.py](backend/app/startup.py#L61)
- Why this is needed:
	- Other process managers can still launch multiple workers without this variable.
- Goal:
	- Enforce scheduler single-executor safety regardless of launcher.
- What to do:
	- Add robust single-run lock/leader mechanism for scheduler ownership.
- Possible traps and issues:
	- Locking strategy must be reliable in container orchestration.
- Docs changes needed:
	- Expand deployment constraints and supported run modes.
- Doc references:
	- [Docs/Architekture.md](Docs/Architekture.md)

---

## 38) History archive query paths may need explicit indexing plan
- Where found:
	- [backend/app/db.py](backend/app/db.py)
	- [backend/app/repositories/history_archive_repo.py](backend/app/repositories/history_archive_repo.py)
- Why this is needed:
	- Large archive datasets can degrade filter/sort performance.
- Goal:
	- Add indexes aligned with real query patterns.
- What to do:
	- Benchmark common history queries.
	- Add migration with targeted indexes.
- Possible traps and issues:
	- Extra indexes increase write cost and DB size.
- Docs changes needed:
	- Add DB performance/indexing section for history.
- Doc references:
	- [Docs/Backend-Development.md](Docs/Backend-Development.md)
	- https://www.sqlite.org/queryplanner.html

---

## 39) No explicit DI container strategy for backend service graph
- Where found:
	- [backend/app/dependencies.py](backend/app/dependencies.py)
	- [backend/app/services](backend/app/services)
- Why this is needed:
	- Dependency construction and lifecycle are partly implicit.
- Goal:
	- Define a clear dependency wiring pattern for services and repositories.
- What to do:
	- Create service composition root pattern and document usage.
- Possible traps and issues:
	- Over-engineering if container abstraction is too heavy for current size.
- Docs changes needed:
	- Add dependency wiring chapter.
- Doc references:
	- [Docs/Architekture.md](Docs/Architekture.md)

---

## 40) Frontend and backend observability are not aligned
- Where found:
	- [backend/app/main.py](backend/app/main.py)
	- [frontend/src](frontend/src)
- Why this is needed:
	- Backend uses structured logging while frontend error telemetry is mostly local and ad-hoc.
- Goal:
	- Define unified error telemetry and correlation approach.
- What to do:
	- Introduce frontend error reporting pipeline and request correlation IDs.
- Possible traps and issues:
	- PII/sensitive payload leakage risk in client-side telemetry.
- Docs changes needed:
	- Add observability and privacy-safe logging guidelines.
- Doc references:
	- [Docs/Architekture.md](Docs/Architekture.md)
	- [Docs/Web-Development.md](Docs/Web-Development.md)