System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Furin is a React meta-framework optimized for the Bun runtime and Elysia web server. It provides a file-based routing system supporting Server-Side Rendering (SSR), Static Site Generation (SSG), and Incremental Static Regeneration (ISR). The framework enforces full TypeScript type inference and leverages Bun's native capabilities for Hot Module Replacement (HMR) and fast builds.
Sources: README.md:1-6, AGENTS.md:16-19
Core Components
The architecture consists of a core library, a command-line interface (CLI) for scaffolding, and specialized adapters for different deployment targets.
| Component | Responsibility |
|---|---|
| Packages/Core | Implements the framework runtime, routing logic, and React rendering integration. |
| Apps/Scaffolder | Provides the create-furin CLI for initializing new projects with predefined templates. |
| Elysia Plugin | Integrates Furin as a middleware/plugin within Elysia applications to handle frontend requests. |
| Static Adapter | Orchestrates the pre-rendering process for SSG deployments. |
Sources: README.md:16-21, AGENTS.md:68-70, packages/core/src/adapter/static.ts:365-372
Request and Rendering Flow
Furin uses a hierarchical routing structure where a root layout wraps every page. During a request, the framework resolves the route chain, executes loaders to fetch data, and assembles the React component tree.
The diagram shows the sequence from an incoming HTTP request to the final HTML response generated by the server.
Document and Metadata Management
The DocumentProvider manages global state including assets, head metadata, and serialized data for hydration. The HeadContent component injects standard meta tags, stylesheets, and custom head elements defined in route configurations.
Sources: packages/core/src/client/document.tsx:32-40, packages/core/src/client/document.tsx:64-70
Scaffolding Pipeline
The scaffolding system uses a multi-stage pipeline to generate project files from EJS templates and static assets.
The sequence diagram illustrates how the CLI processes a template manifest to produce a project structure on the local disk.
Sources: apps/scaffolder/src/pipeline/stages/5-generation.ts:88-121, apps/scaffolder/src/pipeline/stages/3-design.ts:7-27
Static Export Architecture
The static adapter enables pre-rendering of SSG-eligible routes. It validates that routes do not use server-only features like requestLoader before proceeding with the export.
- Validation: The system ensures all routes are in
ssgmode or skips them based on theonSSRconfiguration. - Task Queueing: A concurrent queue of pre-render tasks is built using
staticParams()to resolve dynamic segments. - Rendering: The
prerenderSSGfunction generates HTML and.ndjsondata payloads for each resolved path. - Artifact Collection: Assets from
public/and the client build are copied to the destinationdist/folder.
Sources: packages/core/src/adapter/static.ts:365-385, packages/core/src/adapter/static.ts:251-270, packages/core/src/adapter/static.ts:30-32
Development and Tooling
Furin is built exclusively for the Bun runtime. It utilizes bun --hot for HMR, eliminating the need for Vite or other external bundlers in development.
- Runtime: Bun >= 1.4.0.
- Styling: Tailwind CSS v4 via
bun-plugin-tailwind. - Linting: Biome (via Ultracite).
- Communication: WinterCG compliance for cross-runtime compatibility.
Sources: AGENTS.md:55-58, AGENTS.md:68-70, README.md:1-12
Summary
The Furin system architecture prioritizes Bun-native performance and strict TypeScript safety. By integrating deeply with Elysia, it provides a unified environment where backend and frontend logic share a single process and type system. The modular design, spanning from the core runtime to specialized static adapters, allows the framework to serve both dynamic SSR applications and optimized static sites.
Sources: AGENTS.md:16-19, packages/core/tests/README.md:10-21