# singpass/demo-app architecture

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

- Interactive diagram: https://gitdiagram.com/singpass/demo-app
- Repository: https://github.com/singpass/demo-app

## Overview

##### Project Type and Purpose
- This is a demo app intended to show how to integrate with Singpass as an OpenID Connect (OIDC) client.
- Although currently only a NodeJS example is available, there is mention of a Java version in the works. So, for now, focus on the NodeJS implementation.

##### File Structure
- Key directories:
- The root includes general documentation (docs) and examples.
- Under “examples” there are two subdirectories: one for the frontend (static HTML/CSS assets) and one for the NodeJS backend.
- In the “examples/nodejs” folder:
- You have a package.json for dependencies and build scripts.
- The “src” directory contains “config.mjs”, “router.mjs”, and “server.mjs”, which implies that the backend server’s layers are split into configuration, routing, and server bootstrapping.
- The “examples/frontend” holds static assets (an HTML file and a CSS file) that might serve as the user-facing component, such as the login page.

##### README for Additional Insights
- The README explains that this demo app uses Singpass for authentication via OIDC.
- It provides instructions on running the demo locally and describes the login flow:
- The user initially sees a page with a “log in with Singpass” button.
- On clicking this, the user is directed to Singpass for authentication.
- Once authenticated, the app processes the response from the Singpass API and displays a UUID.
- It also includes screenshots (before and after login), which are stored in the docs directory.

- Main Components to Include:
- User Browser: Represents the client that consumes the demo app.
- Frontend Static Assets: The HTML and CSS files under examples/frontend.
- NodeJS Backend: The core server application located under examples/nodejs/src. This includes:
- Server initialization (server.mjs)
- Routing (router.mjs)
- Configuration (config.mjs)
- External OIDC Provider (Singpass): Indicate integration with Singpass’s authentication API.
- Relationships and Interactions:
- The Browser loads the static frontend assets (login page).
- When the user clicks the login button, the frontend (or backend via redirection) communicates with the NodeJS server.
- The NodeJS server, functioning as an OIDC client, initiates the OIDC authentication flow with Singpass.
- After authentication, Singpass returns authentication data (like a UUID) to the NodeJS server, which then sends the information back to the browser.

##### Emphasizing Architectural Patterns and Technologies
- Architectural Pattern:
- The design follows a client-server model with clearly separated frontend and backend concerns.
- The backend is organized in a modular way (using separate modules for configuration, routing, and server startup), suggesting good separation of concerns.
- Technologies/Frameworks:
- NodeJS is used for the backend, and you may want to note any web frameworks (for example, if Express.js is used, though you may visually indicate this as a “Router” component).
- The frontend is simple HTML/CSS served as static content.
- The external OIDC (Singpass) integration is a key technical dependency.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser["Browser"]:::client
        subgraph "Static Frontend Assets"
            Index["index.html"]:::frontend
            Style["style.css"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend Layer"
        subgraph "NodeJS Backend"
            Config["config.mjs"]:::backend
            Router["router.mjs"]:::backend
            Server["server.mjs"]:::backend
        end
    end

    %% External Service
    Singpass["Singpass OIDC Provider"]:::external

    %% Relationships
    Browser -->|"loads"| Index
    Browser -->|"loads"| Style
    Index -->|"triggers login"| Server
    Server -->|"uses configuration"| Config
    Server -->|"uses routing"| Router
    Server -->|"initiates OIDC flow"| Singpass
    Singpass -->|"returns auth data"| Server
    Server -->|"sends response (UUID)"| Browser

    %% Click Events
    click Index "https://github.com/singpass/demo-app/blob/main/examples/frontend/index.html"
    click Style "https://github.com/singpass/demo-app/blob/main/examples/frontend/style.css"
    click Server "https://github.com/singpass/demo-app/blob/main/examples/nodejs/src/server.mjs"
    click Router "https://github.com/singpass/demo-app/blob/main/examples/nodejs/src/router.mjs"
    click Config "https://github.com/singpass/demo-app/blob/main/examples/nodejs/src/config.mjs"

    %% Styles
    classDef client fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef frontend fill:#c8e6c9,stroke:#43a047,stroke-width:2px;
    classDef backend fill:#ffe082,stroke:#f9a825,stroke-width:2px;
    classDef external fill:#ffab91,stroke:#e64a19,stroke-width:2px;
```
