BanGUI/Docs/Tasks.md

Issue #27: MEDIUM - Inconsistent Error Handling Patterns

Where found:

• ban_service.py - Raises exceptions
• server_service.py - Returns defaults silently
• jail_service.py - Mixed approach

Why this is needed: Different services have different error handling contracts. Callers don't know what to expect.

Goal: Establish clear error handling contract for all services.

What to do:

1. Document error handling patterns:

   class ServiceErrorContract:
       """
       ABORT_ON_ERROR: Raise exception, let router handle
       RETURN_DEFAULT: Return empty result, log warning
       PARTIAL_RESULT: Return partial success with error list
       """
   

2. Each service method documents which pattern it follows
3. Routers handle errors consistently
4. Update service protocols

Possible traps and issues:

• Users of service must know pattern
• Switching patterns is breaking change

Docs changes needed:

• Create service development guide with error patterns

Doc references:

• DETAILED_FINDINGS.md - Issue "Inconsistent Error Handling"

---

LOWER PRIORITY ISSUES (LOW-MEDIUM)

---

Issue #28: LOW-MEDIUM - Missing Pre-Commit Hooks

Where found:

• No .pre-commit-config.yaml
• Docs mention husky but no .husky/ directory

Why this is needed: Without pre-commit hooks, developers commit code that fails linting/tests, slowing down CI.

Goal: Enforce code quality checks before commit.

What to do:

1. Create .pre-commit-config.yaml:

   repos:
     - repo: https://github.com/pre-commit/pre-commit-hooks
       hooks:
         - id: check-yaml
         - id: end-of-file-fixer
     - repo: https://github.com/astral-sh/ruff-pre-commit
       hooks:
         - id: ruff
         - id: ruff-format
   

2. Setup husky for frontend
3. Document in CONTRIBUTING.md

Docs changes needed:

• Create CONTRIBUTING.md with setup instructions

Doc references:

• DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "12.1 Missing Pre-Commit Hooks"

---

Issue #29: LOW-MEDIUM - Missing .editorconfig

Where found:

• No .editorconfig file

Why this is needed: Different developers use different editors with different default formatting, causing inconsistent code.

Goal: Enforce consistent formatting across all editors.

What to do:

1. Create .editorconfig:

   root = true
   
   [*]
   charset = utf-8
   end_of_line = lf
   insert_final_newline = true
   
   [*.py]
   indent_style = space
   indent_size = 4
   
   [*.{js,ts,tsx,jsx}]
   indent_style = space
   indent_size = 2
   

2. Add editorconfig plugin to IDE guides

Docs changes needed:

• Add to development setup instructions

Doc references:

• DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "12.3 Missing .editorconfig"

---

Issue #30: LOW-MEDIUM - IPv4-Mapped IPv6 Address Duplicates

Where found:

• backend/app/utils/ip_utils.py
• Treats "192.168.1.1" and "::ffff:192.168.1.1" as different IPs

Why this is needed: Same IP can be banned twice in different formats, causing:

• Duplicate ban logs
• Geo cache duplicates
• Analytics skewed

Goal: Normalize IP addresses to canonical form.

What to do:

1. Add normalization:

   def normalize_ip(ip_str: str) -> str:
       ip = ipaddress.ip_address(ip_str)
       # Convert IPv4-mapped IPv6 to IPv4
       if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped:
           return str(ip.ipv4_mapped)
       return str(ip)
   

2. Apply on all IP inputs (ban, import, etc.)
3. Test with various formats

Docs changes needed:

• Document IP normalization

Doc references:

• DETAILED_FINDINGS.md - Issue #22 "IPv4-Mapped IPv6"

---

Issue #31: LOW-MEDIUM - Weak Master Password Validation

Where found:

• backend/app/models/setup.py (line 22)
• Requires uppercase, digit, special char but no dictionary check

Why this is needed: Passwords can still be weak (e.g., "Password1!" is common).

Goal: Prevent common passwords.

What to do:

1. Add common passwords list or library:

   import common_passwords
   
   @field_validator("password")
   def validate_password(cls, v):
       if v.lower() in common_passwords.PASSWORDS:
           raise ValueError("Password is too common, choose another")
       return v
   

2. Test against known weak passwords

Docs changes needed:

• Document password requirements

Doc references:

• DETAILED_FINDINGS.md - Issue #23 "Weak Password Validation"

---

Issue #32: LOW-MEDIUM - Missing Accessibility Features

Where found:

• frontend/src/components/BanTable.tsx - No aria-label on table
• frontend/src/pages/HistoryPage.tsx - Button has tabIndex but no onKeyDown handler
• World map missing alt text

Why this is needed: Application not usable by screen reader users or keyboard-only navigation.

