Architecture Design

Understanding the Cinder Frontend's technical foundation and data flow.

High-Level Overview

The Cinder Frontend is a SvelteKit application that interacts with the Cinder Go backend through a secure, type-safe RPC-like interface powered by Remote Functions.

Data Flow Pipeline

User Interaction

User enters a URL or query in a Svelte 5 component.

Remote Function Call

Component calls a function imported from src/remote/cinder.remote.ts

Server-Side Execution

SvelteKit executes the function on the server, retrieving private environment variables for secure API communication.

Backend Request

The server makes a fetch call to the Go backend with the API key attached.

Response Serialization

SvelteKit serializes the response and returns it directly to the browser.

Reactive UI Update

The UI reactively updates using Svelte 5 runes ($state, $derived, $effect).

Technology Stack

Frontend Framework

Frontend Framework SvelteKit 5

Full-stack meta-framework with remote functions support.

Reactivity

Reactivity Svelte 5 Runes

$state, $derived, $effect, $props for fine-grained reactivity.

Styling

Styling Tailwind CSS v4

Utility-first CSS with OKLCH color space & Cinder Glow theme.

Components

Components shadcn-svelte

Headless component primitives with Tailwind styling.

Validation

Validation Valibot

Type-safe schema validation for all remote function inputs.

API Communication

API Communication Remote Functions

Type-safe server-side RPC calls with automatic serialization.

Svelte 5 Runes & Remote Functions

Modern Reactivity

All components use Svelte 5 runes for fine-grained reactivity. Legacy patterns like let, $:, and export let are not used.

$state - Component State

let url = $state('');
let isLoading = $state(false);

$derived - Computed Values

let isValid = $derived(url.startsWith('http'));
let errorCount = $derived(errors.length);

$effect - Side Effects

$effect(() => {
  if (crawlForm.result?.id) {
    const interval = setInterval(() => {
      statusQuery.refetch(crawlForm.result.id);
    }, 2000);
    return () => clearInterval(interval);
  }
});

Remote Functions - API Calls

// Query pattern - for reading data
let statusQuery = getCrawlStatus();

// Form pattern - for mutations
let scrapeForm = scrapeUrl();
<form method="POST" use:scrapeForm.enhance>
  <input {...scrapeForm.fields.url.as('text')} />
</form>

Directory Structure

/src
├── lib/
│   ├── components/        # Reusable UI components
│   │   ├── ui/           # shadcn-svelte primitives
│   │   └── blocks/       # Composed feature blocks
│   └── utils.ts          # Helper functions
├── remote/
│   └── cinder.remote.ts  # Server-side RPC functions
└── routes/
    ├── +layout.svelte    # Global layout
    ├── playground/       # Main feature page
    └── docs/            # Documentation pages

All backend communication flows through src/remote/cinder.remote.ts, which handles API calls, validation, and type safety.

Security & Environment Variables

Secrets Protection

API keys and authentication credentials are stored in private environment variables and never exposed to the browser.

PRIVATE_CINDER_BACKEND_URL Backend service endpoint (server-side only)

PRIVATE_CINDER_API_KEY Authentication key for backend (server-side only)

Data Flow Security

✓ API keys remain on the server, never sent to the client
✓ All backend communication happens server-side
✓ Results are serialized and returned to the browser
✓ No direct client-to-backend communication

Design Principles

Simplicity

Minimal abstraction layers. Direct communication between UI and backend through type-safe remote functions.

Type Safety

Full TypeScript support with Valibot schemas for validation. Compile-time and runtime checking.