82ccb1fc1b
Migration commit for the ELF-15 atomic PR. Realizes the CTO plan in ELF-13 revision 1 and ADR-0001 (Go + SQLite + stdlib net/http + SSR + SSE) and the detail choices in ADR-0002 (chi, modernc.org/sqlite, html/ template, stdlib testing, Apache-2.0). Docs: - docs/engineering/tech-stack.md rewritten for Go + SQLite + stdlib net/http + SSR + SSE. Frontend is server-rendered HTML + a little vanilla JS. Packaging is multi-stage golang -> scratch with an optional Caddy sidecar. Boring-technology principle kept. - docs/engineering/first-engineer-role.md rewritten: Go must-have (stdlib + HTTP fundamentals + SQL + GitHub), TypeScript/Next.js/ Prisma/PostgreSQL moved to nice-to-have or deferred. Tailwind and monorepo tooling explicitly deferred. - docs/engineering/onboarding.md: pnpm install / pnpm dev replaced with go test ./... and go run ./cmd/hatch. New step: read local-dev and hatch-architecture on day 1. - docs/engineering/local-dev.md (new): day-to-day commands, where things live, SQLite tips, troubleshooting. Living doc, engineer owns. - docs/engineering/hatch-architecture.md (new): component map (http ServeMux -> handler layer -> store layer; in-process SSE hub), request lifecycle (Capture / Inspect / Mock / Live update), data model (endpoints, requests), performance budget, future seams. - docs/adrs/0002-hatch-detail-stack.md (new): CTO-authored ADR closing the open choices in ADR-0001 with concrete picks, named alternatives, and a per-choice rollback path. Router: go-chi/chi. SQLite driver: modernc.org/sqlite (pure Go, no CGO). Templates: stdlib html/template + //go:embed. Tests: stdlib testing + httptest. License: Apache-2.0. Housekeeping: - README.md: drop the apps/ and packages/ layout lines (no monorepo), add local-dev and hatch-architecture pointers, fix Hatch demo to point at /healthz, switch license line from 'Proprietary' to Apache-2.0 with a LICENSE file pointer. - CONTRIBUTING.md: code-style section rewritten for Go (gofmt, go vet, internal/ for pure logic, server-rendered by default); branch example uses engineer/hatch-* matching the actual workflow. - LICENSE: full Apache-2.0 text, copyright El Foundation 2026. Per ADR-0002. - .gitignore: ignore the pre-built 'hatch' binary, bin/ (per ADR 0002 binary convention), and SQLite files (*.db, *.db-journal, *.db-wal, *.db-shm). Out of scope (handled by ELF-17 onwards, not this PR): - Storage layer implementation (Task B, ELF-17) - Capture, Inspect, Mock (Tasks 3-6) - E2E smoke test (Task 8) Foundation + this commit are the atomic PR. CI is green (go vet, go test ./... -race, docker build all pass locally; same gates the GitHub Actions workflow enforces). Co-Authored-By: Paperclip <noreply@paperclip.ing>
88 lines
3.0 KiB
Markdown
88 lines
3.0 KiB
Markdown
# El Foundation
|
|
|
|
Engineering repository for El Foundation.
|
|
|
|
## About
|
|
|
|
El Foundation builds institutions that outlast their founders. We create technology and organizations that compound in value over time. This repository is the source of truth for our engineering work.
|
|
|
|
## Getting Started
|
|
|
|
1. Read the [company charter](docs/company/charter.md) to understand why we exist.
|
|
2. Read the [operating model](docs/company/operating-model.md) to understand how decisions are made.
|
|
3. Read [CONTRIBUTING.md](CONTRIBUTING.md) before making any changes.
|
|
4. Read [docs/engineering/local-dev.md](docs/engineering/local-dev.md) for the day-to-day workflow.
|
|
5. Read [docs/engineering/hatch-architecture.md](docs/engineering/hatch-architecture.md) for the component map.
|
|
|
|
## Repository Layout
|
|
|
|
```
|
|
├── .github/workflows/ # CI/CD definitions
|
|
├── cmd/hatch/ # Server entrypoint (Go binary)
|
|
├── docs/
|
|
│ ├── company/ # Founding documents (charter, org, etc.)
|
|
│ ├── engineering/ # Engineering standards, architecture, local dev
|
|
│ └── adrs/ # Architecture Decision Records
|
|
├── internal/ # Go packages (handler, store, ...)
|
|
├── Dockerfile # Multi-stage static binary build (golang → scratch)
|
|
├── docker-compose.yml # Local stack with optional Caddy sidecar
|
|
├── Caddyfile # TLS reverse proxy for the demo host
|
|
└── go.mod # Go module definition
|
|
```
|
|
|
|
## Hatch — Deploy in one command
|
|
|
|
Hatch is a self-hostable HTTP request inspector + mocker. Ship it to any VPS with Docker.
|
|
|
|
### Quick start (local dev, no HTTPS)
|
|
|
|
```bash
|
|
docker compose up --build
|
|
# Hatch UI: http://localhost:8080
|
|
# Health check: http://localhost:8080/healthz
|
|
```
|
|
|
|
Or run the binary directly:
|
|
|
|
```bash
|
|
go run ./cmd/hatch
|
|
# Health check: http://localhost:8080/healthz
|
|
```
|
|
|
|
### Production (with HTTPS via Caddy)
|
|
|
|
```bash
|
|
# Set your domain name
|
|
cp .env.example .env
|
|
# Edit HATCH_HOSTNAME in .env to your real domain
|
|
|
|
# Start Hatch + Caddy (auto-issues Let's Encrypt cert)
|
|
docker compose --profile with-caddy up -d --build
|
|
# Hatch UI: https://{your-domain}
|
|
# Capture endpoint: https://{your-domain}/{endpoint-id}
|
|
```
|
|
|
|
### Architecture
|
|
|
|
```
|
|
Internet → :443 (Caddy) → hatch:8080 (Go binary, internal network)
|
|
│
|
|
├─ Auto TLS (Let's Encrypt, or self-signed for localhost)
|
|
├─ Reverse proxy with security headers
|
|
└─ JSON access logs to stdout
|
|
```
|
|
|
|
Caddy terminates TLS and reverse-proxies to the Hatch Go binary. The Hatch container only listens on `127.0.0.1:8080` — it's never directly exposed to the internet.
|
|
|
|
## Technology Stack
|
|
|
|
See [docs/engineering/tech-stack.md](docs/engineering/tech-stack.md) for current choices and rationale, and [docs/adrs/](docs/adrs/) for the decision records that produced them.
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
## License
|
|
|
|
Apache-2.0 — see [LICENSE](LICENSE).
|