# wakujs/waku architecture

> Architecture diagram of the GitHub repository wakujs/waku, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wakujs/waku
- Repository: https://github.com/wakujs/waku

## Overview

Based on our deep dive into the file tree and the comprehensive README, this project is a monorepo for Waku—a minimal React framework. Its purpose is to provide a lightweight, full-stack React framework that leverages server components to give developers a “fun” and efficient way to build websites and web applications. In short, it focuses on a modern approach to rendering, routing, and data fetching by enabling smooth transitions between server and client components.

##### Main High-Level Components
- Core Framework (packages/waku): This contains the engine for handling the rendering, routing, and build-time optimizations. It includes modules such as the router (file-based routing and create-pages utilities), middleware (for handling context, fallback, and dev-server logic), plugins (for integrations with Vite, AWS Lambda, Cloudflare, etc.), and renderers that manage both traditional SSR and newer server component flows.
- CLI & Scaffolding (packages/create-waku): Provides command-line interface utilities to scaffold new Waku projects.
- Website & Documentation (packages/website and docs folder): These support community content, developer documentation, examples, and demos.
- Examples & Tests (examples directory & e2e folder): A wide array of example projects (both TypeScript and JavaScript templates) and end-to-end tests that show how to use various aspects of the framework (routing, full SSR or SSG rendering, RSC, server actions, etc.).
- Configuration, Build, and Utility Files: Including tsconfig, PostCSS config, ESLint config, and many CI/CD workflow files (in .github and .codesandbox folders) that ensure integration with deployment and testing environments.

##### Out the Relationships and Interactions
- How the Core Framework interacts with its various submodules:
- The Routing Engine relies upon the file-based “pages router” (with conventions for single routes, segment, nested, and catch-all routes) and supports dynamic and static rendering through configuration functions (getConfig).
- The Rendering Engine differentiates between server components (that can be asynchronous and handle server-only logic) and client components (marked with ‘use client’) – clearly highlighting the server-client boundary.
- Server Actions: Demonstrate how inline and separate server action functions (with the “use server” directive) are integrated into the overall rendering flow and can be passed down as props to client components.
- Role of Plugins and Builders: These modules modify and extend the Vite configuration, enable deployments to various platforms (AWS Lambda, Cloudflare, Netlify, etc.), and help in code transformation and optimization.
- Integrations with external libraries: Such as Jotai for state management and any other supporting libraries mentioned in the README.

##### Architectural Patterns and Principles
- Separation of Concerns: The architecture splits responsibilities between routing, rendering, and build/deployment aspects.
- Server-Client Boundary: Clearly illustrate how the ‘use client’ directive marks a boundary within the component tree, causing a shift from server to client rendered components.
- Modular & Pluggable Design: Break down the system into reusable modules (plugins, middleware, renderers) that the framework leverages to support various deployment targets.
- File-Based Routing Convention: Emphasize the convention over configuration aspect where directory structure (e.g., src/pages with special files like _layout.tsx, _root.tsx) drives the routing behavior.

##### Essential Elements
- “Core Framework (waku)” – with internal submodules: Router, Middleware, Plugins, Renderers, Server utilities.
- “CLI/Scaffolding (create-waku)” – for project generation.
- “Examples & Tests” – showcasing usage examples and integration tests.
- “Website & Docs” – supporting developer resources.
- Flow paths from server actions, data fetching modules, and build scripts to the final output deployments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-Level Monorepo Structure
    subgraph "Core Framework (Waku)"
        Router["Router (file-based)"]:::core
        Middleware["Middleware"]:::core
        Renderers["Renderers"]:::core
        Plugins["Plugins"]:::core
    end

    CLI["CLI & Scaffolding (create-waku)"]:::cli
    subgraph "Documentation & Community"
        Website["Website"]:::doc
        Docs["Documentation"]:::doc
    end
    subgraph "Examples & Tests"
        Examples["Example Projects"]:::usage
        E2E["E2E Tests"]:::usage
    end
    Utility["CI/CD & Configuration"]:::config
    ServerClientBoundary["Server-to-Client Boundary"]:::boundary
    Deployment["Deployment Targets (Vercel,Netlify,Cloudflare,AWSLambda,PartyKit,Deno)"]:::deploy

    %% Relationships and Data Flow
    Router -->|"routes"| Renderers
    Middleware -->|"applies_logic"| Renderers
    Plugins -->|"enhances"| Renderers

    Renderers -->|"transitions"| ServerClientBoundary

    CLI -->|"scaffolds"| Router
    CLI -->|"generates"| Utility
    Examples -->|"demonstrate"| Router
    E2E -->|"validates"| Middleware

    Docs -->|"documents"| CoreFramework[Core Framework Usage]
    Website -->|"showcases"| CoreFramework

    Utility -->|"triggers_build"| Deployment

    %% Styles
    classDef core fill:#FFF3CD,stroke:#856404,stroke-width:2px;
    classDef cli fill:#CDEBF9,stroke:#2C82C9,stroke-width:2px;
    classDef doc fill:#D5E8D4,stroke:#82B366,stroke-width:2px;
    classDef usage fill:#EAD1DC,stroke:#B854A4,stroke-width:2px;
    classDef config fill:#FFF2CC,stroke:#D6B656,stroke-width:2px;
    classDef boundary fill:#FCE5CD,stroke:#D79B00,stroke-width:2px;
    classDef deploy fill:#E4DFEC,stroke:#8E7CC3,stroke-width:2px;

    %% Click Events
    click Router "https://github.com/wakujs/waku/tree/main/packages/waku/src/router"
    click Middleware "https://github.com/wakujs/waku/tree/main/packages/waku/src/middleware"
    click Renderers "https://github.com/wakujs/waku/tree/main/packages/waku/src/lib/renderers"
    click Plugins "https://github.com/wakujs/waku/tree/main/packages/waku/src/lib/plugins"
    click CLI "https://github.com/wakujs/waku/tree/main/packages/create-waku"
    click Website "https://github.com/wakujs/waku/tree/main/packages/website"
    click Docs "https://github.com/wakujs/waku/tree/main/docs"
    click Examples "https://github.com/wakujs/waku/tree/main/examples"
    click E2E "https://github.com/wakujs/waku/tree/main/e2e"
    click Utility "https://github.com/wakujs/waku/blob/main/.github"
```
