Package Structure

Autentico follows a feature-based package structure. Each package in pkg/ owns one feature domain.

Package layout

autentico/
├── main.go                   Entry point
├── pkg/
│   ├── account/              Account UI API + embedded SPA — profile, password, MFA, passkeys, sessions
│   ├── admin/                Dashboard stats handler; Admin UI embedded FS
│   ├── api/                  Shared API utilities — list query parsing, pagination, filtering
│   ├── appsettings/          Settings DB CRUD + hot-reload into config.Values
│   ├── audit/                Audit log recording and querying (audit_logs table)
│   ├── auth_code/            Authorization code create/read/mark-used
│   ├── authorize/            GET /oauth2/authorize — validates client, renders login page
│   ├── authzsig/             HMAC signatures for authorize-to-login parameter integrity
│   ├── bearer/               Bearer token extraction and user lookup from request
│   ├── cleanup/              Background goroutine to purge expired records
│   ├── cli/                  CLI subcommands — init, start, migrate, onboard
│   ├── client/               OAuth2 client registration, auth, CRUD
│   ├── config/               Bootstrap (env) + Values (runtime) config structs
│   ├── consent/              OAuth2 consent screen — scope display, consent persistence
│   ├── db/                   SQLite init, schema, migrations
│   ├── deletion/             Account deletion requests — user-initiated, admin-reviewed
│   ├── email/                Email sending (SMTP) — OTP codes, password reset, verification
│   ├── emailverification/    Email verification flow — send link, confirm token
│   ├── federation/           Federated/social login — external IdP integration, admin CRUD
│   ├── group/                User groups — CRUD, membership management
│   ├── health/               GET /healthz health check endpoint
│   ├── idpsession/           IdP-level SSO sessions — cookie management, cascade deactivation
│   ├── introspect/           POST /oauth2/introspect — token introspection (RFC 7662)
│   ├── jwtutil/              JWT validation helpers, AccessTokenClaims
│   ├── key/                  RSA key loading, JWK generation
│   ├── login/                POST /oauth2/login — credential validation, auth code creation
│   ├── mfa/                  MFA challenge create/validate (TOTP + email OTP)
│   ├── middleware/            CSRF, CORS, logging, security headers, admin/account auth
│   ├── model/                Shared response types (ApiResponse, AuthErrorResponse, WellKnown)
│   ├── onboarding/           First-run admin account creation flow
│   ├── passkey/              WebAuthn registration and authentication handlers
│   ├── passwordreset/        Password reset flow — forgot password, token validation, reset
│   ├── ratelimit/            Per-IP rate limiting for auth endpoints (token bucket)
│   ├── reqid/                Request ID generation and context propagation
│   ├── revoke/               POST /oauth2/revoke — token revocation (RFC 7009)
│   ├── session/              OAuth session lifecycle — create, read, deactivate, logout
│   ├── signup/               Self-signup handler
│   ├── token/                POST /oauth2/token — all grant types, token generation
│   ├── trusteddevice/        Trusted device create/read/validate
│   ├── user/                 User CRUD, authentication, lockout
│   ├── userinfo/             GET /oauth2/userinfo
│   ├── utils/                Shared helpers — response writers, redirect URI validation, hashing
│   └── wellknown/            GET /.well-known/openid-configuration, GET /oauth2/.well-known/jwks.json
├── view/                     Server-side HTML templates (login, MFA, signup, onboarding)
├── admin-ui/                 React SPA source (built artifact embedded in admin package)
├── account-ui/               React SPA source (built artifact embedded in account package)
├── docs/                     Swagger-generated API documentation
└── docs-web/                 Starlight documentation site (this site)

Conventions within each package

Most feature packages follow a consistent file layout:

File	Purpose
model.go	Data structs, request/response types, validation
handler.go	HTTP handlers with Swagger annotations
create.go	Database INSERT operations
read.go	Database SELECT operations
update.go	Database UPDATE operations
delete.go	Database DELETE operations
service.go	Business logic that doesn't fit CRUD

Config package

The config package is the source of truth for all configuration at runtime:

• config.Bootstrap -- immutable values from .env, loaded once at startup
• config.Values -- mutable runtime settings, loaded from the settings DB table
• config.Get() -- returns the current *config.Values
• config.GetBootstrap() -- returns the *config.Bootstrap
• config.GetForClient(overrides) -- returns a config.Values with per-client overrides applied

Entry point and routing

pkg/cli/start.go RunStart() initializes the database, loads settings, registers all HTTP routes on http.NewServeMux(), starts the cleanup goroutine, and starts the HTTP server.