# dasniko/keycloak-reactjs-demo architecture

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

- Interactive diagram: https://gitdiagram.com/dasniko/keycloak-reactjs-demo
- Repository: https://github.com/dasniko/keycloak-reactjs-demo

## Overview

##### Project Type and Purpose
- This is a front-end demo application (“Keycloak React.JS Demo”) showing how to integrate a React/Vite single-page app with Keycloak for IAM/SSO without extra libraries.
- It fetches “books” data from a backend (AWS Lambda or any REST service defined by backend-swagger-spec.yml) and demonstrates conditional rendering based on authentication state and roles.

##### File Structure Analysis
- Top-level files: index.html, vite.config.js, package.json, deploy.sh
- public/ holds Keycloak adapter config (keycloak.json) and the silent SSO check HTML.
- src/ contains:
- components/ – React UI components (App.jsx, BookList.jsx, conditional renderers, etc.)
- modules/ – API wrappers (books.js)
- services/ – user session handling (UserService.js)
- deployment/ holds Dockerfile and Nginx config (bookbox.conf) for production packaging.
- backend-swagger-spec.yml describes the REST API contract.

##### Key README Insights
- Uses React ≥18, Vite, React Router v6, and the official keycloak-js adapter.
- No custom server code here; backend is external (AWS Lambda or any service matching the Swagger spec).
- Deployment expects a reverse-proxy/static host (via Nginx in Docker) serving the SPA and forwarding /api calls.

##### Main Components
a. Client (Browser)
- React SPA (built with Vite)
- UI Components (App, BookList, BookDetails, BookForm, SecretBooks, etc.)
- React Router v6 for navigation
- keycloak-js adapter for authentication flows
- modules/books.js → HTTP client to /api/books
- services/UserService.js → wraps Keycloak token/session operations
b. External IAM Service
- Keycloak Server (Identity Provider)
c. Backend API Service
- REST endpoints (AWS Lambda or custom service defined by backend-swagger-spec.yml)
- Secured via Bearer tokens issued by Keycloak
d. Deployment Infrastructure
- Nginx (configured by bookbox.conf) serving static files, proxying /api → backend
- Docker container packaging the Nginx + built SPA

##### Relationships and Data Flows
- User opens the SPA in the browser
- SPA (keycloak-js) redirects to Keycloak for login
- On successful login, Keycloak redirects back with tokens
- UserService stores/accesses tokens, exposes user info & roles
- UI components (RenderOnAuthenticated/Role) read UserService → conditional rendering
- For data fetches, modules/books.js attaches Bearer token → calls Nginx /api/books
- Nginx proxies /api → Backend API → responds with JSON data

##### Architectural Patterns & Design Principles
- Layered Architecture: UI layer → service/module layer → transport layer
- Separation of Concerns: React components do not handle auth logic directly (delegated to keycloak-js + UserService)
- Declarative Routing & Conditional Rendering based on auth state/roles
- Infrastructure-as-Code: Dockerfile + Nginx config for reproducible deployments

