# Repository Guidelines

## Project Structure & Module Organization

The main Python modules live in the repository root. `server.py` contains the asyncio TCP server, request handlers, rate limiting, and upload flows. `chat_core.py` holds shared client logic, crypto workflows, and local key handling. `client.py` is the CLI, `gui_client.py` is the PyQt6 GUI, `db.py` is the MySQL layer, `protocol.py` defines the newline-delimited JSON protocol, and `crypto_utils.py` contains X3DH, Double Ratchet, Sender Keys, and local encryption helpers. Use `schema.sql` for a clean database bootstrap. Security and architecture notes are tracked in `SECURITY_AUDIT.md`, `README.md`, `scaling.md`, and `CLAUDE.md`. Put new test tooling under `tests/`. Treat `zaloha/` as archive code, not an active source directory.

## Build, Test, and Development Commands

Use the project virtualenv and MySQL schema:

```bash
.venv/bin/pip install -r requirements.txt
mysql -u <user> -p < schema.sql
.venv/bin/python server.py
.venv/bin/python client.py
.venv/bin/python gui_client.py
```

For quick validation, run:

```bash
.venv/bin/python -m py_compile server.py chat_core.py client.py gui_client.py db.py
.venv/bin/python tests/pentest_client.py --server-host <tls-host> --member-email ... --peer-email ... --outsider-email ...
```

There is no full `pytest` suite yet; current regression coverage is mainly protocol-level through `tests/pentest_client.py`.

## Coding Style & Naming Conventions

Follow existing Python conventions: 4-space indentation, `snake_case` for functions and variables, `PascalCase` for classes, and type hints on new or changed code. Keep handlers non-blocking: DB, file, or SMTP work that can block should be moved behind async helpers or `asyncio.to_thread()`. Reuse central validation helpers instead of duplicating checks, and keep logs free of secrets, emails, or raw user-controlled text where possible.

## Testing Guidelines

Add tests in `tests/` with descriptive names. Prefer `test_<feature>.py` for focused checks and `<scenario>_client.py` for protocol or penetration probes. Every security fix should include a regression path that covers malformed input, authorization, replay, rate limiting, or multi-device behavior.

## Commit & Pull Request Guidelines

Git history is not available in this workspace snapshot, so use short imperative commit messages. Conventional Commit style is preferred, for example `fix: reject invalid ratchet headers`. PRs should summarize behavior changes, mention schema or `.env` updates, link related issues, and include CLI or GUI evidence for user-visible changes.

## Security & Configuration Tips

Do not commit `.env`, TLS private keys, uploaded files, or local key material from `~/.encrypted_chat/`. When testing TLS, remember that `0.0.0.0` is a server bind address, not a valid client hostname. Use a host or IP that matches the certificate SAN or CN.