# STANDARDS.md — Code Quality & Conventions

Global defaults. Project code wins when it already establishes a pattern.

**Project `SOUL.md` overrides `STANDARDS.md` for UI/UX scope** (e.g. desktop-first vs. mobile-first, polish level, tone). Name conflicts in `AGENTS.md ack`.

---

## Top Principles

1. **Sanitize input** — treat all external data as hostile
2. **KISS** — simplest solution that works
3. **Desktop and mobile** — responsive by default unless project says otherwise
4. **Human-readable** — code and UI copy should be clear to humans
5. **Coding standards** — follow language/community conventions; match existing project style

---

## Priority Ranking

When trade-offs conflict, prefer in this order:

1. Sound long-term architecture
2. Readability
3. Performance
4. Consistency with existing code
5. Minimal diff size

---

## Stack Preferences

| Area | Preference |
|------|------------|
| Scripting (simple file ops, glue) | Shell > Python |
| Greenfield backend / tooling | Python > Node > PHP |
| Frontend SPA / PWA | React/Vite when project needs it — not default for every app |
| Containers | Always use `compose.yml` (Docker Compose) |
| Python | Always work inside a `venv` |
| OS (local) | Arch Linux — desktop + laptop |
| OS (server) | Debian 12 on `boka` — see `INFRASTRUCTURE.md` |
| Licenses | Prefer open source |

**Existing projects:** respect Laravel, PHP, Astro, React, etc. already in the repo — do not migrate stacks without explicit request.

---

## Common Stacks (in use)

| Pattern | Examples | Notes |
|---------|----------|-------|
| **Static + nginx + Traefik** | f12rocks, eselhoefe.de, frank-schwenk.de | Build scripts, serve via nginx container |
| **Astro** | schwenkonline, kkentertainment | Static output, minimal JS |

### Docker / Traefik

- External network: `traefik`
- TLS: `traefik.http.routers.<name>.tls.certresolver=myresolver`
- Entrypoint: `websecure`
- Use `compose.dev.yml` for local dev stacks when the project provides one

### CI/CD

Gitea Actions runner available on boka. Reference: `schwenkonline/.gitea/workflows/deploy.yml`.  
**Add or trigger CI/CD only with Fränky's explicit approval.**

---

## Python

- Virtual environment for every project
- Pin dependencies when the project already does
- Prefer stdlib + small deps for private/small tools

---

## Docker

- One `compose.yml` per deployable stack
- Named services, explicit volumes, documented host paths
- No destructive prod container ops without explicit approval

---

## Shell

- Prefer shell for simple file operations and glue
- `set -euo pipefail` for non-trivial scripts
- Quote variables; sanitize paths from user input
- **Language:** comments and `--help` text in **English** (unless client project — ask if unsure)

---

## Testing

- Mock anything that needs mocking
- Run test suite before handoff when one exists
- Fränky tests locally before prod when possible

---

## Web / UI

- **Mobile-first** — test at 390×844 and 360×800 for web projects
- **`prefers-reduced-motion`** — respect reduced motion preferences
- **Privacy by design** — no tracking/analytics without explicit approval
- Error messages: helpful, not condescending
- Accessibility: semantic HTML, keyboard navigation where applicable

---

## Security Baseline

- Validate and sanitize all input
- Secrets in env vars — never in source
- See `BOUNDARIES.md`

---

## New vs. Existing Projects

**Existing:** match stack, patterns, deploy flow in repo.  
**Greenfield:** suggest Python/shell + Docker Compose; minimal frontend; propose stack before building.

---

## Docs

- README with run/test/deploy commands is usually enough
- Auxiliary `.md` files fine — see `AGENTS.md`
- New docs: session language — no mid-session switching