# steveiliop56/tinyauth architecture

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

- Interactive diagram: https://gitdiagram.com/steveiliop56/tinyauth
- Repository: https://github.com/steveiliop56/tinyauth

## Overview

##### Project Type and Purpose
- Tinyauth is a full-stack authentication middleware: a Go-based service (backend + CLI) that serves a React/Vite frontend.
- It sits in front of your Docker-deployed apps (via Traefik, Nginx, Caddy) and provides login screens, basic auth, TOTP, and OAuth (Google, GitHub, generic).

##### File Structure Analysis
- Top-level “cmd/” holds CLI entry points (`toten` generation, `user` creation/verification and `root.go` wiring).
- `main.go` bootstraps the HTTP server, mounts API routes and serves embedded frontend assets.
- `internal/` contains modular packages:
- api: HTTP routing, request/response types
- handlers: request handlers for login, TOTP, OAuth callbacks
- auth: session/token management
- oauth & providers: OAuth flows for Google/GitHub/generic
- hooks, utils, constants, types, assets (embedded React build)
- `frontend/` is a standalone React/Vite app: pages, UI components, contexts (user/app), i18n, schemas for form validation, build config.
- Devops: Dockerfiles (service & frontend), docker-compose.yml examples, CI workflows, .env template.

##### README Insights
- Emphasizes Docker-first deployment, works with popular proxies.
- Demo uses Traefik + whoami + tinyauth.
- No external database; config and user store likely file-based or in-memory (managed via CLI).

##### Key Components
a. Main Components
- External Client (Browser)
- Edge Proxy (Traefik/Nginx/Caddy)
- Tinyauth Service (Go HTTP server)
- Authentication API (login, logout, TOTP, OAuth)
- Session Store (in-memory or file)
- Embedded Frontend (React)
- OAuth Providers (Google, GitHub, Generic)
- Protected Upstream Services (e.g., whoami, your app)
- CLI Tools (user management, totp generation) – optional, for operators
b. Interactions
- 1. Browser → Edge Proxy → Tinyauth (serves React UI or API)
- 2. Tinyauth ↔ OAuth providers (token exchange, user info)
- 3. Browser ← Tinyauth (session cookie)
- 4. Edge Proxy (post-auth) → Protected Service → Browser
- 5. Operator CLI → Tinyauth config/store (via file or API)
c. Architectural Patterns
- Monolithic service with clear layers: HTTP API, business logic (auth, OAuth), and static asset serving.
- CLI as separate commands under `cmd/`.
- Modular Go packages under `internal/` (separation of concerns).
- Frontend: Component-driven UI with context providers and schema-based validation.
d. Technologies & Libraries
- Go modules, Gin/chi (or custom router) in `internal/api`
- React + Vite + TypeScript + Sonner (toast) + Zod (schemas) + i18n
- Docker, Docker-Compose, Traefik/Nginx integration

