UI Design Specification (legacy root)

PHIDS User Interface Design Specification: A Server-Driven Hypermedia Architecture

1. Introduction and Architectural Paradigm

The Plant-Herbivore Interaction & Defense Simulator (PHIDS) Control Center is designed as a high-performance, server-driven web interface. Departing from computationally heavy client-side Single-Page Application (SPA) frameworks, the architecture employs a Hypermedia-Driven Application (HDA) paradigm. It utilizes FastAPI and Jinja2 for server-side rendering, Tailwind CSS for responsive styling, and HTMX for asynchronous, dynamic Document Object Model (DOM) updates.

This methodology centralizes all complex domain logic—such as the enforcement of the "Rule of 16," interaction matrix validation, and scenario serialization—strictly within the Python backend. Client-side JavaScript is minimized almost entirely, strategically isolated only to the high-frequency rendering of the HTML5 via WebSocket streams.

Note for Automated Code Generators: This document explicitly defines the DOM hierarchies, Tailwind utility classes, and HTMX attributes required to construct the interface. Generators must strictly adhere to these structural descriptions to fulfill the visual and functional requirements without requiring external wireframes.

1. Structural Layout and Hypermedia Navigation

The interface utilizes a full-viewport flexbox layout (h-screen w-full flex bg-slate-50 text-slate-900). It is spatially organized into a persistent sidebar navigation layer and a dynamic main content workspace. Transitions between distinct configuration modules must not require full page reloads; instead, they are executed via HTMX partial swaps.

Sidebar Navigation Layer (Left): A fixed-width column (w-64 bg-slate-900 text-slate-100 flex flex-col shadow-xl z-10).

It must contain vertical navigation links categorized into "Views" (Dashboard, Biotope Configuration), "Rule of 16 Entities" (Flora, Predators, Substances), and "Interactions" (Diet and Trigger Matrices).

Navigation links must utilize hx-get targeting the main content area (hx-target="#main-workspace") and employing hx-swap="innerHTML".

The bottom of the sidebar must house localized File I/O controls (Load/Export JSON buttons).

Main Workspace (Right): A flex-column container (flex-1 flex flex-col h-screen overflow-hidden).

Global Header: A persistent, sticky top header (h-16 bg-white border-b border-slate-200 px-6 flex items-center justify-between shadow-sm z-10). It must display the current Scenario Name, a dynamic Simulation Tick counter, and simulation state controls (Start, Pause, Step, Reset buttons). These buttons must utilize hx-post to trigger backend state changes.

Content Container: A scrollable area (flex-1 overflow-auto p-6) with the ID #main-workspace. This is the designated target for all sidebar HTMX navigation swaps.

1. Core Capabilities and System Modules

3.1 Live Dashboard and Isolated Canvas Rendering

