How teamhanko/hanko works
Project Type & Purpose
• This is a monorepo for a full-stack, API-first authentication & user-management platform named “Hanko.”
• Core pieces:
• A Go-based backend API providing authentication (passkeys, passcodes, passwords), OAuth SSO, SAML SSO, webhooks, sessions, MFA, JWT issuance, user-management, audit logging.
• A “Hanko Elements” Web Components library (React/TS) for embedding login/registration/profile UIs.
• A “Hanko Frontend SDK” (TS) that encapsulates HTTP flow-API calls and client-side session/event handling.
• Example apps (Angular, Next.js, React, Vue, Svelte, Fresh, Express) and a Go “quickstart” demo.
• Deployment manifests (Docker Compose, Kubernetes) and end-to-end tests (Playwright).
File Structure Analysis
• Top-level directories:
• backend/ – Go service with subpackages for config, crypto, DTOs, flow_api, persistence (models + migrations), handlers, middleware, webhooks, CLI commands, and “ee” (enterprise) SAML support.
• frontend/elements/ – embeddable UI components packaged as an npm library.
• frontend/frontend-sdk/ – TS HTTP & event client for backend API.
• frontend/examples/ – starter templates for various frameworks.
• quickstart/ – a minimal Go HTTP + static frontend showing integration.
• deploy/ – Docker Compose and Kustomize for Kubernetes.
• e2e/ – Playwright tests running against a seeded environment (uses MailHog & Postgres).
Key Insights from README
• Architecture section calls out three building blocks: backend, elements, frontend-sdk.
• It’s API-first and cloud-native.
• Deployment examples show Postgres for persistence, MailHog (or SMTP) for email, optional Redis or in-memory for session/rate-limiting.
• Supports external OAuth providers and SAML IdPs.
a. Main Components (containers/services):
• Browser (client) hosting a consumer app that pulls in Hanko Elements or calls Hanko Frontend SDK.
• Hanko Frontend SDK / Elements (JS in browser).
• Hanko Backend API (Go HTTP server).
• PostgreSQL database.
• Mail service (SMTP or MailHog).
• Optional Redis (rate limiter, cache).
• External identity providers – OAuth providers (Google, GitHub, Apple, etc.), SAML IdP(s).
• Webhook targets (external HTTP endpoints).
b. Relationships & Data Flows:
1. User → Browser → Hanko Elements (or custom UI using Frontend SDK) → HTTP(S) → Hanko Backend API.
2. Backend API ↔ PostgreSQL (CRUD on users, passkeys, sessions, flows).
3. Backend API → SMTP/MailHog (for verification emails, passcodes).
4. Backend API ↔ Redis or in-memory store (for rate-limiting or device-trust cookies).
5. Backend API ↔ External OAuth providers (OAuth2 exchanges).
6. Backend API ↔ External SAML IdP(s) via SAML flows (enterprise edition).
7. Backend API → Webhook targets (on events like user created, login success).
c. Architectural Patterns & Design Principles:
• Layered architecture in the backend: HTTP handlers → service layer (flow_api, business logic) → persistence layer → migrations/models.
• CLI commands use Cobra for ops (migrations, key management, schema export).
• API-first approach: all features exposed as REST endpoints, with interactive flow API.
• Distributed configuration via YAML and environment variables.
• Monorepo containing multiple deployable artifacts (Go binary, npm packages, example apps).
d. Key Technologies & Frameworks:
• Go modules, Cobra CLI, fizz/migrate for DB migrations
• PostgreSQL, optional Redis
• SMTP (MailHog) for email
• React + Webpack for Hanko Elements
• TypeScript for Frontend SDK
• Playwright for E2E tests
• Docker Compose & Kubernetes (Kustomize) for deployments