Frontend Architecture

Purpose and Scope

This document explains Telescope's frontend architecture, focusing on the Vue.js Single Page Application (SPA) structure, routing system, component hierarchy, and integration patterns with the backend API. It covers the application shell, Vue application bootstrap process, the 18+ entry-type-specific routes, global UI controls, and the configuration bridge between server and client.

For information about asset compilation and build processes, see Asset Management and Build System. For backend API endpoints and data structures, see Repository Pattern.

---

Application Shell Structure

The frontend is delivered through a Blade template that serves as the HTML shell for the Vue.js application. This shell provides the initial DOM structure, configuration injection, and asset loading.

HTML Bootstrap Process

Sources: resources/views/layout.blade.php1-237

Key DOM Structure

The application shell defines several critical DOM elements:

Element	Location	Purpose
#telescope	Line 20	Root Vue application mount point with v-cloak directive
<alert> component	Lines 21-26	Global notification system with type, message, and confirmation handlers
.header container	Lines 29-65	Top navigation bar with logo, controls, and monitoring link
.sidebar navigation	Lines 68-220	Left sidebar with 18 entry-type route links
<router-view>	Line 224	Dynamic content area managed by Vue Router

Sources: resources/views/layout.blade.php20-227

Configuration Bridge

Server configuration is injected into the client via the window.Telescope global object:

The configuration object is serialized as JSON and embedded in a <script> block at resources/views/layout.blade.php231-233 This provides the Vue application with server-side settings including the base path, timezone, recording state, and other runtime configuration without requiring an initial API call.

Sources: resources/views/layout.blade.php231-233

---

Routing System

Telescope's frontend implements an 18-route navigation system for different entry types, plus additional utility routes.

Route Structure

Navigation Implementation

The sidebar navigation is implemented as a static list of <router-link> components with the active-class="active" attribute for visual feedback:

Route	Lines	Label	SVG Icon
/requests	71-76	Requests	Bidirectional arrows
/commands	79-84	Commands	Terminal icon
/schedule	87-92	Schedule	Clock icon
/jobs	95-100	Jobs	Queue icon
/batches	105-110	Batches	List icon
/cache	113-119	Cache	Rocket icon
/dumps	122-127	Dumps	Code brackets
/events	130-135	Events	Broadcast icon
/exceptions	138-143	Exceptions	Bug icon
/gates	146-151	Gates	Lock icon
/client-requests	154-159	HTTP Client	Globe icon
/logs	162-168	Logs	Archive icon
/mail	171-177	Mail	Envelope icon
/models	180-185	Models	ID card icon
/notifications	188-194	Notifications	Bell icon
/queries	197-202	Queries	Database icon
/redis	205-210	Redis	Redis logo
/views	213-218	Views	Browser window icon

Sources: resources/views/layout.blade.php69-220

Router View Integration

The main content area uses Vue Router's <router-view> component at resources/views/layout.blade.php224 to dynamically render the appropriate entry-type component based on the current route. This is a standard Vue Router pattern where:

1. User clicks a sidebar <router-link>
2. Vue Router updates the URL and active route
3. The matched route component renders into <router-view>
4. The component makes API calls to fetch entry data
5. Entries are displayed in the component's template

Sources: resources/views/layout.blade.php224

---

Component Architecture

The application follows a hierarchical component structure with a root application component, global UI controls, and route-specific entry views.

Component Hierarchy

Sources: resources/views/layout.blade.php20-227

Alert Component

The global alert system is implemented as a component with the following props and behavior:

The alert component is defined at resources/views/layout.blade.php21-26 and conditionally renders based on the alert.type value. It supports both simple notifications (with auto-close) and confirmation dialogs (with proceed/cancel callbacks).

Sources: resources/views/layout.blade.php21-26

---

Global Controls and Interactions

The header contains four primary control mechanisms that manage recording state and data operations globally across all views.

Control Button Structure

Sources: resources/views/layout.blade.php38-64

Control Button Specifications

Control	Line Range	Event Handler	State Variable	Icon Logic
Recording Toggle	38-45	toggleRecording	recording	Pause icon when true, Play icon when false
Clear Entries	47-51	clearEntries	N/A	Static trash can icon
Auto Load	53-57	autoLoadNewEntries	autoLoadsNewEntries	Static refresh icon, active class when enabled
Monitoring	59-64	Router navigation	N/A	Static eye icon

Interaction Patterns

1. Recording Toggle: Calls toggleRecording method which likely makes a POST request to the backend to pause/resume data collection. The recording state updates the button title attribute and icon display.

2. Clear Entries: Invokes clearEntries method, presumably sending a DELETE request to clear all recorded entries from storage. May show confirmation dialog via the alert component.

3. Auto Load: Toggles the autoLoadsNewEntries boolean state, enabling/disabling automatic polling for new entries. The active class provides visual feedback.

4. Monitoring: Uses Vue Router's <router-link> component for client-side navigation to the monitored tags configuration page.

Sources: resources/views/layout.blade.php38-64

---

