BanGUI/Docs/Tasks.md

22) Magic strings are scattered in frontend storage keys

• Where found:
  • frontend/src/providers/AuthProvider.tsx
  • frontend/src/layouts/MainLayout.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

---

23) No global cancellation policy on route transitions

• Where found:
  • 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

---

24) API response wrapper shape is inconsistent

• Where found:
  • backend/app/routers/dashboard.py
  • backend/app/routers/jails.py
  • 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

---

25) No canonical snake_case/camelCase serialization policy

• Where found:
  • backend/app/models/server.py
  • 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
  • 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/history.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

---

27) Error response body shape is inconsistent

• Where found:
  • backend/app/main.py
  • backend/app/routers
  • 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

---

28) Login failure delay can enable app-layer DoS

• Where found:
  • backend/app/routers/auth.py
• 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

---

29) Blocklist URL validation has DNS-rebinding window

• Where found:
  • backend/app/utils/ip_utils.py
  • backend/app/services/blocklist_service.py
• 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
  • 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/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

---

31) Fire-and-forget reschedule may fail silently

• Where found:
  • backend/app/tasks/blocklist_import.py
• 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

---

32) RateLimiter cleanup function is not scheduled/used

• Where found:
  • backend/app/utils/rate_limiter.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

---

33) Trusted proxy configuration is hardcoded in auth router

• Where found:
  • backend/app/routers/auth.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

---

34) Setup redirect allowlist uses broad prefix matching

• Where found:
  • backend/app/main.py
• 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

---

35) API client sends JSON and CSRF header for every request method

• Where found:
  • 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

---

36) Polling continues when tab is not visible

• Where found:
  • frontend/src/hooks/usePolledData.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

---

37) Multi-worker safety check depends on one environment variable

• Where found:
  • backend/app/startup.py
• 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

---

38) History archive query paths may need explicit indexing plan

• Where found:
  • backend/app/db.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
  • https://www.sqlite.org/queryplanner.html

---

39) No explicit DI container strategy for backend service graph

• Where found:
  • backend/app/dependencies.py
  • 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

---

40) Frontend and backend observability are not aligned

• Where found:
  • backend/app/main.py
  • 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/Web-Development.md