BanGUI/Docs/Tasks.md

BanGUI — Task List

This document breaks the entire BanGUI project into development stages, ordered so that each stage builds on the previous one. Every task is described in prose with enough detail for a developer to begin work. References point to the relevant documentation.

Reference: Docs/Refactoring.md for full analysis of each issue.

---

Open Issues

Backend Architecture Review Findings

• Status: done — backend/app/routers/config.py now uses explicit dependency injection for fail2ban settings and no longer reads request.app.state.settings directly.

• Status: done — backend/app/routers/config.py now uses an explicit AppState dependency for pending recovery and activation state instead of writing request.app.state directly.

• Status: done — backend/app/routers/* often reads config directly from request.app.state.settings instead of using dependency injection. This bypasses the dependency layer and creates hidden coupling between routers and application state.

  • Fix: replace direct request.app.state.settings access with SettingsDep or other explicit dependencies such as ServerStatusDep and PendingRecoveryDep in router function signatures.
  • Expected outcome: routers become easier to unit test, composition is more explicit, and shared state access is only available through documented FastAPI dependencies.

• Status: done — Several utility modules under backend/app/utils/ import service layer code (app.services.*). Utilities should remain low-level helpers and not depend on higher-level service logic.

  • Fix: move service-dependent helpers into app/services/ or extract shared logic into a new app/helpers/ layer, keeping app/utils/ purely independent.
  • Expected outcome: lower coupling between utility and service layers, cleaner dependency direction, and better maintainability.

• Status: done — background task modules in backend/app/tasks/ no longer rely on the dead app.state.db fast-path and now open/close dedicated task-local DB connections using app.state.settings.database_path.

  • Fix: remove the unused app.state.db branch and always open/close a dedicated task-local connection, or intentionally add a shared DB connection to app.state and manage its lifecycle.
  • Expected outcome: background jobs have predictable DB lifecycle, avoid hidden bugs from stale connection assumptions, and task code is simpler.

• backend/app/dependencies.py contains an in-memory process-local session cache for auth tokens. This optimization is valid for a single-process server, but it is not cluster-safe for multi-worker or distributed deployments.

  • Fix: either document the single-process limitation clearly, or replace _session_cache with an external shared cache (Redis/Memcached) or eliminate it if eventual cluster support is required.
  • Expected outcome: authentication behavior is consistent across deployment modes, and session invalidation works correctly in multi-worker setups.

• backend/app/main.py uses local imports inside _lifespan() to avoid circular dependencies, indicating that startup logic is tightly coupled with services.

  • Fix: evaluate whether the startup initialization can be moved into a dedicated startup.py or split service initialization into smaller modules; keep import order simple and explicit.
  • Expected outcome: cleaner startup code with lower coupling, fewer hidden circular import risks, and easier maintenance.

Recommended refactors for an AI agent

• Status: done — Standardise dependency injection in routers by using SettingsDep, ServerStatusDep, PendingRecoveryDep, and other dependency definitions from backend/app/dependencies.py.
• Refactor backend/app/utils/ so it does not import business-layer services. Move cross-layer helpers to the appropriate layer or introduce a shared helper package if needed.
• Simplify background task DB management in backend/app/tasks/: remove the dead app.state.db logic or implement a real shared connection and document its lifecycle.
• Document auth cache semantics in the code and project docs. If cluster deployments are intended, replace the process-local cache with a shared cache or remove it.
• Inspect backend/app/main.py startup wiring and reduce local import usage by extracting startup responsibilities into clearer components.

Goals and expectations for the fix

• Preserve existing functionality while reducing hidden coupling.
• Improve testability of routers and background tasks by making dependencies explicit.
• Make the application startup and shared-state behavior easy to reason about.
• Ensure backend architecture is stable for future refactors, especially around authentication, config handling, and scheduled jobs.
• Provide enough detail so an AI agent can make the changes safely without altering business behavior.