# ngtrieuvi92/keycloak-reactjs-demo architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack demo application showcasing a React.js single-page application (SPA) integrated with Keycloak for SSO, plus a proxied backend service described by a Swagger spec.

##### File structure
- Top-level:
- public/ contains static HTML and Keycloak adapter config
- src/ houses React components, business-logic modules, and proxy setup
- backend-swagger-spec.yml describes the API schema
- setupProxy.js configures the CRA dev server to forward API calls
- Patterns:
- Component-based UI (BookList, BookDetails, BookForm, etc.)
- A thin “modules/books.js” layer for HTTP calls to /books endpoints
- Integration with Keycloak’s JavaScript adapter and silent-check-sso

##### README for additional insights
- Purpose: demo of Keycloak SSO + “silent check-sso” flow in a React app
- Prerequisites: CRA (>= v16.3), Keycloak >= v8.x
- Backend: can be spun up via the provided Swagger spec or any compatible service; dev proxy points to a local backend

##### Main components & interactions
a. Components
1. Browser / User Agent
2. React SPA (running in the browser)
– Components: BookList, BookDetails, BookForm, etc.
– Modules layer (books.js) calling REST API
– Keycloak adapter (in index.js + silent-check-sso.html)
3. Keycloak SSO Server (external identity provider)
4. Backend API Service (implements Swagger spec)
5. (Optional) Database behind the backend
b. Relationships / Data flow
– User → Browser → serves index.html + React bundle
– SPA → Keycloak: initialization, login redirect, token exchange, silent-check-sso via hidden iframe
– SPA → Backend API: authenticated REST calls (GET/POST/PUT/DELETE /books) through the CRA proxy
– Backend API → Database: CRUD operations
c. Architectural patterns / principles
– SPA architecture with separation of concerns: UI components vs. API modules
– Proxying dev-server traffic to avoid CORS
– OIDC authorization code flow (with PKCE) and silent SSO check
d. Key technologies
– React.js (create-react-app)
– keycloak-js adapter
– Webpack Dev Server proxy (setupProxy.js)
– Swagger/OpenAPI (backend-swagger-spec.yml)
– Node/Express or any RESTful backend (implied)

##### Detail without over-splitting
- Essential pieces (static assets, SPA runtime, auth adapter, proxy, API spec)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser"
        Browser["Browser / User Agent"]
    end

    subgraph "Frontend (React SPA)"
        direction TB
        IndexHTML["index.html"]:::frontend
        KeycloakJSON["keycloak.json"]:::auth
        SilentHTML["silent-check-sso.html"]:::auth
        IndexJS["index.js"]:::frontend
        subgraph "UI Components"
            direction TB
            Book["Book.jsx"]:::frontend
            BookBox["BookBox.jsx"]:::frontend
            BookDetails["BookDetails.jsx"]:::frontend
            BookForm["BookForm.jsx"]:::frontend
            BookList["BookList.jsx"]:::frontend
        end
        subgraph "API Modules"
            direction TB
            BooksModule["books.js"]:::frontend
            ModulesIndex["index.js"]:::frontend
        end
        Proxy["setupProxy.js"]:::backend
    end

    subgraph "Auth (Keycloak)"
        Keycloak["Keycloak SSO Server"]:::auth
    end

    subgraph "Backend Service"
        SwaggerSpec["backend-swagger-spec.yml"]:::backend
        API["Books API Service"]:::backend
        DB[(Database)]:::database
    end

    %% Connections
    Browser -->|"serves index.html and static assets"| IndexHTML
    IndexHTML --> IndexJS
    IndexJS -->|"init Keycloak adapter"| KeycloakJSON
    IndexJS -->|"load silent-check-sso iframe"| SilentHTML
    IndexJS -->|"bootstrap UI"| Book
    Book --> BookBox
    Book --> BookDetails
    Book --> BookForm
    Book --> BookList
    IndexJS --> BooksModule
    ModulesIndex --> BooksModule
    BooksModule -->|"HTTPS/JSON"| API
    Proxy --> API
    IndexJS -->|"OIDC HTTPS"| Keycloak
    API -->|"CRUD operations"| DB

    %% Click Events
    click IndexHTML "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/public/index.html"
    click KeycloakJSON "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/public/keycloak.json"
    click SilentHTML "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/public/silent-check-sso.html"
    click IndexJS "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/src/index.js"
    click Book "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/src/components/Book.jsx"
    click BookBox "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/src/components/BookBox.jsx"
    click BookDetails "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/src/components/BookDetails.jsx"
    click BookForm "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/src/components/BookForm.jsx"
    click BookList "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/src/components/BookList.jsx"
    click BooksModule "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/src/modules/books.js"
    click ModulesIndex "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/src/modules/index.js"
    click Proxy "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/src/setupProxy.js"
    click SwaggerSpec "https://github.com/ngtrieuvi92/keycloak-reactjs-demo/blob/master/backend-swagger-spec.yml"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#000,stroke-width:1px
    classDef auth fill:#FFD8B0,stroke:#000,stroke-width:1px
    classDef backend fill:#D0FFD6,stroke:#000,stroke-width:1px
    classDef database fill:#E0E0E0,stroke:#000,stroke-width:1px
```
