# jeffersonlab/epics2web architecture

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

- Interactive diagram: https://gitdiagram.com/jeffersonlab/epics2web
- Repository: https://github.com/jeffersonlab/epics2web

## Overview

##### Project Type and Purpose
- epics2web is a full-stack Java web application packaged as a WAR and intended to run on a servlet container (Tomcat, GlassFish, WildFly).
- Purpose: Act as a gateway between EPICS Channel Access PVs (process variables) and web clients, exposing both REST endpoints (for “caget” style operations) and full-duplex WebSocket channels (for PV monitoring) along with a simple JavaScript client API.

##### File Structure Analysis
- Top-level build and CI configs: `build.gradle`, Gradle wrapper, Dockerfile, GitHub Actions workflows, `compose.yaml` + `compose.override.yaml`.
- `src/main/java/org/jlab/epics2web`:
- Application.java: Spring-boot style or Servlet initializer.
- `controller/`: REST endpoints for GET/monitor operations (CAGet, TestGet, TestMonitor, Overview).
- `filter/`: HTTP filter for caching and encoding.
- `websocket/`: ServerEndpoint configuration, session manager, listener, write strategy.
- `epics/`: ChannelManager, ChannelMonitor, ContextFactory, PvListener (JCA wrappers).
- `src/main/webapp`:
- JSP views under WEB-INF/views for console, overview, tests.
- Static resources: JS clients (`epics2web.js`, `test-camonitor.js`), CSS, images.
- `src/integration`: integration tests that spin up containers (softIOC, epics2web) and exercise WebSocket & REST.
- `examples/`: sample Soft IOC .db files, shell scripts to feed channel access values for local testing.

##### Key Architectural Patterns and Layers
- Containerized micro-services (via Docker Compose):
- softIOC service (EPICS simulation)
- epics2web service (Tomcat + epics2web.war)
- MVC for REST: Controller layer → business logic (ChannelManager) → JCA library → EPICS network
- WebSocket publish/subscribe: MonitorEndpoint + WebSocketSessionManager → push PV updates to browser
- Filter chain: `CacheAndEncodingFilter` to set caching headers and enforce UTF-8
- Thread pools via `CustomPrefixThreadFactory` for listener threads

##### Components & Interactions
a. Main Components
- EPICS PV Source
- SoftIOC container (docker-compose) or real EPICS IOCs on network
- EPICS2Web Server (Tomcat container)
- JCA library (javax.json, jca-2.4.6)
- ChannelManager / ChannelMonitor / ContextFactory
- REST Controllers (CAGet, TestGet)
- WebSocket Stack (MonitorEndpoint, SessionManager, WriteStrategy)
- HTTP Filter (CacheAndEncodingFilter)
- JSP View Resolver + Static Resources (JS/CSS)
- Browser Client
- JavaScript API (epics2web.js) – uses WebSocket or HTTP fetch
- JSP-rendered pages (console.jsp, overview.jsp, test pages)
- CI/CD Infrastructure (optional)
- GitHub Actions for CI (`ci.yaml`), CD (`cd.yaml`), dependency updates (`dd.yaml`)

b. Relationships & Data Flows
1. Browser → HTTP GET → Tomcat → CacheAndEncodingFilter → Controller → JCA ChannelAccess → EPICS PV → Controller → JSP/JSON → Browser
2. Browser → WebSocket handshake → MonitorEndpoint → WebSocketSessionManager → ChannelMonitor (JCA) subscribes to PV → On PV update: ChannelMonitor → MonitorEndpoint → Browser client JS callback
3. Integration Test harness spins up SoftIOC + epics2web services, then uses Java tests to exercise both REST (`GetTest.java`) and WS (`WebSocketTest.java`).

c. Architectural Patterns & Principles
- Layered architecture separating transport (HTTP/WebSocket), business logic (ChannelManager), and external system (EPICS network).
- Stateful session management in WebSocketSessionManager vs. stateless REST.
- Reuse of containers for development, testing, and production via Docker Compose.
- Convention-over-configuration for servlet filter and endpoint registration (annotations).

d. Key Technologies & Frameworks
- Java 17 (compiled to Java 8 bytecode), Gradle 7
- EPICS JCA library for Channel Access
- Java WebSocket API (javax.websocket)
- JSP + JSTL for server-side views
- Plain JS client (no heavy frontend framework)
- Docker, Docker Compose for orchestration
- GitHub Actions for CI/CD

