Files

docs: add README explaining the repo's purpose and usage

Introduce a README that frames this repo as living, cross-project
architectural guidance — required reading for human and agentic
contributors to any project under my control. Explains what's here,
how to use it, and how it evolves.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-22 12:07:32 +03:00

2.4 KiB

Raw Blame History

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.

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.