AIditorEcosystemDocumentationDesign Log
GitHubGet Started

Jay Stack Conceptual Model

Jay Stack Conceptual Model

Written for AI agents. See Log Methodology Note below for details.

Overview

This design log provides a conceptual diagram showing the relationships between the key building blocks of Jay Stack:

  • Services - Server-side singletons (database, API clients)
  • Contexts - Client-side hierarchical dependency injection
  • Pages - Page definitions that generate website pages
  • Plugins - NPM packages providing reusable contracts, components, actions
  • Headless Components - Plugin-provided components with data contracts
  • Init - Server and client initialization via makeJayInit

Conceptual Relationships Diagram

Plugin (NPM Package) Project Server Runtime Client Runtime _serverInit() returns data _serverInit() returns data injected via withServices() injected via withServices() injected via withServices() <script jay-headless> defines view state registered HTTP HTML + embedded data injected via withContexts() called from plugin.yaml lib/init.tsmakeJayInit Contracts.jay-contract HeadlessComponents ServerActions src/init.tsmakeJayInit Pagespage.ts + page.jay-html ServicescreateJayService ContextscreateJayContext Service RegistryregisterService / getService Action RouterPOST /_action/:id Server-Side RenderingslowRender → fastRender Context RegistryregisterGlobalContext / useContext Action Callerfetch POST /_action/:id Client Hydrationinteractive phase

Component Lifecycle Diagram

rect [rgb(240, 248, 255)] rect [rgb(255, 248, 240)] rect [rgb(240, 255, 240)] Import & call _serverInit() Register services, return client data Import & call _serverInit() Register services, return client data slowRender(services) Load component data slowViewState fastRender(services, params) Load dynamic data fastViewState HTML + embedded scripts Parse client init data Call _clientInit(data) Register contexts Call _clientInit(data) Register contexts Mount component tree Hydrate interactive handlers Request Handling Server Rendering (per request) Client Phase Dev Server Plugin Init(lib/init.ts) Project Init(src/init.ts) Page(page.ts) HeadlessComponent Browser

Entity Relationships

PLUGIN (no attributes) CONTRACT object slowViewState object fastViewState object props object refs HEADLESS_COMPONENT (no attributes) ACTION (no attributes) INIT (no attributes) PROJECT (no attributes) PAGE (no attributes) SERVICE string name function factory singleton string scope CONTEXT string name any value hierarchical string scope defines provides exposes has contains defines defines has uses implements

Key Concepts Summary

Concept Runtime Scope Lifecycle Purpose
Service Server Global singleton Application lifetime Database, API clients, config
Context Client Hierarchical (parent→child) Page lifetime Theme, auth state, feature flags
Page Both Per-route Per request Define website routes and content
Plugin Both Global Application lifetime Package reusable functionality
Headless Component Both Per-usage Component lifetime Provide data+behavior without template
Init Both Global Application startup Register services/contexts
Action Server (callable from client) Per-call Stateless Server-side mutations/queries

Data Flow Overview

Build Time Server Startup (once) Per Request Client (browser) Server Action Handling withServices embedded JSON parse withServices response generate registerService return data registerService return data slowViewState fastViewState withContexts user interaction HTTP POST Contracts TypeScript Types Plugin Inits Services Client Init Data Project Init Slow Render Fast Render HTML Response Contexts Components Action Calls Action Handler Action Logic

File Structure Reference

project/
├── src/
│   ├── init.ts                    # Project init (makeJayInit)
│   ├── pages/
│   │   └── products/
│   │       ├── page.ts            # Page logic
│   │       ├── page.jay-html      # Page template
│   │       └── page.jay-contract  # Generated contract
│   ├── services/
│   │   └── database.service.ts    # Service definitions
│   ├── contexts/
│   │   └── theme.context.ts       # Context definitions
│   └── actions/
│       └── cart.actions.ts        # Server actions
├── node_modules/
│   └── @wix/stores/               # Example plugin
│       ├── plugin.yaml
│       ├── lib/
│       │   ├── init.ts            # Plugin init
│       │   ├── contracts/
│       │   └── components/
│       └── dist/
└── package.json

Related Design Logs

Log Methodology Note

Note: These design logs are written primarily for AI agents as part of the Design Log methodology and made accessible here for human readers. The language and structure are optimized for machine consumption — expect precise, specification-style prose rather than narrative documentation.