Cinder Docs
Documentation
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 enters a URL or query in a Svelte 5 component.
Component calls a function imported from src/remote/cinder.remote.ts
SvelteKit executes the function on the server, retrieving private environment variables for secure API communication.
The server makes a fetch call to the Go backend with the API key attached.
SvelteKit serializes the response and returns it directly to the browser.
The UI reactively updates using Svelte 5 runes ($state, $derived, $effect).
Technology Stack
Full-stack meta-framework with remote functions support.
$state, $derived, $effect, $props for fine-grained reactivity.
Utility-first CSS with OKLCH color space & Cinder Glow theme.
Headless component primitives with Tailwind styling.
Type-safe schema validation for all remote function inputs.
Type-safe server-side RPC calls with automatic serialization.
Svelte 5 Runes & Remote Functions
are not used.let,$:, andexport let
$state Component State
Declares reactive variables that trigger UI updates when changed.
let url = $state('');
let isLoading = $state(false);$derived Computed Values
Automatically updated computed values that depend on state.
let isValid = $derived(url.startsWith('http'));
let errorCount = $derived(errors.length);$effect Side Effects
Handle side effects like timers, subscriptions, and DOM manipulation.
$effect(() => {
if (crawlForm.result?.id) {
const interval = setInterval(() => {
statusQuery.refetch(crawlForm.result.id);
}, 2000);
return () => clearInterval(interval);
}
});Remote Functions API Calls
Type-safe server-side functions for data fetching and mutations.
// 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
├── +layout.svelte
├── +page.svelte
├── architecture/
├── features/
├── setup/
├── theme/
└── user-flow/All backend communication flows through src/remote/cinder.remote.ts , which handles API calls, validation, and type safety.
Security & Environment Variables
PRIVATE_CINDER_BACKEND_URL
Backend service endpoint (server-side only)
PRIVATE_CINDER_API_KEY
Authentication key for backend (server-side only)
✓ 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