authschwenkonline/STANDARDS.md

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 (compose.yaml in vendor/third-party trees is OK)
• Every service: restart: unless-stopped — no exception unless Fränky or project docs say otherwise
• 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