Skip to content

Technology Stack

Version: 1.1.0

Status: Active

Owner: Rafael da Silva Guerra

Purpose

This document lists the tools W7 is built on at the foundation layer, and the reasoning behind each choice. It does not list technology choices made inside individual initiatives — those belong to the initiative's own repository and inherit only the principles below, not the specific tools.

Context

The stack favors open formats, established tools and replaceable hosted services likely to remain recoverable in ten years. This is a deliberate bias. Trend-driven tooling and proprietary storage formats are liabilities in a repository meant to outlast whatever is popular the year it was written.

Principles Behind the Choices

Open formats over proprietary ones. Anything that stores W7's knowledge must be readable with a text editor and a Git client alone, with no vendor account required to recover it.

Plain text over binary. Markdown, YAML and plain text diff cleanly, merge predictably, and survive tool migrations. Binary formats (proprietary word processors, design tool project files) are avoided for anything canonical.

Git as the mechanism, GitHub as the venue. The mechanism (Git) is portable and vendor-independent. The venue (GitHub) is replaceable if it ever needs to be, because the mechanism underneath it is not locked in.

Static over dynamic. Nothing in this repository requires a running server, a database, or an account to read. A clone of this repository, opened with any text editor, is fully self-contained.

The Stack

Layer Choice Why
Source control Git Distributed, open, the de facto standard; not tied to any single host
Hosting GitHub Where the team already collaborates; not treated as irreplaceable — see below
Documentation format Markdown (CommonMark) Readable as plain text, renders everywhere, no proprietary lock-in
Documentation site MkDocs (Material theme) Static site generator with no server dependency; builds directly from the Markdown already in this repository, nothing is duplicated to produce it
Decision records ADRs (Markdown, template) Lightweight, versioned alongside the decisions they document
Commit convention Conventional Commits Machine-parseable history; enables changelogs and makes intent explicit at a glance
Continuous integration GitHub Actions Validates and deploys the documentation build on changes to main; public availability still depends on repository and Pages settings
Personal knowledge management Obsidian ("Rafael OS") Explicitly not part of the stack that produces official documentation — see Information Boundaries

What Is Deliberately Not Here

There is no database, no backend service, and no build step that isn't a static site generator. If a future initiative needs any of those, it is that initiative's decision to make in its own repository, following the Product Framework — it does not become part of this repository's stack.

Reversibility

GitHub was chosen for convenience and reach, not because W7 depends on it existing forever. Everything in this repository is plain Markdown under Git; migrating hosts is a git remote set-url away, not a rewrite. This is intentional: the tool should always be easier to replace than the knowledge it holds.