DevelopersArchitectureOverview

System architecture

A deep dive into how PWFabric is structured. Understanding the architecture helps you build better surfaces and integrations.

Layered architecture

┌─────────────────────────────────────────────────────────────────┐
│                        APPLICATIONS                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐         │
│  │  PhiCo   │  │   PhiSo  │  │ Account  │  │Marketing │         │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘         │
├─────────────────────────────────────────────────────────────────┤
│                          API LAYER                               │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  Hono Router  │  Auth  │  Validation  │  Rate Limiting   │   │
│  └──────────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────────┤
│                         RUNTIME                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │  Renderer   │  │State Engine │  │  Event System           │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                          CORE                                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │Block System │  │ Composition │  │  Validation             │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                        CONTRACTS                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │    Types    │  │   Schemas   │  │  Interfaces             │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Each layer has a specific responsibility and can only depend on layers below it. This creates a clean separation of concerns and makes the system easier to maintain.

Layer breakdown

Contracts — @pwfabric/contracts

The foundation of the system. Defines all types, interfaces, and schemas that other layers use.

Responsibilities:

  • TypeScript type definitions
  • Zod validation schemas
  • API contracts
  • Block type definitions

Dependencies: None (foundation layer)

Core — @pwfabric/core

Implements the block system and composition engine. The heart of surface creation.

Responsibilities:

  • Block registration and validation
  • Surface composition
  • Block lifecycle management
  • Plugin system

Dependencies: @pwfabric/contracts

Runtime — @pwfabric/runtime

Executes surfaces in different environments. Handles rendering, state, and events.

Responsibilities:

  • Server-side rendering
  • Client-side hydration
  • State management
  • Event handling

Dependencies: @pwfabric/contracts, @pwfabric/core

API — @pwfabric/api

HTTP layer for external access. Built on Hono for edge-first performance.

Responsibilities:

  • REST endpoints
  • Authentication
  • Rate limiting
  • Request validation

Dependencies: @pwfabric/contracts, @pwfabric/core, @pwfabric/runtime

Data flow

Request → API → Validation → Core → Runtime → Response

1. Request arrives at API layer
2. Auth middleware validates credentials
3. Request validation against Contracts
4. Core processes business logic
5. Runtime renders surface
6. Response sent to client

Every request follows this flow, ensuring consistent validation, logging, and error handling across all endpoints.

Key architectural concepts

  • Immutable contracts — Published contracts are immutable. Breaking changes require new major versions. This ensures stability for integrations.
  • Edge-first — Designed to run at the edge. The runtime is lightweight and can execute in Cloudflare Workers, Vercel Edge, or similar environments.
  • Type safety — End-to-end type safety from database to UI. TypeScript throughout with strict configuration.
  • Composability — Everything is composable. Blocks compose into surfaces, surfaces compose into applications.

Deployment architecture

                    ┌─────────────┐
                    │   CDN/Edge  │
                    └──────┬──────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
      ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
      │  Web App  │  │  API      │  │  Assets   │
      │  (Next.js)│  │  (Hono)   │  │  (R2/S3)  │
      └─────┬─────┘  └─────┬─────┘  └───────────┘
            │              │
            └──────┬───────┘
                   │
            ┌──────▼──────┐
            │  Database   │
            │(PostgreSQL) │
            └─────────────┘

Production deployments use edge computing for low latency, with regional database replicas for data-heavy operations.

Dive deeper

RuntimeSurface OS layers