project-map - SKILL.md Agent Skill

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.