---
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`.