Vue Application Structure
Relevant source files
The following files were used as context for generating this wiki page:
The PRKS Vue application comprises the Vue 3 and TypeScript source used for the incremental migration of the frontend. It operates as a set of features hosted within the legacy shell, rather than a standalone single-page application. The Vue application mounts on a hidden #prks-vue-root and teleports specific UI elements, such as performance diagnostics and workspace tabs, into the legacy DOM structure.
Sources: frontend-app/README.md:3-13, frontend/index.html:31-33
Core Architecture and Integration
The Vue application integrates with the legacy PRKS runtime through a series of owner-scoped bridges. It does not replace the canonical router or workspace state model. Instead, it renders projections of the state and sends intents back to the legacy coordinators.
Integration Flow
The following diagram illustrates how the Vue application mounts and interacts with the legacy shell.
The coordination between legacy JS and Vue happens through specific entry points like prksPresentVueRoute, which delivers host-local requests to Vue feature presenters.
Sources: frontend-app/README.md:10-25, frontend-app/AGENTS.md:37-45
Module Organization
The application source code is organized by technical role and feature domain.
| Path | Role |
|---|---|
src/workspace/ | Canonical typed workspace model and pure transforms. |
src/workspace-shell/ | Vue presentation for tab strips and pane frames. |
src/route-surface/ | Typed Vue route-instance lifecycle and owner-scoped mounting. |
src/api/ | Typed PRKS API client for feature services. |
src/components/ | Shared UI primitives and atomic components. |
src/features/ | Domain-specific logic (e.g., search, work, progress). |
Sources: frontend-app/README.md:34-53
Component Vocabulary
PRKS enforces a strict set of shared primitives to maintain visual consistency according to DESIGN.md. Feature components must reuse these primitives instead of creating raw HTML or local CSS overrides.
Shared Primitives
- PrksButton: Handles standard actions with variants (primary, secondary, ghost, danger).
- PrksLinkButton: Renders a native anchor styled as a button for navigation.
- PrksIconButton: Provides square icon-only controls with accessible names.
- PrksField: Wraps native inputs with labels, help text, and error states.
- PrksState: Manages loading, empty, and error states for collections.
- PrksRelSummary: Displays identity strips and relationship summaries.
Sources: frontend-app/AGENTS.md:21-34, frontend-app/README.md:65-88
Feature Implementation: Work Detail
The WorkMainSurface.vue component demonstrates the integration of these primitives and the layout of the primary research view.
Lifecycle and State Management
The application follows an owner-scoped lifecycle. Resources mounted by a route are released upon unmounting of that component.
Connectivity and Offline States
The system tracks connectivity through an offline runtime. Components subscribe to state changes to enable or disable mutation controls.
- Durable Operations: Mutations such as creating concepts or editing person profiles are durable. They are recorded locally and synchronized when connectivity is restored.
- Resource Ownership: Editor sessions (e.g., Research Notes) are suspendable. They are captured when mounting begins and can be parked "warm" or released "cold" depending on tab lifecycle.
Sources: frontend-app/AGENTS.md:46-64, frontend/js/components/people.js:84-142
Toolchain and Build Process
The Vue application uses Vite for bundling and TypeScript for type safety.
- Node.js Version: Requires
node >=24.15.0 <25. - Build Artifacts: The production bundle is emitted to
frontend/vue/prks-vue.js. - OpenAPI: Wire schemas are generated into
src/api/generated/from checked-in JSON artifacts. - Testing: Vitest handles unit and component tests, while Playwright is used for E2E browser testing.
Sources: frontend-app/package.json:6-45, frontend-app/README.md:27-32
The Vue Application Structure facilitates a hybrid architecture where modern Vue 3 components progressively replace legacy jQuery-style UI while respecting the existing reliable synchronization and routing systems.