The Dashboard (#dashboard-view) serves as the primary observation deck during active simulation execution. It is structured as a CSS grid or flex column containing two primary visual panels:

WebSocket Canvas Stream (Top Panel): A large, elevated container (bg-white rounded-xl shadow-sm border p-4).

Visual Structure: Must contain an HTML5 styled to fill its container with image-rendering: pixelated;.

Technical Behavior: Standard HTML DOM elements are bypassed for grid rendering. A strictly isolated, minimal block of Vanilla JavaScript establishes a continuous WebSocket connection (/ws/simulation/stream) to the FastAPI backend. It ingests compressed binary state payloads and utilizes the Canvas API to paint the localized Cellular Automata grid, delineating flora (e.g., green fill) and predator swarms (e.g., red fill) at a consistent tick rate.

Lotka-Volterra Telemetry (Bottom Panel): A shorter container beneath the canvas.

Visual Structure: Displays a scalable vector graphic (SVG) chart.

Technical Behavior: Historical ecological metrics (e.g., aggregate flora energy, predator cluster sizes) are aggregated server-side via polars. The SVG chart is generated by the Python backend and seamlessly swapped into a designated

via an HTMX polling mechanism (e.g., hx-get="/api/telemetry" hx-trigger="every 1s"), entirely avoiding the need for heavy client-side charting libraries.

3.2 Global Biotope Configuration

This module (#biotope-config-view) governs the foundational topology and environmental constants via standard HTML forms.

Visual Structure: A centered, card-like container (max-w-2xl bg-white rounded-xl shadow-sm border p-6). It utilizes a CSS Grid (grid grid-cols-2 gap-6) for form layout.

Form Elements:

Grid Constraints: Numeric fields for Width and Height (min 10, max 80).

Meteorological Vectors: Numeric fields allowing decimal steps for Wind Vector X and Wind Vector Y.

Technical Behavior: The form must utilize hx-post="/api/config/biotope" with hx-trigger="change" to automatically submit updates to the backend upon user modification, triggering pydantic validation.

3.3 Entity Definition Management (The "Rule of 16")

The backend rigorously enforces the architectural "Rule of 16" constraint. The UI dynamically renders configuration tables (#entity-config-view) based on the backend state.

Visual Structure: Each entity category (Flora, Predators, Substances) is displayed as a comprehensive HTML

(w-full divide-y divide-slate-200). The table header (thead bg-slate-50) labels the specific attributes. Above the table, an "Add New Entity" button must be present, visually disabled if the row count reaches 16.

Form Inputs per Row:

Flora: Text input for Name; Numeric inputs for Max Energy, Growth Rate, Reproduction Cost; Checkbox for Symbiotic Network.

Predators: Text input for Name; Numeric inputs for Speed, Eating Rate, Reproduction Threshold.

Substances: Text input for Name; dropdown for Type (Signal, Lethal Toxin, Repellent Toxin); Numeric inputs for Production Time, Aftereffect Time, Lethality Rate.

Technical Behavior: Modifying any input field within a row must trigger an hx-post or hx-put containing the row's specific ID to update the singular attribute on the backend. The "Delete" button per row executes an hx-delete targeted at the row's ID, utilizing hx-target="closest tr" and hx-swap="outerHTML swap:1s" for graceful removal.

3.4 Interaction Matrices

Biological interactions are configured through dynamic grid-based tables generated by Jinja2 templates (#matrices-view).

Diet Compatibility Matrix:

Visual Structure: A 2D HTML

. Row headers (first column) represent $E_i$ (Predator Species names). Column headers (first row) represent $P_j$ (Flora Species names).

Technical Behavior: Each intersecting cell contains a . Toggling the checkbox triggers an hx-post="/api/matrices/diet" to update the backend mapping defining whether predator $E_i$ can consume flora $P_j$.

Substance Trigger Matrix:

Visual Structure: A 2D HTML

. Row headers represent $P_j$ (Flora Species). Column headers represent $E_i$ (Predator Attackers).

Technical Behavior: Each intersecting cell contains a dropdown populated with available Substance names. Modifying the selection triggers an hx-post="/api/matrices/trigger", dictating which chemical defense is synthesized during that specific interaction.

1. Scenario Serialization and File I/O

To guarantee experimental reproducibility, the system incorporates comprehensive JSON serialization capabilities, handled entirely via standard HTTP protocols within the Sidebar.

Payload Generation (Export): An anchor link styled as a button () that triggers a standard GET request. The Python backend aggregates all current configurations into a strictly formatted JSON object and responds with a FileResponse, initiating a direct download.

Payload Ingestion (Import): A hidden

paired with a visible "Upload" button label. Utilizing HTMX (hx-post="/api/scenario/import" hx-encoding="multipart/form-data"), the backend parses the uploaded JSON payload, validates it via Pydantic, repopulates the server-side state, and subsequently responds with an HTMX header (e.g., HX-Refresh: true) to force a full workspace refresh, displaying the newly imported parameters.

1. Technical Implementation Details (The Tri-Partite Architecture)

Code generators must strictly adhere to a tri-partite technological division to ensure optimal performance and maintainability:

Python and Jinja2 (State & Logic): The authoritative source of truth. All HTML generation, grid loops ({% for plant in plants %}), state management, "Rule of 16" enforcement, matrix validation, and complex logic reside securely on the server.

HTMX (Navigation & Mutation): Facilitates Single-Page Application responsiveness without JavaScript build steps. HTML attributes (hx-get, hx-post, hx-target, hx-swap, hx-trigger) declare how the client interacts with the server. Forms and inputs should utilize these attributes exclusively to mutate state.

Vanilla JavaScript (Isolated Rendering): Sequestered entirely to the Dashboard module. A singular