# Einherjar

> *For those who come after.*

A Go framework built from battle-tested production code — organized for teams,
documented for the developer who was never in the room.

---

## The Name

In Norse mythology, the **Einherjar** are the chosen — warriors who fell in battle
and were carried to Valhalla by the Valkyries. There they train, day after day,
preparing for Ragnarök. Not for themselves. For what comes after.

This framework carries that name deliberately. Every interface defined here, every
architectural decision recorded, every module boundary enforced exists for the
developer who will build on this code without ever speaking to its authors. No
tribal knowledge. No implicit conventions. **The documentation is the system.**

---

## What Is This

Einherjar is a collection of composable Go modules, each addressing one
infrastructure concern. The mental model is Spring Boot starters — not one framework
binary, but a curated set of independent modules with isolated dependency graphs.

Each module is its own `go.mod`. Import only what your service needs. A minimal CRUD
API requires exactly three: **`core` + `web` + one `db-*`**.

---

## Modules

| Module | Purpose | Depends on |
|---|---|---|
| [`contracts`][contracts] | Pure interfaces. The constitution of the framework. | — |
| [`core`][core] | Lifecycle, logging, errors, validation | `contracts` |
| [`web`][web] | HTTP server, middleware, routing, health | `contracts` `core` |
| [`auth`][auth] | Auth middleware, RBAC | `contracts` `web` `core` |
| [`auth-jwt`][auth-jwt] | JWT signing, token pairs, refresh | `contracts` `auth` `core` |
| [`auth-firebase`][auth-firebase] | Firebase authentication | `contracts` `auth` `core` |
| [`db-postgres`][db-postgres] | PostgreSQL client | `contracts` `core` |
| [`db-mysql`][db-mysql] | MySQL client | `contracts` `core` |
| [`db-sqlite`][db-sqlite] | SQLite client | `contracts` `core` |
| [`cache-valkey`][cache-valkey] | Valkey / Redis-compatible cache | `contracts` `core` |
| [`storage-minio`][storage-minio] | Object storage | `contracts` `core` |
| [`telemetry`][telemetry] | OpenTelemetry — `main` packages only | `contracts` `core` |
| [`worker`][worker] | Concurrent background worker pool | `contracts` `core` |
| [`httpclient`][httpclient] | Resilient outbound HTTP client | `contracts` `core` |

---

## Dependency Graph

```
contracts
└── core
     ├── web
     │    └── auth
     │         ├── auth-jwt
     │         └── auth-firebase
     ├── db-postgres
     ├── db-mysql
     ├── db-sqlite
     ├── cache-valkey
     ├── storage-minio
     ├── telemetry          ← import from main only
     ├── worker
     └── httpclient
```

Data modules (`db-*`, `cache-*`, `storage-*`) never import `web`. Repositories do
not know HTTP exists. This boundary is absolute.

---

## The Law

`contracts` is the constitution of this framework — pure interfaces, zero
dependencies, permanent signatures. Changes flow **outward from `contracts`**, never
inward. Before any change to `contracts`, the blast radius is calculated: which
interfaces are affected, which modules implement them, which modules consume those.
Release sequence: `contracts` first, then implementors, then consumers.

Adding a method to a published interface is a breaking change in Go. It is not
permitted without a major version bump and coordinated updates across all
implementing modules.

---

## For Those Who Come After

Good code is not written for the machine. It is not even written for the deadline.
It is written for the person who will read it at 11pm six months from now, under
pressure, trying to understand what this thing does and why it was built this way.

Every ADR in this organization exists because a decision was made and the reasoning
behind it matters as much as the outcome. Every interface in `contracts` is as small
as it can be because the developer implementing it in a new context deserves to know
exactly what is required and nothing more.

This is the standard. Not the deadline.

---

[contracts]: https://code.nochebuena.dev/einherjar/contracts
[core]: https://code.nochebuena.dev/einherjar/core
[web]: https://code.nochebuena.dev/einherjar/web
[auth]: https://code.nochebuena.dev/einherjar/auth
[auth-jwt]: https://code.nochebuena.dev/einherjar/auth-jwt
[auth-firebase]: https://code.nochebuena.dev/einherjar/auth-firebase
[db-postgres]: https://code.nochebuena.dev/einherjar/db-postgres
[db-mysql]: https://code.nochebuena.dev/einherjar/db-mysql
[db-sqlite]: https://code.nochebuena.dev/einherjar/db-sqlite
[cache-valkey]: https://code.nochebuena.dev/einherjar/cache-valkey
[storage-minio]: https://code.nochebuena.dev/einherjar/storage-minio
[telemetry]: https://code.nochebuena.dev/einherjar/telemetry
[worker]: https://code.nochebuena.dev/einherjar/worker
[httpclient]: https://code.nochebuena.dev/einherjar/httpclient