Web Frontend

🌐 SolidJS-based progressive web application for PiSovereign

The web frontend provides a modern chat interface for interacting with PiSovereign through any browser. It is built with SolidJS and embedded directly into the Rust binary at compile time via rust-embed.

Table of Contents

• Overview
• Technology Stack
• Architecture
  • Directory Structure
  • Component Architecture
  • State Management
  • API Client Layer
• Development
  • Prerequisites
  • Getting Started
  • Available Commands
  • Development Workflow
• Build & Deployment
  • Production Build
  • Rust Integration
  • Docker Build
• Testing
• Code Quality
• PWA Support
• Styling
• Security

Overview

PiSovereign’s web frontend is a single-page application (SPA) that communicates with the backend via REST and Server-Sent Events (SSE). Key design goals:

• Zero external hosting — Assets are embedded in the Rust binary, no separate web server needed
• Offline-capable — PWA with service worker for offline resilience
• Privacy-first — No external CDNs, fonts, or analytics; everything is self-contained
• Lightweight — ~200 KB production bundle with code splitting

Technology Stack

Architecture

Directory Structure

crates/presentation_web/
├── Cargo.toml              # Rust crate manifest
├── dist/                   # Vite build output (gitignored)
├── frontend/               # SolidJS source code
│   ├── index.html          # HTML entry point
│   ├── package.json        # Node dependencies
│   ├── tsconfig.json       # TypeScript configuration
│   ├── vite.config.ts      # Vite build configuration
│   ├── vitest.config.ts    # Test configuration
│   └── src/
│       ├── index.tsx        # Application entry point
│       ├── app.tsx          # Root component with router
│       ├── api/             # REST & SSE API clients
│       ├── components/      # Reusable UI components
│       │   └── ui/          # Base UI primitives
│       ├── hooks/           # Reactive hooks
│       ├── lib/             # Utilities (cn, format, sanitize)
│       ├── pages/           # Route page components
│       ├── stores/          # Global state stores
│       └── types/           # TypeScript type definitions
└── src/                    # Rust source code
    ├── lib.rs              # Crate root
    ├── assets.rs           # rust-embed asset struct
    ├── csp.rs              # Content Security Policy
    ├── handler.rs          # Static file handler with caching
    └── routes.rs           # SPA router & axum integration

Component Architecture

The frontend follows a layered component architecture:

Pages (routes)
  └── Composed Components (chat, settings panels)
        └── UI Primitives (Button, Card, Modal, Badge, Spinner)
              └── Utility Functions (cn, format, sanitize)

Pages are lazy-loaded via solid-router for code splitting:

• / — Chat interface (main interaction view)
• /settings — Application settings
• /commands — Available bot commands
• /memories — Memory inspection
• /audit — Audit log viewer
• /health — System health dashboard

UI Primitives (components/ui/) are unstyled, composable building blocks:

• Button — With variants (default, outline, ghost, destructive) and sizes
• Card — Container with header/content/footer slots
• Modal — Dialog with focus trap and backdrop
• Badge — Status indicators with color variants
• Spinner — Loading indicators

State Management

Global state uses SolidJS signals organized into stores:

Stores are accessed via the StoreProvider context, available throughout the component tree.

API Client Layer

The api/ directory contains typed REST clients:

All API calls go through client.ts, which handles:

• Bearer token injection from the auth store
• Base URL resolution (same origin in production, proxy in dev)
• JSON serialization/deserialization
• Error response mapping

Development

Prerequisites

• Node.js ≥ 22 (LTS recommended)
• npm ≥ 10

Getting Started

# Install dependencies
just web-install

# Start development server with hot reload
just web-dev

The Vite dev server starts on http://localhost:5173 and proxies API requests to the backend at http://localhost:3000.

Available Commands

All frontend tasks are available via just:

Development Workflow

1. Start the backend: just run or cargo run
2. Start the frontend dev server: just web-dev
3. Open http://localhost:5173 in your browser
4. Edit SolidJS components — changes are reflected instantly via HMR

