Skip to main content

Architecture

This section explains how Archibald works under the hood — how the CLI, the Rspack build system, the SSR server, and client-side hydration fit together. It is aimed at framework contributors and anyone debugging or extending framework behavior.

If you are looking for how to use these features in a project, start with Working With Archibald instead; each chapter below links back to the corresponding usage docs.

What's covered here​

1. CLI​

How archibald serve, build, and package work internally: tenant/platform awareness, the preparation sequence, and command orchestration. For day-to-day command usage, see the CLI usage docs.

2. Rspack Build System​

The Rust-based bundler and SWC transpilation pipeline: the base configuration (loaders, splitChunks, shadowing aliases), production optimizations, how archibald.json drives the build, and how to extend the Rspack config from a project (see also the config override guide).

3. Server​

The Node.js SSR backbone, told in three phases: bootstrap (entry point to Hapi.js listener), structure (Inversion of Control and project wiring), and runtime (the request journey and ServerContext enrichment). The Core Concepts chapter then dissects the individual building blocks: CoreServer, Factory, ConfigService, EnvironmentHelper, Context Decorators, Component Wiring (services, controllers, routes, plugins, modules), the Renderer (asset orchestration, inlining, SSR flow), and the DataClient.

4. Hydration & Client-Side​

How server-rendered markup becomes an interactive app: the islands architecture for partial hydration, the hydration mechanics bridging SSR markup and client interaction, and the decision logic that determines when and how a component hydrates.

High-Level Architectural Flow​

The following diagram illustrates the complete "Source to Browser" journey, showing how the CLI, Build System, Server, and Browser interact with external integrations and internal packages.

1. Folder Structure Map​

The monorepo leverages a strict separation of concerns, heavily utilizing an on-demand scaling module architecture.

/
├── packages/              # Core framework, universal logic, and shared libraries
│   ├── analytics/         # Universal tracking and analytics logic
│   ├── auth/              # Authentication wrappers and state management
│   ├── build/             # Build system utilities, TS/Babel/Rspack custom plugins
│   ├── cart/              # Cart & checkout state logic
│   ├── check/             # Project health checks and validation
│   ├── cli/               # @archibald/cli (Rspack compiler, workspace generators)
│   ├── cli-kit/           # Shared CLI building blocks (prompts, command plumbing)
│   ├── client/            # Client-side core logic, hydration, contexts
│   ├── cms/               # CMS abstractions, template management, component registries
│   ├── codemod/           # AST transformations and migrations
│   ├── config/            # Cross-environment configuration loader
│   ├── core/              # Shared core primitives, types, application lifecycle
│   ├── create/            # CLI wizard to scaffold new templates
│   ├── di/                # Dependency Injection container (@archibald/di)
│   ├── e2e/               # End-to-end testing utilities and constants
│   ├── helpers/           # Shared isomorphic utilities
│   ├── log/               # Universal logging library (winston server, console client)
│   ├── native/            # React Native / Expo specific abstractions
│   ├── personalization/   # AB Testing and feature flag abstractions
│   ├── product/           # Product and catalog data abstractions
│   ├── quotes/            # B2B quotes handling
│   ├── search/            # Universal search and refinement logic
│   ├── server/            # Node.js SSR framework (extends @hapi/hapi)
│   ├── storage/           # Server context and client state storage abstractions
│   ├── storefront/        # High-level UI framework, registries (CMSRegistry), hooks
│   └── testing/           # Universal testing wrappers
├── integrations/          # Implementations & adapters for external vendor systems
│   ├── capacitor/         # Capacitor native app shell integration
│   ├── cdc/               # SAP Customer Data Cloud integration
│   ├── commerce/          # SAP Commerce Cloud / Hybris integration
│   ├── contentful/        # Contentful headless CMS integration
│   ├── coveo/             # Coveo intelligent search integration
│   ├── cypress/           # Cypress e2e testing harness
│   ├── depolier/          # Depolier deployment tooling integration
│   ├── docker/            # Docker image build integration
│   ├── docusaurus/        # Docusaurus documentation tooling
│   ├── growthbook/        # Growthbook personalization integration
│   ├── hapi/              # Hapi.js server adapter
│   ├── hono/              # Hono server adapter
│   ├── maestro/           # Maestro mobile e2e testing integration
│   ├── playwright/        # Playwright e2e testing integration
│   ├── rspack/            # Rspack build tooling integration
│   ├── service-worker/    # Service worker (Workbox) integration
│   ├── storybook/         # Storybook isolated UI testing environment
│   ├── swagger/           # Swagger/OpenAPI documentation integration
│   ├── vercel/            # Vercel edge/serverless handler adapters
│   └── vite/              # Vite build tooling integration
├── support/               # Foundational monorepo tooling
│   ├── jest/              # Centralized Jest and SWC test configurations
│   ├── mock/              # Mocking utilities (TestBed, Browser API mocks)
│   ├── tsdown/            # Rollup/Babel driven package bundler config
│   └── tsup/              # Tsup (esbuild) centralized package bundler config
└── templates/             # Blueprint project implementations
    ├── basic/             # Minimal Archibald app boilerplate
    └── shop/              # Fully featured B2C/B2B storefront template