Frank Schwenk
93c78f503e
Compose + Traefik ForwardAuth middleware, Redis sessions, SMTP via 0012.de, TOTP and ACL for consumer apps (e.g. pi.schwenk.online). Co-authored-by: Cursor <cursoragent@cursor.com>
133 lines
3.9 KiB
Markdown
133 lines
3.9 KiB
Markdown
# 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
|