# 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

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

```bash
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):

```bash
pip install pre-commit
pre-commit install
```

**Frontend** (husky, TypeScript validation):

```bash
cd frontend && npm install
npx husky install
```

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

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

```bash
# 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`:

```python
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](Docs/Instructions.md) — Agent operating rules
- [Backend-Development.md](Docs/Backend-Development.md) — Backend conventions
- [Web-Development.md](Docs/Web-Development.md) — Frontend conventions
- [Features.md](Docs/Features.md) — Complete feature list
- [Architekture.md](Docs/Architekture.md) — System architecture