Executive

An agentic product for building consolidating actionable information in a semantically zoomable interface.

Features

Real-time Synchronization: Changes sync instantly across all connected clients
Persistent State: Optional server-side storage in Cloudflare Durable Objects
Local-first Architecture: Works offline with browser localStorage
TypeScript Support: Full type safety throughout the application
Infrastructure as Code: Managed with Alchemy framework

Prerequisites

mise - for tool version management
A Cloudflare account (for deployment)
Git

Installation

Clone the repository:

git clone <repository-url>
cd executive

Install mise (if not already installed):

curl https://mise.run | sh

Install project dependencies:

mise install

This will automatically:

Install the correct version of Bun (1.2.8)
Run bun install to install all npm dependencies
Set up the development environment

Development

Running the Full Stack Locally

Start both the client and server in development mode:

mise run dev

This runs both:

Client dev server at http://localhost:5173
Cloudflare Workers server locally

Running Components Individually

Client only:

mise run dev:client

Server only:

mise run dev:server

Building for Production

Build the client:

mise run build:client

Preview the production build:

mise run preview:client

Deployment

Deploy to Cloudflare

Deploy the entire infrastructure (client + server):

mise run deploy

This uses Alchemy to:

Deploy the TinyBase Durable Object synchronization server
Deploy the Vite-built client as a Cloudflare Pages site
Configure all necessary bindings and routes

Destroy Infrastructure

Remove all deployed resources:

mise run destroy

Project Structure

.
├── client/               # React frontend application
│   ├── src/
│   │   ├── App.tsx      # Main application component
│   │   └── store.ts     # TinyBase store configuration
│   └── package.json
├── server/              # Cloudflare Worker backend
│   ├── index.ts         # WebSocket synchronization server
│   └── package.json
├── alchemy.run.ts       # Infrastructure definition
├── mise.toml           # Development environment configuration
└── CLAUDE.md           # AI assistant instructions

Configuration

Server URL

The WebSocket server URL is configured in client/src/App.tsx. By default, it connects to vite.tinybase.cloud.

To use your own server:

Update the SERVER constant in client/src/App.tsx
Deploy your own server instance using mise run deploy

Persistence Mode

Configure server-side persistence in server/index.ts by setting:

const PERSIST_TO_DURABLE_OBJECT = true; // or false

Environment Variables

Create a .env file in the root directory:

ALCHEMY_PASSWORD=your-secure-password
CLOUDFLARE_ACCOUNT_ID=your-account-id

Available Commands

# Development
mise run dev              # Run full stack locally
mise run dev:client       # Run client only
mise run dev:server       # Run server only

# Building
mise run build           # Build client for production
mise run build:client    # Build client
mise run preview:client  # Preview production build

# Deployment
mise run deploy          # Deploy to Cloudflare
mise run destroy         # Destroy all resources

# Utilities
mise run fmt             # Format code with Biome
mise run logs            # Stream logs from deployed workers
mise run logs:server     # Stream server logs only
mise run logs:client     # Stream client logs only

Monitoring

Stream logs from deployed workers:

# All logs
mise run logs

# Server logs only
mise run logs:server

# Client logs only
mise run logs:client

Architecture

Frontend: React SPA with TinyBase for state management
State Sync: WebSocket connections to Cloudflare Durable Objects
Persistence: Browser localStorage + optional Durable Object storage
Infrastructure: Managed with Alchemy TypeScript framework
Conflict Resolution: Automatic via TinyBase MergeableStore

Contributing

Fork the repository
Create a feature branch
Make your changes
Run mise run fmt to format code
Submit a pull request

License

This project is provided without license - use it however you want!

TinyBase and Vite are both MIT licensed.

zephraph/tinybase-cf