BanGUI/Docs/Tasks.md

## 21) Silent auth error swallow in fetch error utility
- Where found:
	- [frontend/src/utils/fetchError.ts](frontend/src/utils/fetchError.ts)
- Why this is needed:
	- Silent return can drop actionable errors when no auth handler is registered.
- Goal:
	- Ensure auth errors are handled deterministically with fallback logging/handling.
- What to do:
	- Enforce handler registration or fallback behavior.
- Possible traps and issues:
	- Duplicate redirect flows if multiple auth handlers exist.
- Docs changes needed:
	- Add auth error handling contract for utilities.
- Doc references:
	- [frontend/src/providers/AuthProvider.tsx](frontend/src/providers/AuthProvider.tsx)

---

## 22) Magic strings are scattered in frontend storage keys
- Where found:
	- [frontend/src/providers/AuthProvider.tsx](frontend/src/providers/AuthProvider.tsx)
	- [frontend/src/layouts/MainLayout.tsx](frontend/src/layouts/MainLayout.tsx)
	- [frontend/src/providers/ThemeProvider.tsx](frontend/src/providers/ThemeProvider.tsx)
- Why this is needed:
	- Repeated literals invite drift and typo regressions.
- Goal:
	- Centralize user/session/local storage keys.
- What to do:
	- Consolidate into a single constants module.
- Possible traps and issues:
	- Existing tests may assume current literal values.
- Docs changes needed:
	- Add storage key registry note.
- Doc references:
	- [frontend/src/utils/constants.ts](frontend/src/utils/constants.ts)

---

## 23) No global cancellation policy on route transitions
- Where found:
	- [frontend/src/hooks](frontend/src/hooks)
- Why this is needed:
	- Many hooks cancel individually, but route-wide cancellation remains inconsistent.
- Goal:
	- Provide a global request lifecycle cancellation mechanism.
- What to do:
	- Introduce navigation-aware cancellation context/manager.
- Possible traps and issues:
	- Over-cancel can break long-lived background fetches unintentionally.
- Docs changes needed:
	- Add request lifecycle policy.
- Doc references:
	- [Docs/Web-Development.md](Docs/Web-Development.md)

---

## 24) API response wrapper shape is inconsistent
- Where found:
	- [backend/app/routers/dashboard.py](backend/app/routers/dashboard.py)
	- [backend/app/routers/jails.py](backend/app/routers/jails.py)
	- [frontend/src/types](frontend/src/types)
- Why this is needed:
	- Inconsistent payload envelopes increase frontend branching and integration bugs.
- Goal:
	- Define and enforce a consistent response envelope policy.
- What to do:
	- Standardize endpoint response forms.
	- Align frontend typing and parsing strategy.
- Possible traps and issues:
	- Breaking contract for existing clients.
- Docs changes needed:
	- Add API response style guide.
- Doc references:
	- [Docs/Backend-Development.md](Docs/Backend-Development.md)

---

## 25) No canonical snake_case/camelCase serialization policy
- Where found:
	- [backend/app/models/server.py](backend/app/models/server.py)
	- [frontend/src/types/server.ts](frontend/src/types/server.ts)
- Why this is needed:
	- Naming convention drift causes brittle frontend-backend contracts.
- Goal:
	- Enforce one API field naming policy.
- What to do:
	- Configure model aliasing strategy and update frontend contracts.
- Possible traps and issues:
	- Partial migration can leave mixed payload formats.
- Docs changes needed:
	- Add naming convention section for API fields.
- Doc references:
	- [Docs/Backend-Development.md](Docs/Backend-Development.md)
	- https://docs.pydantic.dev/latest/concepts/alias/

---

## 26) Pagination contract is not standardized across endpoints
- Where found:
	- [backend/app/routers/dashboard.py](backend/app/routers/dashboard.py)
	- [backend/app/routers/history.py](backend/app/routers/history.py)
	- [backend/app/routers/blocklist.py](backend/app/routers/blocklist.py)
- Why this is needed:
	- Different pagination patterns increase frontend complexity.
- Goal:
	- Use one shared paginated response model.
- What to do:
	- Introduce common pagination schema and query parameter policy.
- Possible traps and issues:
	- Existing endpoint consumers may require transition period.
- Docs changes needed:
	- Add pagination API spec.
- Doc references:
	- [Docs/Backend-Development.md](Docs/Backend-Development.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)