project-map

name	project-map
description	Complete module inventory of the Auth API project with file paths, dependencies, and architecture overview. Load this first in any new session.
license	MIT

What This Project Is

A multi-tenant authentication and authorization REST API in Go 1.23+, using Gin, PostgreSQL (GORM), and Redis. It provides user registration, login, OAuth2 social login, TOTP/email/SMS/backup-email 2FA, WebAuthn/passkeys, magic links, RBAC, session management, OIDC provider, webhooks, brute-force protection, GeoIP IP rules, health/metrics, and a full admin interface (JSON API + HTMX GUI).

Architecture

Pattern: Repository -> Service -> Handler (Clean Architecture)

Key design decisions:

• Concrete struct dependency injection (no interface-based DI containers)
• Function-type callbacks between modules to avoid import cycles (e.g., RoleLookupFunc, AssignDefaultRoleFunc)
• Multi-tenancy: Tenant -> Application -> User hierarchy
• Every user is scoped to an AppID (UUID), with default app 00000000-0000-0000-0000-000000000001

Entry Point

• cmd/api/main.go -- Dependency injection, route setup, server startup

Domain Modules (internal/)

internal/admin/ (11 files)

Tenant/app CRUD, OAuth provider configuration, email management, API key management, admin account authentication, 2FA for admin accounts, system settings (env -> DB -> default resolution), dashboard stats, HTMX GUI handler.

File	Purpose
gui_handler.go	HTMX admin GUI (4976 lines, largest file)
handler.go	Admin JSON REST API (1146 lines)
repository.go	Data access for tenants, apps, OAuth, users, API keys, logs (952 lines)
account_service.go	Admin auth, sessions, 2FA, CSRF, password ops
account_repository.go	AdminAccount GORM queries
dashboard_service.go	Dashboard stats aggregation (PostgreSQL + Redis)
settings_service.go	System settings with 3-tier resolution (env > DB > default)
settings_repository.go	SystemSetting GORM queries with upsert
apikey_util.go	API key generation (SHA-256 hash, prefix/suffix)
apikey_util_test.go	Tests for API key utilities
account_service_test.go	Tests for admin account service

internal/user/ (5 files)

Registration, login (with self-healing role assignment), password reset, magic link auth, email change with verification, profile management.

File	Purpose
handler.go	User HTTP handlers
service.go	User business logic
repository.go	User GORM queries
handler_test.go	Handler tests
service_test.go	Service tests

internal/social/ (4 files)

Google, Facebook, GitHub OAuth2 flows. Supports account linking and direct social login/registration.

File	Purpose
handler.go	OAuth2 HTTP handlers (login, callback, link)
service.go	OAuth2 business logic
repository.go	SocialAccount GORM queries
oauth_state.go	OAuth state parameter encoding (appID, provider, action, HMAC)

internal/twofa/ (3 files)

TOTP (authenticator apps), email-based 2FA codes, SMS 2FA (Twilio), backup email 2FA, recovery codes, trusted devices.

File	Purpose
handler.go	2FA HTTP handlers (TOTP, email, SMS, backup email, trusted devices, phone management)
service.go	2FA business logic (TOTP + email + SMS + backup email codes, trusted device validation)
trusted_device_repository.go	TrustedDevice GORM queries

internal/webauthn/ (5 files)

Full WebAuthn support for users and admin accounts.

File	Purpose
handler.go	Passkey HTTP handlers
service.go	WebAuthn ceremony logic
repository.go	WebAuthnCredential GORM queries
config.go	Relying party configuration
user_adapter.go	Adapts User/AdminAccount to WebAuthn user interface

internal/session/ (2 files)

Redis-backed sessions with refresh token rotation, multi-device tracking.

File	Purpose
service.go	Session lifecycle (create, refresh, revoke, list)
handler.go	Session API endpoints

internal/rbac/ (3 files)

Roles per-application, permissions as resource:action, Redis-cached authorization.

File	Purpose
service.go	RBAC logic with Redis caching
repository.go	Role/Permission/UserRole GORM queries
handler.go	RBAC API endpoints

internal/email/ (8 files)

Multi-layered email system: Service -> VariableResolver + Renderer + Sender.

File	Purpose
service.go	Orchestrator (send pipeline, template/SMTP resolution)
resolver.go	Variable resolution pipeline (4 layers)
renderer.go	Three template engines (go_template, placeholder, raw_html)
sender.go	SMTP sending via gopkg.in/mail.v2
types.go	Constants, structs, variable registry
defaults.go	7 hardcoded default email templates
repository.go	Email types, templates, server configs GORM queries
email_integration_test.go	Integration tests

internal/log/ (6 files)

Async channel-based logging with anomaly detection.

