# 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.

- `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.

- 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

- 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.