Goal: Improve accessibility to WCAG AA compliance.

What to do:

1. Add ARIA labels to major components
2. Implement keyboard navigation handlers
3. Test with screen readers
4. Check color contrast ratios

Docs changes needed:

• Add accessibility guidelines

Doc references:

• DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "11 Accessibility"

---

Issue #33: LOW - Missing Architecture Decision Records (ADRs)

Where found:

• No Docs/adr/ directory

Why this is needed: New developers don't understand architectural choices, recreate debates, make wrong assumptions.

Goal: Document important decisions and their rationale.

What to do:

1. Create Docs/adr/ directory
2. Add ADRs for major decisions:
   • Why SQLite instead of PostgreSQL?
   • Why FastAPI instead of Django?
   • Why React instead of Vue?
   • Why APScheduler instead of Celery?
   • Why single-instance scheduler?

Docs changes needed:

• Create ADR template and examples

Doc references:

• DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "8.5 Missing ADRs"

---

Issue #34: LOW - No Troubleshooting Guide

Where found:

• Missing Docs/TROUBLESHOOTING.md

Why this is needed: Users can't self-serve on common issues, create issues instead.

Goal: Document common problems and solutions.

What to do:

1. Create Docs/TROUBLESHOOTING.md with:
   • "502 Bad Gateway" - backend is down or not ready
   • "Permission denied" - database directory not writable
   • "fail2ban not found" - socket path wrong
   • "Geo lookups empty" - GeoLite2 database missing
   • "Rate limited (429)" - too many requests
2. Expand based on real user issues

Docs changes needed:

• Create comprehensive troubleshooting guide

Doc references:

• DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "8.3 No Troubleshooting"

---

Issue #35: LOW - Missing Upgrade/Migration Guide

Where found:

• No Docs/UPGRADING.md

Why this is needed: Users don't know how to safely upgrade without losing data.

Goal: Document upgrade process and breaking changes.

What to do:

1. Create Docs/UPGRADING.md with:
   • Backup procedure
   • Breaking changes for each version
   • Step-by-step upgrade procedure
   • Rollback procedure if something goes wrong

Docs changes needed:

• Create upgrade guide for each major version

Doc references:

• DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "8.5 No Migration Guide"

---

Issue #36: LOW - No Backup Strategy Documented

Where found:

• No backup procedure in deployment docs
• No automated backup in Docker Compose

Why this is needed: Users don't know how to protect their data.

Goal: Document and automate database backups.

What to do:

1. Create Docs/BACKUP_RESTORE.md
2. Add backup script to Docker
3. Document retention policy
4. Document restore procedure

Docs changes needed:

• Create backup & restore guide

Doc references:

• DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "10.4 No Backup Strategy"

---

Issue #37: LOW - Missing CONTRIBUTING.md

Where found:

• fail2ban-master/CONTRIBUTING.md is from fail2ban, not BanGUI

Why this is needed: Contributors don't know project guidelines.

Goal: Document contribution guidelines.

What to do:

1. Create CONTRIBUTING.md with:
   • Development setup
   • Branch naming conventions
   • PR requirements
   • Code style guidelines
   • Testing requirements
   • PR review process

Docs changes needed:

• Create CONTRIBUTING.md

Doc references:

• DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "12.5 No CONTRIBUTING.md"

---

Issue #38: LOW - No Test Coverage Minimum Enforced

Where found:

• backend/pyproject.toml - Coverage report generated but no minimum threshold
• CI doesn't fail on low coverage

Why this is needed: Code quality can degrade as coverage drops.

Goal: Enforce minimum test coverage.

What to do:

1. Set minimum coverage threshold in CI (e.g., 80%)
2. Fail build if coverage drops below threshold
3. Add coverage badge to README

Docs changes needed:

• Document testing requirements

Doc references:

• DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "12.6 Test Coverage Not Enforced"

---

DOCUMENTATION GAPS (Cross-Cutting)

---

Issue #39: DOCUMENTATION - Missing API Reference

Files affected: All routers

Create: Comprehensive API reference documenting:

• All endpoints
• Request/response formats
• Status codes
• Examples

References:

• DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "8.1 Missing API Documentation"

---

Issue #40: DOCUMENTATION - Missing Deployment Best Practices

Files affected: Docs/Deployment.md, Docker configuration

Create/Update:

• Security best practices
• Performance tuning
• Monitoring setup
• Scaling guidelines

References:

• DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "6 Build & Deployment"

---

Issue #41: DOCUMENTATION - Missing Database Schema Documentation

Create: Document:

• All tables and their purpose
• Relationships and constraints
• Indexes and performance notes
• Migration history

References:

• DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "1 Database Design"