Core Concepts
Archibald is built on a set of foundational architectural patterns that ensure scalability, maintainability, and a clear separation of concerns. Understanding these concepts is key to effectively developing and extending the framework.
The diagrams below trace a request end to end, showing where the three server-side patterns—Module System, Providers & Adapters and Data Mappers—sit in the lifecycle. The build-time concerns (File Shadowing, Isomorphic Execution, Tenants/Platforms/Environments) are covered on their own pages, linked further down.
Architectural Overview & Request Flow
To help you visualize how these concepts connect, here is a high-level diagram illustrating a typical request-response cycle and data flow in Archibald, spanning both the client browser and the server runtime:
High-Level Architecture Diagram
The names below are the ones you will actually find in the shop template's Server class.
Flow Sequence Diagram
Foundational Patterns
Module System
Discover the self-contained, pluggable architecture of Archibald. Modules encapsulate features like Auth, CMS, and Commerce, allowing for easy registration, middleware configuration, and dependency management.
Providers & Adapters
Understand how Archibald bridges the gap between its generic interfaces and specific third-party integrations. This pattern keeps the application core agnostic by using Providers for server-side fetching and Adapters for client-side interactions.
Data Mappers
Learn how Archibald transforms raw backend data into clean, typed UI models. This pattern ensures your frontend and UI components remain completely decoupled from the specifics of third-party API payloads.
File Shadowing
See how one codebase serves multiple platforms and tenants: any file can be overridden by a more specific one, resolved most-specific-first at build time, while imports always name the base path.
Isomorphic Execution
Understand the client/server/native boundary: how conditional package entry points decide which code runs where, and how SSR and hydration execute the same components twice.
Tenants, Platforms & Environments
Keep the three build axes apart: platform picks the source tree, tenant picks the overrides, environment picks the runtime configuration.