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

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

---

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