Once the Jakarta EE 10 migration stabilized the servlet container baseline, Wikantik faced its next major architectural bottleneck: the presentation tier. For over two decades, Apache JSPWiki relied on server-side JavaServer Pages (JSP) coupled with custom JSP tag libraries (<wiki:PageExists>, <wiki:Link>, <wiki:Content>). Because those tag libraries coupled HTML rendering directly to server-side session state, adding interactive UI views or clean JSON APIs for automated clients was difficult.
To separate presentation from backend logic, we replaced server-rendered JSPs with a Vite and React Single Page Application (SPA) backed by stateless REST endpoints and PostgreSQL-backed Role-Based Access Control (RBAC).
The Monolithic Baseline: 20 Years of JSP Taglibs
The legacy JSPWiki user interface was deeply entwined with the Java servlet lifecycle. Rendering a single wiki page required:
- Stateful HTTP Sessions: Container-managed
WikiSessionobjects tied to cookie sessions and server-side memory. - Custom Tag Library Processing: Complex tag handler classes executing inside Tomcat's JSP compiler, interleaving HTML output with business logic, ACL checks, and localized resource bundle lookups.
- Static Policy Configuration: Security rules declared in a static
jspwiki.policyflat file using Java Security syntax:grant signedBy "jspwiki", principal org.apache.wiki.auth.authorize.Role "Authenticated" { permission org.apache.wiki.auth.permissions.PagePermission "*:*", "view,edit"; };
This design created severe limitations. Any modification to navigation or layout required recompiling server templates. More critically, an external AI agent or client application could not easily interact with the wiki without parsing raw HTML or navigating brittle, stateful session redirects.
The Presentation Decoupling: Vite and React
The first phase of the modernization extracted the user interface entirely from the Java web application archive. Rather than maintaining JSP templates under Jakarta Servlet 6.0, the frontend was rebuilt as a standalone Single Page Application:
- Vite Build Toolchain: Fast, modern bundling replacing old Maven resource-copy plugins for static assets.
- Modular React Architecture: Interactive components for page rendering, live markdown previewing, visual page-graph navigation (powered by Cytoscape.js), and administrative dashboards.
- Clean Root Mounting: The compiled React SPA is mounted cleanly at
/, with client-side routing managed via HTML5 History API filters inweb.xmlthat forward non-API requests toindex.html. - Strict REST Boundary: All interaction between the frontend and the core Java wiki engine now flows through stateless, versioned REST endpoints under
/api/*.
Decoupling the frontend wasn't merely a facelift; it fundamentally changed how permissions and rendering interact. In the legacy JSP model, permissions were checked lazily inside custom taglib blocks during page generation, leading to partial renders when permissions failed mid-stream. In the decoupled architecture, permission evaluation is strictly pre-flighted at the REST boundary, returning clean HTTP 401 or 403 problem details before any rendering state is transferred.
Security Modernization: From Static XML to Relational RBAC
Replacing the UI exposed the fragility of the legacy authorization model. Maintaining a flat jspwiki.policy file across distributed container instances was untenable in production cloud environments. Administrators could not grant permissions, revoke privileges, or onboard user groups without modifying local disk files and triggering container reloads.
Wikantik replaced the static file model with a dynamic, relational security engine:
1. Dynamic Policy Grants Table
All authorization rules were migrated to PostgreSQL in a dedicated policy_grants schema. Each record defines a principal (user UID or role group), an action permission (view, edit, comment, upload, admin), a target pattern, and optional temporal or tenant constraints. Security checks that previously traversed JAAS policy providers now query an in-memory, cache-invalidated permission tree synchronized with the database.
2. Enterprise SSO via Pac4j
Modern enterprise deployments demand identity federation. Wikantik integrated pac4j into the Jakarta filter pipeline, providing native support for OpenID Connect (OIDC) and SAML 2.0. Users and AI agent administrators authenticate against corporate identity providers (such as Okta, Keycloak, or Google Workspace), with claims mapped seamlessly into Wikantik principals upon successful assertion.
3. Administrative Security Control
Because security policies now reside in relational storage, administrators manage user access directly through the new React admin console. Creating an agent service account, restricting access to sensitive knowledge clusters, or revoking a compromised token no longer requires SSH access or container restarts.
Retaining Load-Bearing Foundations
In modernizing the presentation and security tiers, Wikantik avoided the classic rewrite trap of discarding battle-tested storage logic. The core abstraction for managing physical page files—the PageProvider interface and its VersioningFileProvider implementation—remained intact under the newly extracted wikantik-api module.
Page version history, diff calculation, and concurrency locks continued to operate on disk through the existing provider interface, while the web and security layers were moved to REST and PostgreSQL. The next post in this series covers how we built the hybrid BM25 and pgvector search engine.
Comments