{"id":29182638,"url":"https://github.com/akshat-owo/z1-chat","last_synced_at":"2025-07-01T20:07:04.046Z","repository":{"id":300485461,"uuid":"999055196","full_name":"akshat-OwO/z1-chat","owner":"akshat-OwO","description":"A next-generation chat application that demonstrates how to build scalable, real-time applications with resumable AI streaming","archived":false,"fork":false,"pushed_at":"2025-06-18T17:19:23.000Z","size":7043,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-29T23:50:04.197Z","etag":null,"topics":["ai","postgres","redis","tanstack-start","zero"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akshat-OwO.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-09T17:06:21.000Z","updated_at":"2025-06-28T10:46:33.000Z","dependencies_parsed_at":"2025-06-22T00:41:32.065Z","dependency_job_id":"c7463ffa-3e78-4530-b0a0-59f636e6f654","html_url":"https://github.com/akshat-OwO/z1-chat","commit_stats":null,"previous_names":["akshat-owo/z1-chat"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/akshat-OwO/z1-chat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshat-OwO%2Fz1-chat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshat-OwO%2Fz1-chat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshat-OwO%2Fz1-chat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshat-OwO%2Fz1-chat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akshat-OwO","download_url":"https://codeload.github.com/akshat-OwO/z1-chat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshat-OwO%2Fz1-chat/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263029212,"owners_count":23402354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","postgres","redis","tanstack-start","zero"],"created_at":"2025-07-01T20:07:02.322Z","updated_at":"2025-07-01T20:07:04.018Z","avatar_url":"https://github.com/akshat-OwO.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# z1-Chat 🚀\n\n\u003e **Built for [Cloneathon](https://cloneathon.t3.chat/)** - A real-time multi-user chat application with resumable LLM streaming\n\nA next-generation chat application that demonstrates how to build scalable, real-time applications with **resumable AI streaming**. Built with [Zero's sync engine](https://zero.rocicorp.dev/) for insane scalability and PostgreSQL for rock-solid persistence.\n\n## ✨ Key Features\n\n- 🔄 **Resumable AI Streaming** - Reload the page mid-response? No problem, the stream continues seamlessly\n- 🧠 **Multiple LLM Models** - Powered by OpenRouter with support for various AI models\n- 🔐 **Flexible Authentication** - Support for both authenticated and anonymous users\n- 📱 **Modern UI** - Clean, responsive interface built with React and Tailwind CSS\n- ⚡ **Lightning Fast** - Optimized for performance with minimal database operations\n\n## 🏗️ Architecture\n\nThis project showcases an innovative streaming architecture that solves the challenge of **resumable LLM responses at scale**:\n\n### The Problem\n\nStreaming every token through PostgreSQL/Zero isn't scalable. But users expect real-time updates and resumable streams.\n\n### The Solution\n\nA hybrid approach using **Redis for streaming state** and **PostgreSQL for persistence**:\n\n1. **Start Stream**: Insert message with `isStreaming: true` and empty content into PostgreSQL\n2. **Real-time Sync**: Zero immediately syncs this \"streaming\" message to all connected clients\n3. **Token Streaming**: Client opens SSE connection for that specific message (not the entire chat)\n4. **Redis Buffering**: Stream tokens are stored in Redis and sent via Server-Sent Events\n5. **Resumable Magic**: New/reconnecting clients get caught up instantly from Redis buffer\n6. **Completion**: Final message content saved to PostgreSQL, `isStreaming: false`, Redis cleanup\n\n### Key Benefits\n\n- **Only 2 PostgreSQL operations per message** (insert → update)\n- **Multiple concurrent streams** per chat thread\n- **Resumable streams** - refresh mid-response and it continues\n\n## 🛠️ Tech Stack\n\n### Frontend\n\n- **React 19** - Latest React with concurrent features\n- **TanStack Router/Start** - Type-safe routing and SSR\n- **Tailwind CSS** - Utility-first styling\n- **Radix UI** - Accessible component primitives\n- **Zero Client** - Reactive data synchronization\n\n### Backend\n\n- **TanStack Start** - Full-stack React framework\n- **PostgreSQL** - Primary database with logical replication\n- **Redis** - Streaming state management\n- **Prisma** - Type-safe database ORM\n- **Better Auth** - Modern authentication\n\n### AI \u0026 Streaming\n\n- **OpenRouter** - Multi-model LLM access\n- **AI SDK** - Streaming text generation\n- **Server-Sent Events** - Real-time token streaming\n- **Zero Sync** - Reactive state management\n\n### Infrastructure\n\n- **Docker Compose** - Local development environment\n- **TypeScript** - End-to-end type safety\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- Node.js 18+\n- Docker \u0026 Docker Compose\n- pnpm (recommended)\n\n### Quick Start\n\n1. **Clone the repository**\n\n    ```bash\n    git clone https://github.com/akshat-OwO/z1-chat\n    cd z1-chat\n    ```\n\n2. **Install dependencies**\n\n    ```bash\n    pnpm install\n    ```\n\n3. **Start the infrastructure**\n\n    ```bash\n    docker-compose up -d\n    ```\n\n4. **Set up environment variables**\n\n    ```bash\n    cp .env.example .env\n    # Edit .env with your GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and OPENROUTER_API_KEY\n    ```\n\n5. **Run database migrations**\n\n    ```bash\n    pnpm prisma:migrate\n    ```\n\n6. **Run zero-cache server**\n\n    ```bash\n    npx zero-cache-dev\n    ```\n\n7. **Start the development server**\n    ```bash\n    pnpm dev\n    ```\n\nVisit `http://localhost:3000` and start chatting!\n\n## 🔧 Configuration\n\n### Environment Variables\n\n```bash\ncp .env.example .env\n```\n\n### Available Models\n\nThe application supports multiple LLM models via OpenRouter:\n\n- **Google Gemini 2.0 Flash** (default for chat titles)\n- **OpenAI GPT models**\n- **Anthropic Claude**\n- **And many more...**\n\n## 📊 Database Schema\n\nThe application uses a clean, optimized schema:\n\n- **Users** - Authentication and user management\n- **Chats** - Chat threads with metadata\n- **Messages** - Individual messages with streaming state\n- **Sessions/Accounts** - Authentication data\n\nKey optimizations:\n\n- Minimal fields for fast queries\n- Proper indexing for real-time performance\n- Zero sync generation for reactive updates\n\n## 🎯 Why This Architecture?\n\n### Traditional Approach Problems:\n\n- ❌ Lost streams on page refresh\n- ❌ Complex state management for multiple concurrent streams\n- ❌ Poor user experience during network issues\n\n### Solution Benefits:\n\n- ✅ **2 DB operations per message** regardless of response length\n- ✅ **Resumable streams** - refresh anytime, stream continues\n- ✅ **Multiple concurrent streams** per chat\n- ✅ **Instant catch-up** for new connections\n- ✅ **Scales horizontally** with Redis clustering\n\n## 📸 Demo\n\nhttps://github.com/user-attachments/assets/573da14e-affe-49de-85ba-cf661f617c23\n\n\n## 🚀 What I Want to Add\n\nThis project has several exciting features planned for future development:\n\n### 🌐 Deployment \u0026 Hosting\n- **Production Deployment** - Currently local-only, planning to deploy to cloud platforms\n\n### 👥 Multiplayer Chat Features\n- **Shareable Chats** - Generate shareable links for chat conversations\n- **Collaborative Editing** - Multiple users can participate in the same chat thread\n\n### 🎨 Enhanced Code Experience\n- **Advanced Syntax Highlighting** - Better code block rendering with language detection\n- **Code Execution** - Interactive code blocks with execution capabilities\n\n### 🌳 Chat Branching \u0026 Navigation\n- **Conversation Branching** - Fork conversations at any point to explore different paths\n- **Visual Chat Tree** - Tree-like visualization of conversation branches\n- **Quick Navigation** - Jump between different branches and conversation points\n- **Branch History** - Track and manage conversation branch history\n\n\n## 🤝 Contributing\n\nThis project was built for the [Cloneathon](https://cloneathon.t3.chat/) - feel free to explore, learn, and build upon it!\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **[Zero](https://zero.rocicorp.dev/)** - For the incredible sync engine that makes real-time updates effortless\n- **[Cloneathon](https://cloneathon.t3.chat/)** - For the inspiration and platform to build this\n- **[Mark MacLeod](https://x.com/marbemac/status/1929922350549479564)** - For sharing the original tweet that inspired this architecture\n\nBuilt with ❤️ for the developer community. Happy chatting! 💬\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakshat-owo%2Fz1-chat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakshat-owo%2Fz1-chat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakshat-owo%2Fz1-chat/lists"}