Architecture

🛡️ Armadillo · Go JWT Traefik

This document describes what Armadillo actually does today, grounded in the current code — not the longer-term scaffolding roadmap (see the README for that list).

Overview

Armadillo is a single Go binary (cmd/api/main.go) that runs an HTTP API on :3001 by default (configurable via PORT). It currently implements one thing end to end: a JWT-based auth service that other containers in the deployment can sit behind.

cmd/api/main.go   entrypoint — wires config, token service, and HTTP handlers
lib/auth/
  config.go       env-driven config (demo credentials, JWT secret, token TTL)
  token.go        TokenService — issues and verifies HS256 JWTs
  handler.go      HTTP handlers — /api/auth/login, /logout, /me

HTTP surface

Route	Method	Purpose
`/api/auth/login`	POST	Verifies email/password against configured demo credentials (constant-time compare) and issues a signed JWT
`/api/auth/logout`	POST	No-op 200 (tokens are stateless; nothing to invalidate server-side yet)
`/api/auth/me`	GET	Verifies the `Authorization: Bearer <token>` header and returns the decoded claims (`userId`, `role`, `scopeSpaceId`)
`/health`	GET	Liveness check
`/info`	GET	Service name, commit hash, and build time (set via `-ldflags` at build time)

Auth model

Tokens are signed HS256 JWTs (golang-jwt/jwt/v5), issued with an Issuer of armadillo, a subject, a role, and an optional scope_space_id claim.
Credentials are currently a single configured demo account (DEMO_EMAIL / DEMO_PASSWORD env vars) — there’s no user store or database yet.
JWT_SECRET and DEMO_PASSWORD are required env vars (the process exits at startup if they’re unset); TOKEN_TTL defaults to 86400 seconds.

Deployment

Docker: multi-stage Dockerfile builds a static binary into a scratch image, exposing :8080. Build args GIT_HASH and BUILD_TIME get baked into /info.
docker-compose.yaml: runs Armadillo alongside Traefik, another service (ibis), and an nginx static file server on a shared web Docker network. This is the personal homelab deployment shape today — there’s no notion yet of separate personal/experimental/production deployment tiers, though that’s on the roadmap.
Traefik: traefik.d/service-armadillo.yaml and config/traefik/traefik.d/service-armadillo.yaml register Armadillo as a Traefik service/router (routed on PathPrefix('/api')). traefik.d/service-ibis.yaml shows the intended pattern for gating other services: a forwardAuth middleware that calls http://armadillo:8080/auth before letting a request through to ibis.

What isn’t implemented yet

Per the README’s original feature list, the following are aspirational and not present in the code today:

Scaffolding a new service’s UI
Importing an existing service into the stack
Initializing CLI or workflow boilerplate for a new service
Building/updating infra and opening PRs against a target repo
Deployment-tier selection (personal / experimental / production) driving the deployment stack
Migrations

Test coverage exists for the auth package (lib/auth/handler_test.go, lib/auth/token_test.go); there is no integration or end-to-end test suite yet.