The Vite dev server proxies /api/* requests to localhost:3000, so you get the full API available during development.

Build & Deployment

Production Build

just web-build

This runs vite build which outputs optimized assets to crates/presentation_web/dist/. The build:

• Tree-shakes unused code
• Minifies JS/CSS
• Adds content hashes to filenames for cache busting
• Generates PWA service worker
• Code-splits routes for lazy loading
• Outputs ~200 KB total (gzipped ~60 KB)

Rust Integration

The presentation_web crate embeds the dist/ directory at compile time using rust-embed:

#[derive(Embed)]
#[folder = "dist/"]
pub struct FrontendAssets;

The Rust handler layer provides:

• Content-type detection — MIME types based on file extension
• Cache control — Immutable caching for hashed assets, no-cache for HTML
• ETag support — Conditional requests via If-None-Match
• CSP headers — Content Security Policy for XSS protection
• SPA fallback — Unknown routes serve index.html for client-side routing

Important: You must run just web-build before cargo build so the dist/ directory is populated. The Docker build handles this automatically.

Docker Build

The Dockerfile uses a multi-stage build:

# Stage 1: Build frontend
FROM node:22-alpine AS frontend-builder
COPY crates/presentation_web/frontend/ .
RUN npm ci && npm run build

# Stage 2: Build Rust binary
FROM rust:1.93-slim-bookworm AS builder
COPY --from=frontend-builder /app/dist/ crates/presentation_web/dist/
RUN cargo build --release

# Stage 3: Runtime
FROM debian:bookworm-slim
COPY --from=builder /app/target/release/pisovereign .

This ensures the frontend is always built fresh and embedded into the binary.

Testing

Unit & Component Tests

Tests use Vitest with @solidjs/testing-library for component tests and MSW (Mock Service Worker) for API mocking.

# Run all tests
just web-test

# Run with coverage
just web-test-coverage

Test structure mirrors the source layout:

frontend/src/
├── lib/__tests__/          # Utility tests (cn, format, sanitize)
├── stores/__tests__/       # Store logic tests
├── api/__tests__/          # API client tests
└── components/ui/__tests__/ # Component rendering tests

Current coverage: 93 tests across utilities, stores, API clients, and UI components.

End-to-End Tests (Playwright)

The project includes Playwright-based E2E journey tests that simulate real user interactions against a live application instance on localhost:3000. These tests cover every page, CRUD operation, and user action in the frontend.

Setup

# Install Playwright browsers (one-time)
just web-e2e-install

# Ensure the Docker stack is running
just docker-up

Running E2E Tests

# Run all journey tests
just web-e2e

# Run with interactive UI (for debugging)
just web-e2e-ui

# View the last HTML report
just web-e2e-report

Skipping LLM-Dependent Tests

Tests tagged @llm (Chat, Agentic) require Ollama to be running. To skip them:

cd crates/presentation_web/frontend && npx playwright test --grep-invert @llm

Architecture

frontend/e2e/
├── global-setup.ts              # Authenticates once, saves session cookie
├── fixtures/
│   └── auth.fixture.ts          # Pre-authenticated page fixture
├── reporters/
│   └── bugreport.reporter.ts    # Auto-generates bug reports on failure
├── helpers/
│   ├── navigation.helper.ts     # Sidebar navigation, page-load utilities
│   └── form.helper.ts           # Form fills, modal helpers, test IDs
└── journeys/
    ├── auth.journey.spec.ts         # Login, logout, session persistence
    ├── dashboard.journey.spec.ts    # Stat cards, quick actions, sections
    ├── chat.journey.spec.ts         # Send message, SSE streaming (@llm)
    ├── conversations.journey.spec.ts # List, search, delete conversations
    ├── commands.journey.spec.ts     # Parse, execute, catalog CRUD
    ├── approvals.journey.spec.ts    # List, approve, deny requests
    ├── contacts.journey.spec.ts     # Full CRUD + search
    ├── calendar.journey.spec.ts     # Views, event CRUD, date navigation
    ├── tasks.journey.spec.ts        # Task CRUD, filters, completion
    ├── kanban.journey.spec.ts       # Board columns, filter buttons
    ├── memory.journey.spec.ts       # Memory CRUD, search, decay, stats
    ├── agentic.journey.spec.ts      # Multi-agent task lifecycle (@llm)
    ├── mailing.journey.spec.ts      # Email list, refresh, mark read
    └── system.journey.spec.ts       # Status, models, health checks

Writing New Journey Tests

Journey tests follow a consistent pattern using test.step() for structured reproduction steps:

import { test, expect } from '../fixtures/auth.fixture';

test.describe('Feature Journey', () => {
  test('complete user flow', async ({ page }) => {
    await test.step('navigate to the page', async () => {
      await page.goto('/feature');
      await page.waitForLoadState('networkidle');
    });

    await test.step('perform user action', async () => {
      await page.locator('button:has-text("Action")').click();
      await expect(page.locator('text=Result')).toBeVisible();
    });
  });
});

Key conventions:

• File naming: {feature}.journey.spec.ts
• Test steps: Use test.step() — these feed the bugreport reporter for clear reproduction steps
• Data cleanup: Create test data with unique IDs (testId() helper) and clean up in afterAll or at the end of the test
• Timeouts: Use generous timeouts (60s) for LLM/SSE-dependent tests and tag them with @llm
• Resilience: Use .catch(() => false) for optional UI elements that may or may not exist depending on backend state

Automatic Bug Reports

When a test fails, the custom BugreportReporter writes a detailed markdown file to bugreports/:

• Title and test metadata (file, line, browser, duration)
• Steps to reproduce extracted from test.step() annotations
• Error message and stack trace
• Screenshot paths (captured on failure)
• Environment details (OS, Node.js version)

Bug reports are named YYYY-MM-DD-e2e-{test-slug}.md for chronological ordering.

Code Quality

The project enforces strict code quality standards:

• TypeScript strict mode — All strict checks enabled, including exactOptionalPropertyTypes
• ESLint — SolidJS-specific rules + TypeScript checks (0 errors required)
• Prettier — Consistent formatting
• Pre-commit checks — just pre-commit runs lint, typecheck, and tests

Quality gates are integrated into the just quality and just pre-commit recipes, which run both frontend and backend checks together.

PWA Support

The frontend is a Progressive Web App with:

• Service Worker — Generated by vite-plugin-pwa using Workbox
• Offline support — Cached assets served when offline
• Installable — Add to home screen on mobile devices
• Web manifest — App name, icons, theme colors defined in manifest.webmanifest

The service worker uses a cache-first strategy for static assets and network-first for API calls.

Styling

Styling uses Tailwind CSS v4 with a custom design system:

• CSS custom properties for theming (dark/light mode)
• Utility classes for layout, spacing, typography
• cn() helper — Merges Tailwind classes with conflict resolution via tailwind-merge + clsx
• No external CSS frameworks — Everything is built from Tailwind utilities

The color palette follows a navy/slate theme matching PiSovereign’s brand identity.

Security

The embedded frontend includes several security measures:

• Content Security Policy (CSP) — Restricts script sources, style sources, and connections
• No inline scripts — All JavaScript is loaded from hashed asset files
• Same-origin API calls — No cross-origin requests by design
• No external dependencies at runtime — Fonts, icons, and all assets are self-hosted
• Auth token handling — Tokens stored in memory (SolidJS signals), not localStorage

See the Security Hardening guide for production deployment recommendations.