##### Detailed Capture of Architectural Elements
- How the embedded `frontend/dist` is served by Go’s asset handler (`internal/assets`).
- API endpoints under the Go service (e.g., `/login`, `/oauth/callback`, `/totp`, `/verify`).
- Session flow: cookie issued → Proxy reads cookie → grants/denies forwarding to upstream.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Entities
    Browser["External Client (Browser)"]:::userFacing
    Proxy["Edge Proxy (Traefik/Nginx/Caddy)"]:::external
    OAuthCloud["OAuth Providers\n(Google, GitHub, Generic)"]:::external
    Upstream["Protected Upstream Service\n(e.g., whoami)"]:::external

    %% Frontend Layer
    subgraph "Frontend (Embedded React UI)" 
        ReactUI["React/Vite App"]:::userFacing
    end

    %% Backend Service Layer
    subgraph "Tinyauth Service (Go HTTP Server)" 
        Service["Go HTTP Server"]:::service
        API["Authentication API\n(internal/api/api.go\ninternal/types/api.go)"]:::service
        Handlers["Request Handlers\n(internal/handlers/handlers.go)"]:::service
        AuthStore["Session & Token Store\n(internal/auth/auth.go)"]:::data
        Assets["Embedded Frontend Assets\n(internal/assets/assets.go)"]:::service
        Config["Configuration & Types\n(internal/types/config.go)"]:::data
        Constants["Constants\n(internal/constants/constants.go)"]:::data
        Utils["Utility Functions\n(internal/utils/utils.go)"]:::service
        Hooks["Hooks\n(internal/hooks/hooks.go)"]:::service

        %% OAuth Submodule
        subgraph "OAuth Core & Providers"
            OAuthCore["OAuth Core Logic\n(internal/oauth/oauth.go)"]:::service
            Providers["Providers\n(internal/providers/providers.go)"]:::service
            Google["Google Provider\n(internal/providers/google.go)"]:::service
            GitHub["GitHub Provider\n(internal/providers/github.go)"]:::service
            Generic["Generic Provider\n(internal/providers/generic.go)"]:::service
        end
    end

    %% CLI Tools
    subgraph "CLI Tools" 
        CLIRoot["CLI Root & Version\n(cmd/root.go\ncmd/version.go)"]:::cli
        CLIUser["User Management\n(cmd/user/user.go\ncmd/user/create/create.go\ncmd/user/verify/verify.go)"]:::cli
        CLITOTP["TOTP Generation\n(cmd/totp/totp.go\ncmd/totp/generate/generate.go)"]:::cli
    end

    %% Config Store
    ConfigStore["Configuration / Secrets Store"]:::data

    %% Connections
    Browser -->|"HTTP Request"| Proxy
    Proxy -->|"Route to UI/API"| Service
    Service -->|"serves UI assets"| ReactUI
    Service -->|"reads assets"| Assets
    ReactUI -->|"API Calls"| API
    API -->|"dispatches"| Handlers
    Handlers -->|"uses"| AuthStore
    Handlers -->|"uses"| OAuthCore
    OAuthCore -->|"calls"| Providers
    Providers --> Google
    Providers --> GitHub
    Providers --> Generic
    Service -->|"reads config"| Config
    Service -->|"reads constants"| Constants
    Handlers -->|"utils/hooks"| Utils
    Handlers -->|"utils/hooks"| Hooks
    Handlers --> OAuthCloud
    OAuthCloud -->|"token exchange"| OAuthCore
    AuthStore --> Proxy
    Proxy -->|"forwards if authenticated"| Upstream

    %% CLI interactions (dashed)
    CLIRoot -.-> ConfigStore
    CLIUser -.-> ConfigStore
    CLITOTP -.-> ConfigStore

    %% Click Events
    click Service "https://github.com/steveiliop56/tinyauth/blob/main/main.go"
    click API "https://github.com/steveiliop56/tinyauth/blob/main/internal/api/api.go"
    click Handlers "https://github.com/steveiliop56/tinyauth/blob/main/internal/handlers/handlers.go"
    click AuthStore "https://github.com/steveiliop56/tinyauth/blob/main/internal/auth/auth.go"
    click Assets "https://github.com/steveiliop56/tinyauth/blob/main/internal/assets/assets.go"
    click OAuthCore "https://github.com/steveiliop56/tinyauth/blob/main/internal/oauth/oauth.go"
    click Providers "https://github.com/steveiliop56/tinyauth/blob/main/internal/providers/providers.go"
    click Google "https://github.com/steveiliop56/tinyauth/blob/main/internal/providers/google.go"
    click GitHub "https://github.com/steveiliop56/tinyauth/blob/main/internal/providers/github.go"
    click Generic "https://github.com/steveiliop56/tinyauth/blob/main/internal/providers/generic.go"
    click Config "https://github.com/steveiliop56/tinyauth/blob/main/internal/types/config.go"
    click Constants "https://github.com/steveiliop56/tinyauth/blob/main/internal/constants/constants.go"
    click Utils "https://github.com/steveiliop56/tinyauth/blob/main/internal/utils/utils.go"
    click Hooks "https://github.com/steveiliop56/tinyauth/blob/main/internal/hooks/hooks.go"
    click CLIRoot "https://github.com/steveiliop56/tinyauth/blob/main/cmd/root.go"
    click CLIUser "https://github.com/steveiliop56/tinyauth/blob/main/cmd/user/user.go"
    click CLITOTP "https://github.com/steveiliop56/tinyauth/blob/main/cmd/totp/totp.go"
    click ReactUI "https://github.com/steveiliop56/tinyauth/tree/main/frontend/"

    %% Styles
    classDef userFacing fill:#adebad,stroke:#333,stroke-width:1px
    classDef service fill:#87cefa,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef data fill:#f0e68c,stroke:#333,stroke-width:1px
    classDef cli fill:#add8e6,stroke:#333,stroke-width:1px
```