##### Technologies & Frameworks
- React (Presentation)
- Vite (Build & dev server)
- React Router v6 (Routing)
- keycloak-js (Auth adapter)
- Axios/fetch (in modules/books.js)
- Nginx + Docker (Deployment)
- Swagger (API contract)
- AWS Lambda (Optional backend hosting)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Browser
    Browser(["User Browser"]):::external

    %% SPA Container
    subgraph "Browser / SPA"
        direction TB
        subgraph "Build Config & Entry"
            direction TB
            HTML["index.html"]:::frontend
            VITE["vite.config.js"]:::frontend
            ENTRY["src/index.jsx"]:::frontend
        end
        subgraph "UI Components"
            direction TB
            App["App.jsx"]:::frontend
            Menu["Menu.jsx"]:::frontend
            Welcome["Welcome.jsx"]:::frontend
            NoMatch["NoMatch.jsx"]:::frontend
            NotAllowed["NotAllowed.jsx"]:::frontend
            BookBox["BookBox.jsx"]:::frontend
            BookList["BookList.jsx"]:::frontend
            BookDetails["BookDetails.jsx"]:::frontend
            BookForm["BookForm.jsx"]:::frontend
            SecretBooks["SecretBooks.jsx"]:::frontend
        end
        subgraph "Conditional Renderers"
            direction TB
            Anon["RenderOnAnonymous.jsx"]:::frontend
            Auth["RenderOnAuthenticated.jsx"]:::frontend
            Role["RenderOnRole.jsx"]:::frontend
        end
        subgraph "Auth Adapter & Service"
            direction TB
            KCJSON["keycloak.json"]:::frontend
            UserSvc["UserService.js"]:::frontend
            SSO["silent-check-sso.html"]:::frontend
        end
        subgraph "API Modules"
            direction TB
            BooksMod["books.js"]:::api
            APIIdx["index.js"]:::api
        end
    end

    %% External Services and Infra
    Keycloak["Keycloak IAM"]:::external
    Nginx["Nginx + Docker"]:::infra
    Backend["REST API (AWS Lambda)"]:::external

    %% Data Flows
    Browser -->|"Loads SPA"| HTML
    HTML --> ENTRY
    ENTRY --> App
    App --> Menu
    App --> Welcome
    App --> NoMatch
    App --> NotAllowed
    App --> BookBox
    BookBox --> BookList
    BookList --> BookDetails
    BookBox --> BookForm
    BookBox --> SecretBooks

    App -->|"init keycloak-js"| UserSvc
    UserSvc -->|"reads config"| KCJSON
    UserSvc -->|"silent SSO check"| SSO

    UserSvc -->|"OIDC Auth Code Flow"| Keycloak
    Keycloak -->|"JWT Tokens"| UserSvc

    BookList -->|"calls getBooks()"| BooksMod
    BooksMod --> APIIdx
    APIIdx -->|"GET /api/books + Bearer token"| Nginx
    Nginx -->|"proxy /api"| Backend
    Backend -->|"JSON Response"| Nginx
    Nginx --> BooksMod

    %% Click Events
    click HTML "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/index.html"
    click VITE "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/vite.config.js"
    click ENTRY "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/index.jsx"
    click App "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/App.jsx"
    click Menu "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/Menu.jsx"
    click Welcome "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/Welcome.jsx"
    click NoMatch "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/NoMatch.jsx"
    click NotAllowed "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/NotAllowed.jsx"
    click BookBox "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/BookBox.jsx"
    click BookList "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/BookList.jsx"
    click BookDetails "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/BookDetails.jsx"
    click BookForm "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/BookForm.jsx"
    click SecretBooks "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/SecretBooks.jsx"
    click Anon "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/RenderOnAnonymous.jsx"
    click Auth "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/RenderOnAuthenticated.jsx"
    click Role "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/components/RenderOnRole.jsx"
    click KCJSON "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/public/keycloak.json"
    click UserSvc "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/services/UserService.js"
    click SSO "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/public/silent-check-sso.html"
    click BooksMod "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/modules/books.js"
    click APIIdx "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/src/modules/index.js"
    click Backend "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/backend-swagger-spec.yml"
    click Nginx "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/deployment/bookbox.conf"
    click Nginx "https://github.com/dasniko/keycloak-reactjs-demo/tree/main/deployment/Dockerfile"
    click Nginx "https://github.com/dasniko/keycloak-reactjs-demo/blob/main/deploy.sh"

    %% Styling
    classDef frontend fill:#D0E6FF,stroke:#003366,stroke-width:1px
    classDef api fill:#FFE0B2,stroke:#FF9800,stroke-width:1px
    classDef external fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px
    classDef infra fill:#ECEFF1,stroke:#546E7A,stroke-width:1px
```
