System Architecture
Hazel Chat is a modern, real-time collaborative chat platform built with cutting-edge technologies that prioritize type safety, functional programming, and local-first architecture.Architecture Diagram
Core Components
Frontend (Web & Desktop)
The client applications provide the user interface for Hazel Chat:- Local-first data layer using TanStack DB for offline support
- Real-time sync via Electric SQL for instant updates
- Type-safe RPC calls to the backend API
- Reactive state management with Effect Atom
- Built with React 19, Vite, and TailwindCSS v4
Key Frontend Technologies
- React 19 with TypeScript for UI components
- TanStack Router for file-based routing
- TanStack DB for local SQLite database
- Electric SQL for real-time sync
- Effect Atom for reactive state
- Plate.js for rich text editing
Backend API
The backend API handles business logic, authentication, and data persistence:- Built with Effect-TS for functional programming patterns
- Type-safe RPC system using Effect RPC
- Dependency injection via Effect layers
- Policy-based authorization with row-level security
- Runs on Bun runtime for performance
The backend uses Effect-TS extensively for error handling, dependency management, and resource lifecycle management.
Cluster Service
The cluster service provides distributed workflow execution:- Effect Cluster for distributed systems coordination
- Effect Workflow for durable background jobs
- PostgreSQL-backed persistence for message storage
- HTTP API for workflow management
Message Notifications
Creates notifications for new messages based on channel type and user mentions
GitHub Integration
Processes GitHub webhooks and installation events
File Cleanup
Removes unused file uploads on schedule
RSS Polling
Fetches RSS feeds and posts updates to channels
Electric SQL Proxy
The Electric proxy enforces authorization for real-time sync:- Row-level security based on user permissions
- WHERE clause injection for organization and channel access
- Table allowlisting to prevent unauthorized sync
- Routes sync requests to Electric SQL service
Data Flow
Write Operations (Client → Server)
- User action triggers RPC call from client
- Backend API validates request and checks permissions
- Database write occurs in PostgreSQL transaction
- Transaction ID returned to client for optimistic updates
- Electric SQL detects change and broadcasts to subscribers
- Cluster workflow triggered for background processing (if needed)
Read Operations (Server → Client)
- Electric SQL streams data changes via HTTP long-polling
- Electric Proxy injects WHERE clauses based on user auth
- TanStack DB receives updates and stores in local SQLite
- React components re-render with new data via Effect Atom
Optimistic updates allow the UI to respond instantly while the server processes the request in the background.
Technology Stack
Frontend Stack
| Technology | Purpose |
|---|---|
| React 19 | UI framework with concurrent rendering |
| TypeScript | Type safety and developer experience |
| Vite | Fast development server and builds |
| TanStack Router | File-based routing with type safety |
| TanStack DB | Local-first SQLite database |
| Electric SQL | Real-time sync with PostgreSQL |
| Effect Atom | Reactive state management |
| TailwindCSS v4 | Utility-first styling |
| React Aria | Accessible UI components |
| Plate.js | Rich text editor framework |
Backend Stack
| Technology | Purpose |
|---|---|
| Bun | JavaScript runtime (faster than Node.js) |
| Effect-TS | Functional programming framework |
| Effect RPC | Type-safe client-server communication |
| Effect Cluster | Distributed systems coordination |
| Effect Workflow | Durable workflow execution |
| Drizzle ORM | Type-safe database queries |
| PostgreSQL | Primary relational database |
| Redis | Session storage and caching |
| WorkOS | Authentication and SSO |
Development Tools
| Tool | Purpose |
|---|---|
| Turborepo | Monorepo build orchestration |
| OXC | Fast linting and formatting |
| Vitest | Unit and integration testing |
| Drizzle Kit | Database migration management |
Key Architectural Decisions
Local-First Architecture
Hazel Chat uses a local-first approach where data is stored locally in TanStack DB and synced with the server via Electric SQL. This provides:- Instant UI updates with optimistic rendering
- Offline support with automatic sync when reconnected
- Reduced server load by handling reads locally
- Better user experience with no loading spinners
Effect-TS for Backend
Effect-TS provides functional programming patterns that make the backend code:- Type-safe with compile-time guarantees
- Composable with small, reusable functions
- Testable via dependency injection
- Resilient with built-in error handling and retry logic
Distributed Workflows
Effect Cluster and Effect Workflow handle background jobs with:- Durability - workflows survive restarts
- Idempotency - safe to retry operations
- Observability - structured logging and tracing
- Scalability - distributed across multiple nodes
Port Assignments
| Service | Port | Description |
|---|---|---|
| Web App | 3000 | React frontend development server |
| Backend API | 3003 | Effect-TS API server |
| Cluster Service | 3020 | Distributed workflow service |
| PostgreSQL | 5432 | Primary database |
| Redis | 6379 | Session cache |
| Electric SQL | 3002 | Real-time sync service |
| MinIO (S3) | 9000 | Local object storage |
All services communicate over HTTP/HTTPS. The backend uses RPC over HTTP for client-server communication.
Next Steps
Monorepo Structure
Learn about the monorepo organization and package dependencies
Effect-TS Patterns
Explore Effect-TS usage and functional programming patterns
Electric SQL
Understand the local-first sync architecture
RPC System
Dive into the type-safe RPC system