Backend Systems

Furin is a React meta-framework that uses Elysia as its underlying web server and Bun as its runtime. The backend architecture provides file-based routing with multiple rendering modes, including Server-Side Rendering (SSR), Static Site Generation (SSG), and Incremental Static Regeneration (ISR).

The system functions primarily as an Elysia plugin, allowing developers to mount multiple Furin instances within a single parent Elysia application. It integrates full TypeScript type inference and manages data loading through a specialized internal API.
Sources: AGENTS.md:16-19, packages/core/tests/runtime/multi-instance/multi-instance.integration.test.ts:10-14

Core Architecture and Multi-Instance Support

Furin operates as a composable Elysia plugin. You can mount several instances of the framework on the same server by providing different pagesDir and prefix configurations. Each instance maintains its own route snapshot, state isolation, and revalidation headers.

The diagram above illustrates how the parent Elysia application routes requests to isolated Furin instances based on URL prefixes.
Sources: packages/core/tests/runtime/multi-instance/multi-instance.integration.test.ts:178-185, AGENTS.md:65-67

Key Backend Components

Sources: packages/core/src/adapter/static.ts:257-260, packages/core/tests/dev/hmr/dev-route-topology.integration.test.ts:18-23, packages/core/README.md:37-41

Routing and Topology Management

Furin uses file-based routing where the directory structure defines the URL patterns. In development mode, a topology watcher monitors the filesystem to support Hot Module Replacement (HMR) without requiring a full server restart.

Route Discovery and Normalization

The backend scans the pages directory to build a route map. It supports dynamic segments using [param] syntax and enforces deterministic route ordering. If two files resolve to the same pattern, the system throws a duplicate route error.
Sources: packages/core/tests/dev/hmr/dev-route-topology.integration.test.ts:18-23, packages/core/tests/routing/discovery/scan-order.test.ts:114-121

The Data Endpoint

The backend exposes a specialized endpoint at /_furin/data to serve loader data for Single Page Application (SPA) navigations.

This flow shows how the backend intercepts data requests to provide the necessary state for client-side transitions.
Sources: packages/core/src/client/router/spa-response.ts:108-115, packages/core/tests/dev/hmr/dev-route-topology.integration.test.ts:107-115

Rendering Modes and Document Ownership

The backend manages the execution of React components on the server. The root layout is the owner of the rendered HTML document, including the <html>, <head>, and <body> tags.

Document Controls

Backend logic requires that the root layout includes specific components to function correctly:

• <HeadContent />: Injects metadata, titles, and styles.
• <Scripts />: Injects framework bootstrap scripts and serialized data.

If these components are missing in a root document, the backend reports a rendering error during development.
Sources: packages/core/tests/rendering/document/document-root.test.tsx:162-184, packages/core/src/client/document.tsx:143-149

Static Site Generation (SSG)

The Static Adapter executes a pre-rendering pipeline to generate physical HTML files and data files (__furin_data.ndjson) for static deployment.

The static build process ensures all dynamic routes defined with staticParams() are converted into deterministic files.
Sources: packages/core/src/adapter/static.ts:311-340, packages/core/src/adapter/static.ts:400-415

State Synchronization and Mutations

For features requiring persistent state or replayable mutations, Furin provides a synchronization system. The furinSync utility integrates with Elysia to make mutations idempotent.

• Idempotency Keys: Required for mutations handled by furinSync to ensure replayability.
• Database Adapters: Supports SQLite (development), PostgreSQL, and Redis (production).
• Revalidation: The backend uses the x-furin-revalidate header to notify the client when specific paths need to refresh their data.

Sources: packages/core/README.md:37-41, packages/core/tests/runtime/multi-instance/multi-instance.integration.test.ts:215-223

Summary of Backend Operations

The Furin backend acts as the bridge between the React frontend and the Bun/Elysia runtime. It automates route discovery, manages the document lifecycle through React SSR, and provides robust mechanisms for data synchronization and static exports. By leveraging Bun's native capabilities, it maintains high performance for both development HMR and production serving.
Sources: AGENTS.md:16-19, packages/core/package.json:2-10