Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Stack

Every app in Andromeda is built on the same Go stack. This page covers the core dependencies and how they fit together.

Core Dependencies

net/http

The stdlib net/http package powers every app — no web framework. Routing is done with http.ServeMux (1.22+ method+pattern routes):

mux := http.NewServeMux()
mux.HandleFunc("GET /", index)
mux.HandleFunc("POST /api/items", createItem)

SQLite (modernc.org/sqlite)

modernc.org/sqlite provides the storage layer — a pure-Go SQLite driver, no cgo required. Each app creates its own SQLite database file, keeping data local and portable. No external database server needed.

html/template

The stdlib html/template package handles HTML templating with context-aware escaping. Templates live in a templates/ directory and are parsed at startup:

tmpl := template.Must(template.ParseFS(templatesFS, "templates/*.html"))
tmpl.ExecuteTemplate(w, "index.html", IndexData{Items: items})

embed.FS

The stdlib embed package embeds static assets (CSS, fonts, images) and templates directly into the binary at compile time. This is what makes each app a single, self-contained binary with no external file dependencies.

//go:embed static templates
var assets embed.FS

Shared Packages

Each is its own Go module under pkg/, referenced via replace directives in each app's go.mod.

pkg/auth

Provides session-based password authentication used across apps that require login. It handles:

  • Constant-time password verification (bcrypt + plain)
  • Session cookie management backed by a sessions table in the app's SQLite DB
  • RequireSession, RequireAPIKey, and RequireBearerOrSession middleware
  • Short-id and session-token generators

pkg/sqlite

Thin bootstrap around database/sql + modernc.org/sqlite. Open(path, schema) opens the DB with the project defaults (PRAGMA foreign_keys=ON, single open connection) and applies an optional schema string on first open.

pkg/web

HTTP helpers used across apps:

  • Render — execute template + write response
  • WriteJSON / DecodeJSON — JSON I/O helpers
  • EmbeddedHandler — serve assets out of an embed.FS
  • redirect helpers

pkg/config

Loads env vars from process environment and .env files.

pkg/darkmatter

Ships the canonical Darkmatter stylesheet and Commit Mono fonts as an embedded handler set. Call Mount() once on your mux and every app inherits the shared aesthetic:

  • /assets/darkmatter.css — reset, tokens, and shared component styles
  • /assets/fonts/* — Commit Mono 400/700
  • /darkmatter — live component gallery
import "github.com/stevedylandev/andromeda/pkg/darkmatter"
 
mux := http.NewServeMux()
darkmatter.Mount(mux, "/assets")

Then reference /assets/darkmatter.css from your templates instead of duplicating the styles per app.

App Pattern

Every app follows a consistent structure:

app/
├── main.go            # Entry point, env vars, starts server
├── app.go             # App state + dependency wiring
├── routes.go          # Route registration
├── handlers_*.go      # HTTP handlers
├── db.go              # SQLite database layer
├── templates/         # html/template files
├── static/            # Fonts, favicons, styles
├── go.mod
├── Dockerfile
└── docker-compose.yml

This consistency means once you understand one app, you can navigate any of them.