{"id":31203471,"url":"https://github.com/thavarshan/chalice","last_synced_at":"2026-04-08T18:02:18.235Z","repository":{"id":312048849,"uuid":"1046017089","full_name":"Thavarshan/chalice","owner":"Thavarshan","description":"💬 Modern real-time chat app built with React, Node.js, TypeScript, and Azure WebPubSub — a great resource for devs moving from Vue/Laravel to React/Node.","archived":false,"fork":false,"pushed_at":"2025-08-28T07:10:53.000Z","size":81,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-20T15:26:35.626Z","etag":null,"topics":["azure","chalice","chat","expressjs","nodejs","pubsub","reactjs","websocket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Thavarshan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-08-28T04:16:24.000Z","updated_at":"2025-08-28T07:10:57.000Z","dependencies_parsed_at":"2025-08-28T14:06:54.192Z","dependency_job_id":"3864e54b-dee6-488d-ac50-98af72cc4103","html_url":"https://github.com/Thavarshan/chalice","commit_stats":null,"previous_names":["thavarshan/chalice"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Thavarshan/chalice","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thavarshan%2Fchalice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thavarshan%2Fchalice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thavarshan%2Fchalice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thavarshan%2Fchalice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Thavarshan","download_url":"https://codeload.github.com/Thavarshan/chalice/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thavarshan%2Fchalice/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31567227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["azure","chalice","chat","expressjs","nodejs","pubsub","reactjs","websocket"],"created_at":"2025-09-20T15:07:09.445Z","updated_at":"2026-04-08T18:02:18.227Z","avatar_url":"https://github.com/Thavarshan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chalice - Real-Time Chat Application\n\n## Project Overview\n\nChalice is a modern, full-stack real-time chat application built with **React**, **Node.js**, **TypeScript**, and **Azure WebPubSub**. This project demonstrates professional-grade development practices and serves as an excellent learning resource for developers transitioning from **Vue.js/Laravel** to **React/Node.js** ecosystems.\n\n### Key Features\n\n- **Real-time messaging** with WebSocket connectivity\n- **Dual-mode architecture** (Azure WebPubSub + Mock WebSocket)\n- **Responsive design** with modern UI components\n- **Type-safe development** with comprehensive TypeScript\n- **Monorepo structure** with separate frontend/backend\n- **Production-ready patterns** with error handling and optimization\n- **Educational codebase** with detailed documentation and comments\n\n## Architecture Overview\n\n### High-Level Architecture\n```\n┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐\n│                     │    │                     │    │                     │\n│   React Frontend    │◄──►│   Express Backend   │◄──►│   Azure WebPubSub   │\n│                     │    │                     │    │   (or Mock Server)  │\n│   • TypeScript      │    │   • TypeScript      │    │                     │\n│   • Styled Comps    │    │   • WebSocket       │    │   • Managed Service │\n│   • Custom Hooks    │    │   • Dual Mode       │    │   • Auto Scaling    │\n│   • Vite Bundler    │    │   • REST API        │    │   • Group Messaging │\n│                     │    │                     │    │                     │\n└─────────────────────┘    └─────────────────────┘    └─────────────────────┘\n        Port 5173                   Port 3001                 Azure Cloud\n```\n\n### Technology Stack\n\n#### Frontend (`/web`)\n- **React 19** with TypeScript\n- **Vite** for fast development and building\n- **Styled Components** for CSS-in-JS styling\n- **Custom Hooks** for WebSocket management\n- **Azure WebPubSub Client** for real-time messaging\n\n#### Backend (`/server`) \n- **Node.js 18+** with Express.js\n- **TypeScript** for type safety\n- **Azure WebPubSub SDK** for managed WebSocket service\n- **Native WebSocket** fallback for local development\n- **CORS** configured for cross-origin requests\n\n#### Development Tools\n- **ESLint** for code quality\n- **TypeScript** compiler with strict mode\n- **tsx** for development with hot reload\n- **Comprehensive documentation** and code comments\n\n## Quick Start\n\n### Prerequisites\n- **Node.js 18+** \n- **npm** or **yarn**\n- **Git** for version control\n- Optional: **Azure WebPubSub service** for cloud mode\n\n### 1. Clone and Install\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd chalice\n\n# Install root dependencies\nnpm install\n\n# Install server dependencies  \ncd server \u0026\u0026 npm install \u0026\u0026 cd ..\n\n# Install web dependencies\ncd web \u0026\u0026 npm install \u0026\u0026 cd ..\n```\n\n### 2. Environment Setup\n```bash\n# Server configuration\ncd server\ncp .env.example .env\n\n# For local development (mock mode), comment out Azure connection:\n# AZURE_WEB_PUBSUB_CONNECTION=Endpoint=...;AccessKey=...;Version=1.0;\nHUB=chat\nPORT=3001\nWS_PORT=3002\n```\n\n### 3. Start Development Servers\n```bash\n# Terminal 1: Start backend server\ncd server\nnpm run dev\n\n# Terminal 2: Start frontend server  \ncd web\nnpm run dev\n```\n\n### 4. Open Application\n- **Frontend**: http://localhost:5173\n- **Backend API**: http://localhost:3001\n- **Mock WebSocket**: ws://localhost:3002\n\n## Project Structure\n\n```\nchalice/\n├── server/                    # Backend Express.js application\n│   ├── src/\n│   │   └── index.ts              # Main server file with dual-mode support\n│   ├── dist/                  # Compiled JavaScript output\n│   ├── package.json              # Server dependencies and scripts\n│   ├── tsconfig.json             # TypeScript configuration\n│   ├── .env                      # Environment variables\n│   └── README.md                 # Server-specific documentation\n│\n├── web/                       # Frontend React application  \n│   ├── src/\n│   │   ├── App.tsx               # Main React component\n│   │   ├── main.tsx              # React app entry point\n│   │   ├── hooks/\n│   │   │   └── useWebPubSub.ts   # Custom WebSocket hook\n│   │   ├── types.ts              # Shared TypeScript types\n│   │   └── assets/            # Static assets\n│   ├── public/                # Public static files\n│   ├── dist/                  # Production build output\n│   ├── package.json              # Frontend dependencies and scripts\n│   ├── vite.config.ts            # Vite bundler configuration\n│   ├── tsconfig.json             # TypeScript configuration\n│   └── README.md                 # Frontend-specific documentation\n│\n├── package.json                  # Root package.json for monorepo\n├── INTERVIEW_GUIDE.md            # Comprehensive interview preparation\n└── README.md                     # This file - project overview\n```\n\n## Development Workflow\n\n### Available Scripts\n\n#### Root Level Commands\n```bash\n# Install all dependencies\nnpm install\n\n# Start both server and web in development mode\nnpm run dev\n\n# Build both applications for production\nnpm run build\n```\n\n#### Server Commands (`cd server`)\n```bash\nnpm run dev      # Start development server with hot reload\nnpm run build    # Compile TypeScript to JavaScript\nnpm start        # Run production server\nnpm test         # Run test suite (when implemented)\n```\n\n#### Web Commands (`cd web`)  \n```bash\nnpm run dev      # Start Vite development server\nnpm run build    # Build production bundle\nnpm run preview  # Preview production build locally\nnpm run lint     # Run ESLint for code quality\n```\n\n### Development Features\n- **Hot Module Replacement** for instant updates\n- **TypeScript compilation** with strict type checking  \n- **Auto-reconnection** for WebSocket connections\n- **CORS configuration** for cross-origin development\n- **Environment-based configuration** for different deployment targets\n\n## Deployment Options\n\n### Local Development (Mock Mode)\n- Uses native WebSocket server on port 3002\n- No external dependencies or cloud services required\n- Perfect for local development and testing\n\n### Azure Cloud (Production Mode)\n1. Create Azure WebPubSub service in Azure Portal\n2. Get connection string from service keys\n3. Set `AZURE_WEB_PUBSUB_CONNECTION` environment variable\n4. Deploy applications to preferred hosting service\n\n### Docker Deployment\n```dockerfile\n# Example Dockerfile for server\nFROM node:18-alpine\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci --only=production\nCOPY dist/ ./dist/\nEXPOSE 3001\nCMD [\"npm\", \"start\"]\n```\n\n### Popular Hosting Options\n- **Frontend**: Vercel, Netlify, Azure Static Web Apps\n- **Backend**: Azure App Service, AWS Lambda, Railway, Heroku\n- **WebSocket**: Azure WebPubSub, AWS API Gateway WebSocket, self-hosted\n\n## Learning Objectives\n\nThis project is designed to teach modern web development concepts:\n\n### React Development\n- **Functional components** with hooks\n- **Custom hooks** for reusable logic\n- **State management** patterns\n- **TypeScript integration** with React\n- **Performance optimization** techniques\n- **Real-time data** handling\n\n### Node.js Backend\n- **Express.js** REST API development\n- **WebSocket** server implementation\n- **Azure cloud services** integration\n- **Environment-based configuration**\n- **Error handling** and resilience patterns\n\n### Full-Stack Integration\n- **API design** and consumption\n- **Real-time communication** patterns\n- **Type safety** across frontend/backend\n- **Development vs production** configuration\n- **Monorepo** project structure\n\n## For Vue.js/Laravel Developers\n\nThis project includes extensive comparisons and explanations for developers transitioning from:\n\n### Vue.js → React\n- **Composition API ↔ React Hooks** patterns\n- **Template syntax ↔ JSX** differences  \n- **Reactivity ↔ State management** approaches\n- **Component architecture** comparisons\n\n### Laravel → Node.js/Express\n- **Routing** pattern differences\n- **Middleware** implementation\n- **Environment configuration** \n- **API development** practices\n\n### Key Documentation\n- **INTERVIEW_GUIDE.md** - Comprehensive technical interview preparation\n- **server/README.md** - Backend architecture and Express.js patterns\n- **web/README.md** - Frontend architecture and React patterns\n- **Inline comments** - Detailed explanations throughout the codebase\n\n## Key Features Explained\n\n### Dual-Mode Architecture\n```typescript\n// Automatic environment detection\nif (process.env.AZURE_WEB_PUBSUB_CONNECTION) {\n  // Production: Use Azure WebPubSub\n  azureService = new WebPubSubServiceClient(connectionString, hubName);\n} else {\n  // Development: Use mock WebSocket server\n  mockWebSocketServer.start();\n}\n```\n\n### Custom React Hook\n```typescript\n// Encapsulates WebSocket logic in reusable hook\nfunction useWebPubSub(room: string) {\n  const [connected, setConnected] = useState(false);\n  const [messages, setMessages] = useState\u003cChatMsg[]\u003e([]);\n  \n  useEffect(() =\u003e {\n    // Connection setup and cleanup\n  }, [room]);\n  \n  return { connected, messages };\n}\n```\n\n### Type-Safe Communication\n```typescript\n// Shared types ensure consistency\ntype ChatMsg = {\n  user: string;\n  text: string;\n  ts: number;\n};\n\n// Used across frontend, backend, and WebSocket messages\n```\n\n## Testing Strategy\n\n### Unit Testing (Planned)\n- **React components** with React Testing Library\n- **Custom hooks** with testing utilities\n- **API endpoints** with supertest\n- **WebSocket functionality** with mock clients\n\n### Integration Testing (Planned)\n- **Full chat flow** end-to-end\n- **Connection fallback** testing\n- **Error scenarios** validation\n\n### Manual Testing\n```bash\n# Test REST endpoints\ncurl http://localhost:3001/negotiate\ncurl -X POST http://localhost:3001/chat -d '{\"room\":\"test\",\"user\":\"Test\",\"text\":\"Hello\"}'\n\n# Test WebSocket with wscat\nnpm install -g wscat\nwscat -c \"ws://localhost:3002?user=TestUser\"\n```\n\n## Performance Considerations\n\n### Frontend Optimization\n- **useMemo** for expensive computations\n- **Component memoization** for stable renders\n- **Bundle splitting** with Vite\n- **Tree shaking** for minimal bundle size\n\n### Backend Optimization  \n- **Connection pooling** for WebSocket clients\n- **Memory-efficient** data structures (Set/Map)\n- **Automatic cleanup** of dead connections\n- **Horizontal scaling** ready architecture\n\n### WebSocket Optimization\n- **Automatic reconnection** on connection loss\n- **Message queuing** during disconnections\n- **Connection state management**\n- **Graceful error handling**\n\n## Security Considerations\n\n### Authentication (Ready for Implementation)\n- **JWT token** support in negotiate endpoint\n- **User identity** validation\n- **Rate limiting** for API endpoints\n- **CORS** properly configured\n\n### Input Validation\n- **TypeScript** compile-time validation\n- **Runtime validation** for API inputs\n- **XSS prevention** with proper escaping\n- **Message sanitization**\n\n### Production Security\n- **Environment variables** for secrets\n- **HTTPS/WSS** for encrypted communication\n- **Azure managed identity** for cloud resources\n- **Access key rotation** best practices\n\n## Troubleshooting\n\n### Common Issues\n\n**Connection Refused**\n```bash\n# Check if servers are running\ncurl http://localhost:3001/negotiate\nlsof -i :3001  # Check port usage\n```\n\n**WebSocket Connection Failed**\n```bash\n# Verify mock server\nlsof -i :3002\n# Check browser console for connection errors\n```\n\n**TypeScript Compilation Errors**\n```bash\n# Check TypeScript configuration\nnpm run build\n# Verify all imports and type definitions\n```\n\n**Azure WebPubSub Issues**\n- Verify connection string format\n- Check service status in Azure Portal  \n- Validate access key permissions\n- Review service logs\n\n### Debug Mode\n```bash\n# Enable verbose logging\nDEBUG=* npm run dev\n\n# TypeScript watch mode\nnpx tsc --watch\n```\n\n## Additional Resources\n\n### Official Documentation\n- [React Documentation](https://react.dev/)\n- [TypeScript Handbook](https://www.typescriptlang.org/docs/)\n- [Azure WebPubSub Docs](https://docs.microsoft.com/en-us/azure/azure-web-pubsub/)\n- [Express.js Guide](https://expressjs.com/)\n\n### Learning Materials\n- [React Hooks Guide](https://react.dev/reference/react)\n- [WebSocket API Reference](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)\n- [Node.js Best Practices](https://nodejs.dev/learn/)\n- [TypeScript with React](https://react-typescript-cheatsheet.netlify.app/)\n\n### Community Resources\n- [React Community](https://reactjs.org/community/support.html)\n- [Node.js Community](https://nodejs.org/en/get-involved/)\n- [Azure Developer Community](https://techcommunity.microsoft.com/t5/azure-developer-community-blog/bg-p/AzureDevCommunityBlog)\n\n## Contributing\n\nWe welcome contributions! This project serves as a learning resource, so contributions that improve documentation, add educational value, or demonstrate best practices are especially appreciated.\n\n### Development Setup\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with proper TypeScript types\n4. Add/update documentation and comments\n5. Test your changes thoroughly\n6. Submit a pull request\n\n### Code Style\n- Use **TypeScript** with strict mode\n- Follow **ESLint** recommendations\n- Add **comprehensive comments** for educational value\n- Include **type definitions** for all interfaces\n- Write **self-documenting code** with clear naming\n\n## License\n\nThis project is open source and available under the [MIT License](LICENSE).\n\n---\n\n## Getting Started Checklist\n\n- [ ] **Clone repository** and install dependencies\n- [ ] **Start both servers** (backend + frontend)  \n- [ ] **Open application** in browser (localhost:5173)\n- [ ] **Send first message** to test real-time functionality\n- [ ] **Review code structure** and documentation\n- [ ] **Explore INTERVIEW_GUIDE.md** for technical deep-dive\n- [ ] **Experiment with features** and code modifications\n- [ ] **Deploy to cloud** (optional) with Azure WebPubSub\n\nWelcome to **Chalice** - your gateway to modern full-stack development with React and Azure!\n\n---\n\n*This project is designed to be educational, production-ready, and a great addition to your portfolio. Happy coding!*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthavarshan%2Fchalice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthavarshan%2Fchalice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthavarshan%2Fchalice/lists"}