File	Purpose
service.go	Async log service (buffered channel, background worker)
anomaly.go	Anomaly detection (new IP, new UA, unusual time)
cleanup.go	Scheduled log retention/cleanup
query_service.go	Filtered, paginated log querying
handler.go	Log API endpoints
repository.go	ActivityLog GORM queries

internal/middleware/ (13 files)

File	Purpose
auth.go	JWT auth + token blacklist checking
admin_auth.go	Admin API Key auth (static env + DB-backed)
app_api_key.go	Per-app API Key auth
gui_auth.go	Admin GUI cookie session auth
csrf.go	CSRF protection for GUI
app_id.go	X-App-ID header extraction
app_route_guard.go	Cross-app URL parameter validation
rate_limit.go	Redis + in-memory fallback rate limiting
cors.go	CORS configuration
security_headers.go	CSP, HSTS, X-Frame-Options
auth_test.go	Auth middleware tests
rate_limit_test.go	Rate limit tests
security_headers_test.go	Security header tests

Other internal packages

Package	File	Purpose
internal/oidc/	7 files	Full OIDC provider: discovery, authorize, token, userinfo, introspect, revoke, end_session, JWKS, RS256 id_token signing
internal/webhook/	3 files	Webhook endpoint registry, async delivery dispatcher, retry queue, HMAC-SHA256 signing
internal/bruteforce/	2 files	Account lockout, progressive login delays, CAPTCHA trigger threshold
internal/geoip/	3 files	MaxMind GeoLite2 service, IP rule repository, IP rule evaluator (CIDR/country per app)
internal/health/	1 file	GET /health liveness, GET /metrics Prometheus, PrometheusMiddleware, MetricsSummary
internal/sms/	3 files	SMS sender interface, Twilio implementation, config loader
internal/database/	db.go	PostgreSQL connection + GORM auto-migration
internal/redis/	redis.go	Redis connection + token blacklisting + session helpers
internal/config/	logging.go	Logging configuration
internal/util/	client_info.go, frontend_url.go	Client info extraction, frontend URL resolution

Shared Packages (pkg/)

Package	Files	Purpose
pkg/models/	17+ model files	GORM models: User, Tenant, Application, Role, Permission, UserRole, AdminAccount, SocialAccount, WebAuthnCredential, ActivityLog, ApiKey, ApiKeyUsage, EmailType, EmailTemplate, EmailServerConfig, OAuthProviderConfig, SystemSetting, SchemaMigration, OIDCClient, OIDCAuthCode, WebhookEndpoint, WebhookDelivery, IPRule, TrustedDevice
pkg/dto/	7+ files	Request/response DTOs: auth, admin, session, RBAC, WebAuthn, email, activity_log, oidc, webhook, geoip
pkg/errors/	errors.go, errors_test.go	AppError type with 6 HTTP status code mappings
pkg/jwt/	jwt.go, jwt_test.go	JWT Claims (UserID, AppID, SessionID, TokenType, Roles), generate/parse

Web Package (web/)

File	Purpose
renderer.go	HTML template renderer (embedded templates, funcMap)
context_keys.go	Shared context keys, SessionValidator/ApiKeyValidator interfaces, cookie helpers
static/embed.go	Embedded static files (CSS/JS)

Dependencies Between Modules

main.go wires everything:
  user.Service depends on: user.Repository, email.Service, rbac.Service (via callbacks), session.Service, webhook.Service, sms.Sender
  social.Service depends on: user.Repository, social.Repository, rbac.Service (via callbacks), session.Service, webhook.Service
  twofa.Service depends on: user.Repository, email.Service, sms.Sender, trusted_device.Repository
  twofa.Handler depends on: rbac.Service (via callbacks), session.Service, trusted_device.Repository
  webauthn.Service depends on: webauthn.Repository, user.Repository
  webauthn.Handler depends on: rbac.Service (via callbacks), session.Service, webhook.Service
  oidc.Service depends on: oidc.Repository, rbac.Service (GetUserRoleNames)
  webhook.Service depends on: webhook.Repository
  bruteforce.Service depends on: database.DB (Redis-less, PostgreSQL counters)
  geoip.IPRuleEvaluator depends on: geoip.IPRuleRepository, geoip.Service
  health.Handler depends on: database.DB, redis.Rdb, SMTP address
  rbac.Service depends on: rbac.Repository
  session.Service depends on: Redis
  email.Service depends on: email.Repository, VariableResolver, Renderer, Sender
  log.Service depends on: log.Repository, AnomalyDetector
  admin.Handler depends on: admin.Repository, email.Service, trusted_device.Repository
  admin.GUIHandler depends on: AccountService, DashboardService, admin.Repository, SettingsService, email.Service, rbac.Service, webauthn.Service, webhook.Service, oidc.Service, health.Handler, trusted_device.Repository

When To Use This Skill

Load this skill at the start of any session to understand the project structure. For domain-specific deep dives, also load the relevant skill: route-map, data-model, auth-flows, email-system, or admin-gui.