BanGUI/CONTRIBUTING.md

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

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

---

Testing

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

# Frontend — run once
cd frontend && npm test

---

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