##### Essential Elements
- Clear component names and roles (e.g., “ChannelManager: JCA wrapper”)
- Annotations for environment variables (EPICS_CA_ADDR_LIST, CONTEXT_PREFIX) if space permits

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "EPICS Network"
        direction TB
        PVSource["Soft IOC\n(EPICS PV Source)"]:::external
    end

    subgraph "Tomcat + epics2web.war"
        direction TB
        Application["Application.java"]:::server
        Filter["CacheAndEncodingFilter"]:::server
        CAGet["CAGet"]:::server
        TestGet["TestGet"]:::server
        TestMonitor["TestMonitor"]:::server
        Overview["Overview"]:::server
        WebConsole["WebConsole"]:::server
        MonitorEndpoint["MonitorEndpoint"]:::server
        SessionManager["WebSocketSessionManager"]:::server
        WriteStrategy["WriteStrategy"]:::server
        RequestListener["RequestListener"]:::server
        AuditConfigurator["AuditServerEndpointConfigurator"]:::server
        SessionMonitor["WebSocketSessionMonitor"]:::server
        SessionInfo["SessionInfo"]:::server
        AuditContext["WebSocketAuditContext"]:::server
        ChannelManager["ChannelManager"]:::server
        ChannelMonitor["ChannelMonitor"]:::server
        ContextFactory["ContextFactory"]:::server
        PvListener["PvListener"]:::server
    end

    subgraph "Browser Client"
        direction TB
        Browser["Browser"]:::client
        JSPViews["JSP & HTML Views"]:::client
        JSAPI["JavaScript API"]:::client
    end

    subgraph "Integration Tests"
        direction TB
        GetTest["GetTest"]:::test
        WebSocketTest["WebSocketTest"]:::test
    end

    %% Data Flows
    Browser -->|"HTTP GET"| Filter
    Filter --> CAGet
    Filter --> TestGet
    Filter --> TestMonitor
    Filter --> Overview
    Filter --> WebConsole
    CAGet -->|"uses"| ChannelManager
    TestGet -->|"uses"| ChannelManager
    TestMonitor -->|"uses"| ChannelManager
    Overview -->|"renders"| JSPViews
    WebConsole -->|"renders"| JSPViews
    ChannelManager --> ChannelMonitor
    ChannelMonitor -->|"subscribe"| PVSource
    CAGet -->|"response JSON/JSP"| Browser

    Browser -->|"WebSocket handshake"| MonitorEndpoint
    MonitorEndpoint --> SessionManager
    SessionManager --> ChannelMonitor
    ChannelMonitor -->|"subscribe"| PVSource
    PVSource -->|"PV update"| ChannelMonitor
    ChannelMonitor --> MonitorEndpoint
    MonitorEndpoint -->|"WS push"| JSAPI

    %% Integration tests interactions
    GetTest --> PVSource
    GetTest --> Application
    WebSocketTest --> PVSource
    WebSocketTest --> Application

    %% Click Events
    click Application "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/Application.java"
    click CAGet "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/controller/CAGet.java"
    click TestGet "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/controller/TestGet.java"
    click TestMonitor "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/controller/TestMonitor.java"
    click Overview "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/controller/Overview.java"
    click WebConsole "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/controller/WebConsole.java"
    click Filter "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/filter/CacheAndEncodingFilter.java"
    click MonitorEndpoint "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/websocket/MonitorEndpoint.java"
    click SessionManager "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/websocket/WebSocketSessionManager.java"
    click WriteStrategy "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/websocket/WriteStrategy.java"
    click RequestListener "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/websocket/RequestListener.java"
    click AuditConfigurator "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/websocket/AuditServerEndpointConfigurator.java"
    click SessionMonitor "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/websocket/WebSocketSessionMonitor.java"
    click SessionInfo "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/websocket/SessionInfo.java"
    click AuditContext "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/websocket/WebSocketAuditContext.java"
    click ChannelManager "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/epics/ChannelManager.java"
    click ChannelMonitor "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/epics/ChannelMonitor.java"
    click ContextFactory "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/epics/ContextFactory.java"
    click PvListener "https://github.com/jeffersonlab/epics2web/blob/main/src/main/java/org/jlab/epics2web/epics/PvListener.java"
    click JSPViews "https://github.com/jeffersonlab/epics2web/tree/main/src/main/webapp/WEB-INF/views"
    click JSAPI "https://github.com/jeffersonlab/epics2web/blob/main/src/main/webapp/resources/js/epics2web.js"
    click GetTest "https://github.com/jeffersonlab/epics2web/blob/main/src/integration/java/org/jlab/epics2web/GetTest.java"
    click WebSocketTest "https://github.com/jeffersonlab/epics2web/blob/main/src/integration/java/org/jlab/epics2web/WebSocketTest.java"

    %% Styles
    classDef external fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef server fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef client fill:#ffedcc,stroke:#333,stroke-width:1px
    classDef test fill:#e0e0e0,stroke:#333,stroke-width:1px
```
