architecture/readme.md

architecture

Living documentation for the conventions and scaffolding defaults I use across every project I maintain. If you're contributing to one of those projects — as a human or as an AI coding agent — this repo is required reading.

What this is

A single place where decisions about workspace layout, deployment, infrastructure, service hardening, firewall rules, SELinux posture, and similar cross-cutting concerns are written down once and reused everywhere. Rather than re-deriving (or forgetting) the same defaults in every repo, each project points here and inherits them.

The goal is boring consistency: the same crate layout, the same deploy flow, the same systemd hardening, the same firewalld approach across every app I own, so that context switching between projects doesn't mean re-learning the shape of things.

What's here

• generic.md — the baseline. Applies to every project unless that project explicitly overrides a section. Covers workspace layout, separation of concerns, configuration, secrets, deployment, service accounts, firewalld, SELinux, and code quality.
• deployment-gitea-actions.md — CI-driven deployment via a Gitea Actions workflow, as an alternative to the deploy.sh + manifest.yml flow in generic.md §7. The workflow is the source of infra truth; the runner deploys as a scoped gitea_ci user.
• gitea-runners.md — the catalogue of gongfoo-managed CI runner images (what runs-on: label gives you which toolchain), how to pick the right one, and how to add or extend an image instead of dnf-installing at run time. Makes deployment-gitea-actions.md §5 concrete.
• port-allocations.md — how to choose a conflict-unlikely TCP port for an internal service (uncommon, registered range, not the alt-HTTP cluster or the ephemeral range) and the fleet registry of what's already assigned. Extends generic.md §9/§3.
• internal-tls.md — provisioning and renewing per-service internal TLS certs (<service>.internal) for mesh-only nginx vhosts, extending the PKI conventions in generic.md §11.
• external-tls.md — publicly-trusted certs for WAN-facing vhosts via Let's Encrypt (certbot, Cloudflare DNS-01, ECDSA). The external counterpart to internal-tls.md.
• reverse-proxies.md — the per-site nginx edge proxies (oolon for kosherinata, hanzalova.internal for the office), what sits behind each, the public-vs-mesh access paths, and the per-vhost cert choice. Names the topology behind generic.md §11 Ingress.

More files will appear here over time as guidance that's more specific than generic.md gets extracted — per-stack, per-deployment-target, or per-problem-domain documents. When a project needs guidance that isn't generic, it belongs in a new file here, not buried in one project's repo.

How to use it

• If you're scaffolding a new project: start from generic.md and follow it. Deviations should be deliberate and noted in that project's own README.
• If you're contributing to an existing project of mine: read generic.md first. The project's local CLAUDE.md or README.md will note any intentional deviations; everything else defaults to what's here.
• If you're an AI agent: treat this repo's contents as authoritative defaults for any project under my control. When the surrounding project doesn't specify, fall back to the guidance here. When it does specify, the project wins — but flag the deviation so it's visible.

How this evolves

This is living documentation, not a spec frozen at a point in time. When a convention changes — because something broke, because a better pattern emerged, or because the infrastructure itself changed — the update lands here first, and projects catch up on their next touch.

If you find guidance here that contradicts what's actually running in production, the guidance is wrong. Open an issue or a PR.