# teamhanko/hanko architecture

> Architecture diagram of the GitHub repository teamhanko/hanko, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/teamhanko/hanko
- Repository: https://github.com/teamhanko/hanko

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend"
        Browser["Browser (Consumer App)"]:::frontend
        Elements["Hanko Elements (Web Components)"]:::frontend
        SDK["Hanko Frontend SDK"]:::frontend
        subgraph "Example Apps"
            Angular["Angular Example"]:::frontend
            NextJS["Next.js Example"]:::frontend
            ReactEx["React Example"]:::frontend
            Vue["Vue Example"]:::frontend
            Svelte["Svelte Example"]:::frontend
            Fresh["Fresh (Deno) Example"]:::frontend
            Express["Express Example"]:::frontend
        end
        Quickstart["Quickstart Demo"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend API"
        BackendAPI["Hanko Backend API"]:::backend
        Config["Configuration Module"]:::backend
        Handlers["HTTP Handlers"]:::backend
        FlowAPI["Flow API & Business Logic"]:::backend
        Persistence["Persistence (Models & Migrations)"]:::backend
        CLI["CLI Commands (Cobra)"]:::backend
        SAML["Enterprise SAML Support"]:::backend
    end

    %% Data Stores
    Postgres["PostgreSQL"]:::datastore
    Redis["Redis (Optional)"]:::datastore
    MailHog["SMTP/MailHog"]:::datastore

    %% External Systems
    OAuth["External OAuth Providers"]:::external
    SAMLIdP["External SAML IdP(s)"]:::external
    Webhooks["Webhook Targets"]:::external

    %% Connections
    Browser --> Elements
    Browser --> SDK
    Elements --> BackendAPI
    SDK --> BackendAPI

    BackendAPI --> Config
    BackendAPI --> Handlers
    BackendAPI --> FlowAPI
    BackendAPI --> Persistence
    BackendAPI --> CLI
    BackendAPI --> SAML

    BackendAPI --> Postgres
    BackendAPI --> Redis
    BackendAPI --> MailHog
    BackendAPI --> OAuth
    BackendAPI --> SAMLIdP
    BackendAPI --> Webhooks

    Quickstart --> Elements
    Quickstart --> BackendAPI

    Angular --> Elements
    NextJS --> Elements
    ReactEx --> Elements
    Vue --> Elements
    Svelte --> Elements
    Fresh --> Elements
    Express --> Elements

    %% Click Events
    click BackendAPI "https://github.com/teamhanko/hanko/tree/main/backend/"
    click Config "https://github.com/teamhanko/hanko/tree/main/backend/config/"
    click Handlers "https://github.com/teamhanko/hanko/tree/main/backend/handler/"
    click FlowAPI "https://github.com/teamhanko/hanko/tree/main/backend/flow_api/"
    click Persistence "https://github.com/teamhanko/hanko/tree/main/backend/persistence/"
    click CLI "https://github.com/teamhanko/hanko/tree/main/backend/cmd/"
    click SAML "https://github.com/teamhanko/hanko/tree/main/backend/ee/saml/"
    click Elements "https://github.com/teamhanko/hanko/tree/main/frontend/elements/"
    click SDK "https://github.com/teamhanko/hanko/tree/main/frontend/frontend-sdk/"
    click Angular "https://github.com/teamhanko/hanko/tree/main/frontend/examples/angular/"
    click NextJS "https://github.com/teamhanko/hanko/tree/main/frontend/examples/nextjs/"
    click ReactEx "https://github.com/teamhanko/hanko/tree/main/frontend/examples/react/"
    click Vue "https://github.com/teamhanko/hanko/tree/main/frontend/examples/vue/"
    click Svelte "https://github.com/teamhanko/hanko/tree/main/frontend/examples/svelte/"
    click Fresh "https://github.com/teamhanko/hanko/tree/main/frontend/examples/fresh/"
    click Express "https://github.com/teamhanko/hanko/tree/main/frontend/examples/express/"
    click Quickstart "https://github.com/teamhanko/hanko/tree/main/quickstart/"
    click DockerCompose "https://github.com/teamhanko/hanko/tree/main/deploy/docker-compose/"
    click Kubernetes "https://github.com/teamhanko/hanko/tree/main/deploy/k8s/"
    click E2E "https://github.com/teamhanko/hanko/tree/main/e2e/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085;
    classDef backend fill:#d4edda,stroke:#155724;
    classDef datastore fill:#fff3cd,stroke:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d;
```
