Contributing to BanGUI

Welcome! This guide covers everything you need to know to set up your dev environment, understand the codebase, and submit changes.

Dev Setup

1 — Clone and init

git clone <repo-url>
cd BanGUI
cp .env.example .env
python -c 'import secrets; print(secrets.token_hex(32))'
# paste output as BANGUI_SESSION_SECRET in .env

2 — Start the stack

make up

Backend: http://127.0.0.1:8000 · Frontend (Vite proxy): http://127.0.0.1:5173

3 — Editor Setup

Install EditorConfig plugin for your IDE. Ensures consistent formatting (indent style, line endings) across all editors.

IDE	Plugin
VS Code	EditorConfig (ms-vscode.editorconfig)
PyCharm / IntelliJ	Built-in (enable in Settings → Editor → Code Style)
Vim / Neovim	editorconfig-vim
Sublime Text	EditorConfig

4 — Pre-commit hooks

Backend (pre-commit, all languages):

pip install pre-commit
pre-commit install

Frontend (husky, TypeScript validation):

cd frontend && npm install
npx husky install

Hooks run automatically on every git commit. To run manually:

pre-commit run --all-files        # backend hooks
cd frontend && npm run validate:types  # frontend type check

Project Structure

BanGUI/
├── backend/          Python FastAPI app
│   └── app/
│       ├── routers/  HTTP endpoint handlers
│       ├── services/ Business logic
│       ├── repos/   Data access
│       ├── models/   Pydantic request/response/domain models
│       └── utils/   Shared helpers
├── frontend/         React + TypeScript + Fluent UI v9
│   └── src/
│       ├── pages/   Route-level page components
│       ├── components/  Reusable UI components
│       ├── hooks/   Custom React hooks
│       └── types/   Shared TypeScript types
├── Docs/             Architecture, design, and feature documentation
└── Docker/           Container compose files

Code Quality

Tool	Scope	Command
`ruff`	Backend linting	`cd backend && ruff check .`
`ruff-format`	Backend formatting	`cd backend && ruff format .`
`mypy --strict`	Backend type checking	`cd backend && mypy --strict app`
`tsc --noEmit`	Frontend type checking	`cd frontend && tsc --noEmit`
`eslint`	Frontend linting	`cd frontend && eslint src`
`prettier --check`	Frontend formatting	`cd frontend && prettier --check src`
`import-linter`	Layer boundary enforcement	`cd backend && linter`

All checks must pass before committing. CI runs the same suite.

Testing

# Backend
cd backend && pytest --cov=app --cov-report=term-missing

# Coverage threshold: 80%. Build fails if coverage drops below.

The CI pipeline enforces the same 80% minimum coverage threshold.

Security Rules

Never echo raw user input in error messages

User-supplied values (jail names, filter names, action names, IPs, filenames, etc.) MUST be sanitized before interpolation into any string that may be rendered in an HTML context (error messages, admin UI, email notifications).

Use the sanitize_for_display() helper from app.utils.display_sanitizer:

from app.utils.display_sanitizer import sanitize_for_display

# Good: sanitized before display
super().__init__(f"Jail not found: {sanitize_for_display(name)!r}")

# Bad: raw user input echoed — XSS vector if rendered as HTML
super().__init__(f"Jail not found: {name!r}")

This rule applies even when the value has been validated: validation checks the format, not the rendering context. JSON API responses do NOT need sanitization (JSON is not HTML); apply it only at HTML render boundaries.

Stack

Layer	Stack
Backend	Python 3.12+, FastAPI, Pydantic v2, aiosqlite, structlog
Frontend	TypeScript, React, Fluent UI v9, Vite
Container	Docker Compose (development + production)

Key Docs

Instructions.md — Agent operating rules
Backend-Development.md — Backend conventions
Web-Development.md — Frontend conventions
Features.md — Complete feature list
Architekture.md — System architecture

4.3 KiB Raw Blame History