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.

psLens queries PeopleSoft through SWS over HTTPS. When alert delivery is configured, the container also sends notifications to an SMTP server or chat webhook. Your team accesses the application in a browser over HTTPS.

The Short Version

• Two components, nothing else. SWS runs inside PeopleSoft. psLens runs as a Docker container outside it.
• Traffic only flows one way. psLens calls SWS over HTTPS. SWS never sends requests 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. SWS rejects anything outside the list before the query reaches the database.
• Dedicated deployment per customer. No shared psLens app, no shared storage, no multi-tenant SaaS backend.

How the Pieces Fit

%%{init: {"theme": "redux-color", "flowchart": {"htmlLabels": true, "padding": 30, "nodeSpacing": 70, "rankSpacing": 70, "subGraphTitleMargin": {"top": 20, "bottom": 32}}}}%%
flowchart LR
    USER(["Your team's<br/>web browser"])
    APP["psLens<br/>Docker container"]

    subgraph PS["Your PeopleSoft Environment"]
        SWS["SWS Framework<br/>REST endpoint<br/>Read-only"]
        DB[("PeopleSoft DB<br/>read-only<br/>whitelisted tables")]
        SWS --> DB
    end

    EMAIL["Alerts via Email<br/>SMTP"]
    CHAT["Alerts via Chat - Teams/Slack/Google"]

    USER -- "HTTPS" --> APP
    APP -- "HTTPS · Basic auth<br/>psoftQL JSON" --> SWS
    APP -- "SMTP - Optional" --> EMAIL
    APP -- "HTTPS webhook" --> CHAT

    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 notify fill:#f3f0ff,stroke:#6f42c1,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 EMAIL,CHAT notify
    class PS,EXT,ALERTS subgraphStyle

Your team reaches psLens with any current web browser over HTTPS. There is no desktop client to install. The browser never talks to PeopleSoft directly. If alert delivery is configured, psLens sends email through SMTP and posts to Slack, Microsoft Teams, or Google Chat through incoming webhooks.

For the reasoning behind this design, see Why psLens Runs on Go, Hypermedia, and SWS.

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 can 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 the token is a configuration 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:

• The browser stores nothing from PeopleSoft. 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. If an attacker compromises the psLens container, the SWS whitelist limits what they can read. They cannot access PeopleSoft directly, 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.