Architecture Overview

Architecture Overview

psLens has only two moving parts:

1. The SWS framework, a small Integration Broker service installed inside your PeopleSoft environment.
2. The psLens application, a single Docker container hosted externally (default: fly.io) or on your own infrastructure.

Everything psLens displays (search results, alerts, reports) flows over a single HTTPS connection from the psLens container into your SWS endpoint. There is no other channel.

The Short Version

• Two components, nothing else. SWS inside PeopleSoft; psLens as a Docker container outside it.
• Traffic only flows one way. psLens calls SWS over HTTPS. SWS never reaches out to psLens.
• One protocol. REST + HTTP basic auth + psoftQL JSON queries. No database drivers, no ODBC, no jump hosts.
• One scope. SWS only answers queries against PeopleTools metadata tables that you whitelist. Anything outside the list is rejected before it touches the database.
• Dedicated deployment per customer. No shared psLens app, no shared storage, no multi-tenant SaaS backend.

How the Pieces Fit

%%{init: {"flowchart": {"htmlLabels": true, "padding": 16, "nodeSpacing": 60, "rankSpacing": 80, "subGraphTitleMargin": {"top": 10, "bottom": 14}}}}%%
flowchart LR
    USER(["Your team's<br/>web browser"])
    subgraph EXT["Cedar Hills Group hosted or your own infrastructure"]
        APP["psLens<br/>Docker container"]
    end
    subgraph PS["Your PeopleSoft Environment"]
        SWS["SWS Framework<br/>REST endpoint"]
        DB[("PeopleSoft DB<br/>read-only<br/>whitelisted tables")]
        SWS --> DB
    end
    USER -- "HTTPS" --> APP
    APP -- "HTTPS · Basic auth<br/>psoftQL JSON" --> SWS

    classDef ps fill:#e8f4fd,stroke:#0d6efd,stroke-width:2px,color:#000
    classDef ext fill:#fff5e6,stroke:#fd7e14,stroke-width:2px,color:#000
    classDef user fill:#e9f7ef,stroke:#198754,stroke-width:2px,color:#000
    classDef subgraphStyle fill:#fafafa,stroke:#666,stroke-width:1px,color:#000
    class SWS,DB ps
    class APP ext
    class USER user
    class PS,EXT subgraphStyle

Your team reaches psLens with any current web browser over HTTPS. There is no desktop client to install. Everything the user sees comes from the psLens container; the browser never talks to PeopleSoft directly.

Inside Your PeopleSoft Environment: SWS

The SWS framework is a small Integration Broker service Cedar Hills Group provides. Your PeopleSoft team installs it once, alongside everything else PeopleSoft already runs. It exposes a single REST endpoint that accepts a structured query language called psoftQL and returns JSON.

What SWS gives you control over:

• The whitelist. Your PeopleSoft admins decide which PeopleTools metadata tables SWS is allowed to read. psLens cannot ask for anything off the list.
• The credentials. SWS authenticates incoming requests with HTTP basic auth. Your team owns the token; rotating it is a config change on both ends.
• The audit trail. Calls land on your Integration Broker like any other inbound service, visible in the tooling your team already monitors.

No PeopleSoft database username or password is ever shared with psLens.

Outside Your Environment: psLens Container

psLens itself is a single Docker container: one Go binary, with embedded NATS for storing alert history and report output. That’s the entire runtime.

• Default deployment is on fly.io as a managed instance dedicated to your organization.
• Self-hosting is fully supported. Docker, docker-compose, bare-metal, and air-gapped environments are all covered in the installation guide.
• Stateless toward PeopleSoft. psLens does not copy your business data. The only things it persists are alert history and report output, both inside its own dedicated storage. See the Security & Trust page for details on what is and isn’t stored.

When you upgrade psLens, you pull a new container image. Nothing inside PeopleSoft changes.

Server-Driven Hypermedia Architecture (Zero Client-Side Storage)

psLens renders pages on the server with Go templates and streams updates over Server-Sent Events using Datastar. There is no React, no Angular, no JSON API. The browser receives HTML fragments over SSE (TLS at the transport layer) and renders them.

Two consequences fall out of this:

• Nothing from PeopleSoft is stored in the browser. psLens does not write to LocalStorage, SessionStorage, or IndexedDB. Closing the tab takes the active session data with it.
• No JSON wire format. The server sends pre-rendered HTML; there is no client-side data structure for an attacker to scrape or tamper with. Page transitions are server round-trips of a few KB of HTML, and the browser tab holds no result set.

Why This Shape

• Bounded blast radius. Even in a worst case where the psLens container were compromised, the SWS whitelist is the ceiling on what an attacker could read. They cannot drop into PeopleSoft, run PeopleCode, or pivot to other tables.
• Easy to upgrade and operate. New psLens features ship as a new container image. No PeopleSoft change request, no App Designer migration, no downtime on the PeopleSoft side.
• Multi-environment from day one. A single psLens deployment can connect to DEV, TEST, and PROD at the same time. Point at the SWS endpoint in each environment via separate database entries in config.yaml.

Where Next

• Installation installs SWS in PeopleSoft and runs the psLens container.
• Configuration wires psLens to your PeopleSoft environments.
• Security & Trust covers the read-only design, dedicated deployment, and what psLens does and doesn’t store.