API Integration Patterns

The Vue application communicates with the backend through HTTP requests to fetch entry data, manage recording state, and perform data operations.

Request Flow Architecture

API Endpoint Structure

Based on the frontend architecture, the Vue components communicate with these endpoint patterns:

Operation	Method	Endpoint Pattern	Purpose
Fetch Entries	GET	/telescope/telescope-api/{type}	Retrieve entries by type (requests, queries, etc.)
Clear All	POST	/telescope/telescope-api/clear	Delete all entries
Toggle Recording	POST	/telescope/telescope-api/toggle-recording	Pause/resume data collection
Get Entry Detail	GET	/telescope/telescope-api/{type}/{id}	Retrieve single entry with full details

These endpoints are registered by the TelescopeServiceProvider and protected by middleware. See Service Provider and Bootstrap for backend route registration details.

Sources: Based on diagram analysis and standard Laravel resource patterns

Data Fetching Patterns

Entry-type components follow this general pattern for data fetching:

1. Component Mount: On route activation, the component's mounted() lifecycle hook triggers
2. Initial Load: Component makes GET request to fetch initial page of entries
3. Pagination: User scrolling or pagination controls trigger additional requests with offset parameters
4. Auto-Refresh: If autoLoadsNewEntries is enabled, component polls the API at intervals
5. Filtering: Query parameters added to API requests for filtering by tags, status, etc.

Response Handling

API responses return JSON-serialized EntryResult objects with this structure:

• id: Entry UUID
• type: Entry type (request, query, exception, etc.)
• content: Array of entry-specific data fields
• created_at: Timestamp
• tags: Array of associated tag strings
• Additional metadata varies by entry type

Sources: Inferred from EntryResult structure and common Vue data binding patterns

---

Asset Loading and Versioning

The application shell loads compiled frontend assets using Laravel Mix's versioning system.

Asset Loading Flow

Mix Manifest Structure

The public/mix-manifest.json1-6 file maps logical asset names to versioned filenames:

The hash-based query parameters enable cache-busting: when assets change, the hash changes, forcing browsers to download the new version.

Asset Loading in Template

CSS assets are loaded in the <head> section:

• Line 17: {{ asset(mix($cssFile, 'vendor/telescope')) }}

JavaScript is loaded at the end of <body>:

• Line 235: {{ asset(mix('app.js', 'vendor/telescope')) }}

The mix() helper function reads the manifest file and returns the versioned URL. The second parameter 'vendor/telescope' specifies the asset namespace within Laravel's public directory structure.

Sources: resources/views/layout.blade.php17 resources/views/layout.blade.php235 public/mix-manifest.json1-6

---

Application Bootstrap Sequence

The complete initialization process follows this sequence:

Bootstrap Phases

1. Server-Side Rendering (Lines 1-233):

   • Blade template generates HTML structure
   • Configuration serialized to window.Telescope object
   • Asset URLs resolved via mix() helper

2. Configuration Injection (Lines 231-233):

   • telescopeScriptVariables serialized as JSON
   • Global window.Telescope object created before Vue loads
   • Configuration immediately available to application code

3. Vue Application Initialization (Line 235):

   • app.js bundle loaded and executed
   • Vue instance created and configured
   • Global mixins and plugins registered

4. Router Setup:

   • Vue Router instance created with 18+ route definitions
   • Routes mapped to component imports
   • Initial route matched based on URL path

5. Component Mounting:

   • Vue mounts to #telescope DOM element
   • Root component template replaces v-cloak placeholder
   • Matched route component renders into <router-view>

6. Initial Data Load:

   • Mounted route component's lifecycle hooks execute
   • API requests fired to fetch initial entry data
   • Loading states and skeleton screens displayed

Sources: resources/views/layout.blade.php1-237

---

State Management Patterns

While the codebase doesn't appear to use Vuex or a formal state management library, state is managed through:

1. Component-Level State: Each route component maintains its own entry list, loading state, and filters
2. Root-Level State: Recording status, auto-load toggle, and alert state stored in root Vue instance
3. Shared Configuration: window.Telescope object provides read-only server configuration
4. Router State: Current route and route parameters tracked by Vue Router

Reactive State Flow

Global controls update root-level state, which propagates to child components via props or event bus patterns. Route components independently manage their entry data but share common behaviors through mixins.

Sources: Based on standard Vue.js patterns and component structure visible in resources/views/layout.blade.php20-227

---

Summary

Telescope's frontend architecture implements a clean separation between the server-rendered HTML shell and the Vue.js SPA. The layout.blade.php template provides the application structure, configuration injection via window.Telescope, and asset loading through Laravel Mix. The Vue application uses Vue Router to manage 18+ entry-type-specific routes, with components rendering into a shared <router-view> outlet. Global controls for recording management, data operations, and navigation are implemented in the header, while a sidebar provides route navigation. The application communicates with the backend via RESTful API endpoints, fetching entry data on route activation and responding to user interactions. Asset versioning through mix-manifest.json ensures cache-busting for production deployments.