{"id":31548704,"url":"https://github.com/blawby/blawby-ai-chatbot","last_synced_at":"2026-05-18T11:06:02.891Z","repository":{"id":303347563,"uuid":"1000619773","full_name":"Blawby/blawby-ai-chatbot","owner":"Blawby","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-02T05:02:35.000Z","size":3763,"stargazers_count":4,"open_issues_count":9,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-02T05:29:39.159Z","etag":null,"topics":["cloudflare-api","cloudflare-pages","cloudflare-workers","legaltech","preact"],"latest_commit_sha":null,"homepage":"https://ai.blawby.com","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/Blawby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-12T04:24:46.000Z","updated_at":"2025-10-02T05:02:38.000Z","dependencies_parsed_at":"2025-07-08T08:22:38.364Z","dependency_job_id":"cd433c97-f3be-4e9a-bf5e-d87cd37feb0c","html_url":"https://github.com/Blawby/blawby-ai-chatbot","commit_stats":null,"previous_names":["blawby/preact-cloudflare-intake-chatbot","pcl-labs/preact-cloudflare-intake-chatbot","blawby/blawby-ai-chatbot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Blawby/blawby-ai-chatbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blawby%2Fblawby-ai-chatbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blawby%2Fblawby-ai-chatbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blawby%2Fblawby-ai-chatbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blawby%2Fblawby-ai-chatbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Blawby","download_url":"https://codeload.github.com/Blawby/blawby-ai-chatbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blawby%2Fblawby-ai-chatbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278343086,"owners_count":25971399,"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","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["cloudflare-api","cloudflare-pages","cloudflare-workers","legaltech","preact"],"created_at":"2025-10-04T16:51:26.192Z","updated_at":"2026-05-18T11:06:02.884Z","avatar_url":"https://github.com/Blawby.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Legal Intake Chatbot - Cloudflare Workers AI\n\nA legal intake chatbot built with Cloudflare Workers AI, featuring intelligent conversation handling, step-by-step information collection, and automated matter creation with payment integration.\n\n## 🚀 **Quick Start**\n\n### Prerequisites\n- Node.js 18+ and npm\n- Cloudflare account with Workers, D1, KV, and R2 access\n\n### Installation\n\n1. **Clone and install**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd preact-chat-gpt-interface\n   npm install\n   ```\n\n2. **Set up environment**\n   ```bash\n   cp dev.vars.example worker/.dev.vars\n   # Edit worker/.dev.vars with your API keys\n   # Note: .dev.vars must be in worker/ directory (same as wrangler.toml)\n   ```\n\n3. **Set up local database**\n   ```bash\n   # Reset database with consolidated schema (recommended for development)\n   npm run db:reset\n   \n   # OR apply schema only (if database is empty)\n   npm run db:init\n   ```\n\n4. **Start development**\n   ```bash\n   # Option 1: Start both frontend and worker (recommended)\n   npm run dev:full\n   \n   # Option 2: Start worker only\n   npm run dev:worker\n   # OR manually:\n   # npx wrangler dev --port 8787 --config worker/wrangler.toml\n   \n   # Option 3: Start frontend only\n   npm run dev\n   ```\n\n5. **Deploy to Cloudflare**\n   ```bash\n   npx wrangler deploy --config worker/wrangler.toml\n   ```\n   This deploys the Cloudflare Worker only (Pages is configured separately).\n\n## 🎯 **Key Features**\n\n- **🤖 AI-Powered Legal Intake**: Intelligent conversation handling with Cloudflare Workers AI\n- **🌍 Global Language Support**: 18 languages covering 5+ billion speakers — ~90%+ of global internet users — with full RTL support for Arabic\n- **📋 Lead Qualification**: Smart filtering to ensure quality leads before contact collection\n- **⚖️ Matter Classification**: Automatic legal issue categorization (Employment, Family, Personal Injury, etc.)\n- **💰 Payment Integration**: Automated consultation fee collection with organization configuration\n- **👨‍💼 Human Review Queue**: Lawyer oversight for urgent/complex matters\n- **📱 Mobile-First Design**: Responsive interface with modern UI/UX\n- **📎 File Upload Support**: Photos, videos, audio, documents (25MB max) with camera capture\n- **🔐 Authentication**: Handled by remote Better Auth server at staging-api.blawby.com\n- **🔒 Production Security**: OWASP-compliant headers and validation\n\n## 🏗️ **Architecture**\n\n```\nFrontend (Preact) → Cloudflare Workers → AI Agent → Tool Handlers → Actions\n```\n\n**Core Components:**\n- **Legal Intake Agent**: Self-contained AI with built-in memory and tool execution\n- **Tool Handlers**: Modular functions for contact collection, matter creation, lawyer review\n- **organization Configuration**: Dynamic payment and service configuration per organization\n- **Review Queue**: Human-in-the-loop system for lawyer oversight\n\n## 🛠️ **Technology Stack**\n\n- **Frontend**: Preact, TypeScript, Tailwind CSS\n- **Backend**: Cloudflare Workers, D1 Database, KV Storage, R2 Object Storage\n- **AI**: Cloudflare Workers AI (GPT-OSS 20B)\n- **Auth**: Remote Better Auth server (staging-api.blawby.com)\n- **Deployment**: Cloudflare Workers\n\n## 🧪 **Testing**\n\n```bash\n# Start development servers (required for tests)\nnpm run dev:full\n\n# Run tests\nnpm run test:conversation  # Core AI functionality tests\nnpm test                   # All unit/integration tests\nnpm run test:watch         # Watch mode\nnpm run test:i18n          # Smoke test to confirm translations switch correctly\nnpm run lint:i18n          # Validate locale files stay in sync\n```\n\n## 📁 **Project Structure**\n\n```\n├── src/                    # Frontend (Preact + TypeScript)\n│   ├── components/        # UI components\n│   ├── hooks/            # Custom React hooks\n│   └── utils/            # Utility functions\n├── worker/               # Backend (Cloudflare Workers)\n│   ├── agents/          # AI agent definitions\n│   ├── routes/          # API endpoints\n│   ├── services/        # Business logic\n│   └── utils/           # Worker utilities\n├── tests/               # Test files\n└── public/              # Static assets\n```\n\n## 🔧 **Configuration**\n\n### Environment Variables\n\n#### Worker Secrets (`.dev.vars`)\nCopy `dev.vars.example` to `worker/.dev.vars` and add your API keys:\n- `LAWYER_SEARCH_API_KEY` - Lawyer search API key\n- `CLOUDFLARE_API_TOKEN` - Cloudflare operations API key\n- `ONESIGNAL_APP_ID` - OneSignal app id\n- `ONESIGNAL_REST_API_KEY` - OneSignal REST API key\n\n**Note:** Wrangler reads `.dev.vars` from the same directory as `wrangler.toml`. Since `wrangler.toml` is in the `worker/` directory, create `worker/.dev.vars` directly.\n\n#### Frontend Environment Variables\n\n**For Local Development:**\nCreate a `.env` file in the project root for frontend environment variables:\n\n- `VITE_BACKEND_API_URL` - URL of your remote backend API server (auth/practice/etc.)\n  - Example: `http://localhost:3000` for local development\n  - Optional in development - will fall back to staging API for testing if not set\n- `VITE_WORKER_API_URL` - Base URL for the Cloudflare Worker API (no `/api` suffix)\n  - Example: `http://localhost:8787` for local development\n  - Optional: defaults to localhost in dev and same-origin in prod\n- `VITE_ONESIGNAL_APP_ID` - OneSignal app id for the web SDK (required if using push notifications)\n\n**For Production (Cloudflare Pages):**\nSet frontend environment variables in Cloudflare Pages:\n\n1. Go to your Cloudflare Pages project dashboard\n2. Navigate to **Settings \u003e Environment Variables**\n3. Add required variables:\n   - `VITE_BACKEND_API_URL` - Your production remote API URL (e.g., `https://production-api.blawby.com`)\n   - `VITE_WORKER_API_URL` - Your worker base URL (e.g., `https://ai.blawby.com`, no `/api` suffix)\n   - `VITE_ONESIGNAL_APP_ID` - Your OneSignal app ID (if using push notifications)\n\n**Important:** \n- Frontend environment variables (prefixed with `VITE_`) are bundled into the frontend code at build time\n- Cloudflare Pages automatically injects environment variables during the build process\n- The application will fail at runtime (when auth is used) if `VITE_BACKEND_API_URL` is not set in production\n- These variables should NOT be set in `worker/.dev.vars` (that's for Worker secrets only)\n\n### Internationalization\n\nThe application supports **18 languages** covering 5+ billion speakers — ~90%+ of global internet users:\n\n**Supported Languages:**\n- 🌍 **Americas**: English, Spanish, Portuguese, French\n- 🇪🇺 **Europe**: English, Spanish, French, German, Russian, Italian, Dutch, Polish, Ukrainian\n- 🌏 **Asia**: Chinese, Japanese, Vietnamese, Korean, Thai, Indonesian, Hindi\n- 🇸🇦 **Middle East/Africa**: Arabic (with full RTL support), French, English\n\n**Features:**\n- ✅ Seamless language switching via Settings → General\n- ✅ Automatic language detection based on user location\n- ✅ Complete Right-to-Left (RTL) support for Arabic\n- ✅ 5 namespaces: common, settings, auth, profile, pricing\n- ✅ 50+ country-to-language mappings\n- ✅ Lazy-loaded translations for optimal performance\n\n**Development:**\n- Locale files: `src/locales/\u003clocale\u003e/\u003cnamespace\u003e.json`\n- Configuration: `src/i18n/index.ts`\n- Full guide: `docs/internationalization.md`\n- Run `npm run lint:i18n` to validate translation consistency\n- Run `npm run test:i18n` for internationalization smoke tests\n\n### Organization Management\nOrganization management (CRUD, invitations, subscriptions) is handled by the remote API at `staging-api.blawby.com`:\n- Frontend calls remote API endpoints for organization operations\n- Local worker only handles workspace endpoints (`/api/organizations/:id/workspace/*`) for chatbot data\n- Organization metadata (config, subscription status) is fetched from remote API when needed\n\n### Authentication \u0026 User Management\nUser authentication is handled by a remote Better Auth server at `staging-api.blawby.com`:\n- Frontend uses Better Auth React client (`better-auth/react`) to connect to remote auth server\n- Session cookies are stored by the browser and sent with authenticated requests\n- Worker validates sessions by calling the remote auth server API with the cookie\n- Organization membership and roles are managed through the remote Better Auth server\n- Access the application with `?organizationId=\u003corg-slug\u003e` parameter\n\n## 🔒 **Security**\n\n- OWASP-compliant security headers\n- File upload validation (25MB max)\n- Rate limiting (60 requests/minute)\n- Input sanitization\n- Secure session management with Better Auth\n\n## 🔧 **Troubleshooting**\n\n### Common Issues\n\n**Port 8787 already in use:**\n```bash\n# Kill existing processes on port 8787\nnpm run dev:worker:clean\n```\n\n**Environment variables not loading:**\n- Ensure `worker/.dev.vars` exists and contains your API keys\n- Wrangler reads `.dev.vars` from the same directory as `wrangler.toml` (which is `worker/`)\n\n**Database connection issues:**\n```bash\n# Reset local database\nnpm run db:reset\n```\n\n**Worker not starting:**\n```bash\n# Check wrangler installation\nnpx wrangler --version\n\n# Ensure you're using the correct config file\nnpm run dev:worker\n# OR manually:\n# npx wrangler dev --port 8787 --config worker/wrangler.toml\n\n# Start with verbose logging\nnpx wrangler dev --port 8787 --config worker/wrangler.toml --log-level debug\n```\n\n**Worker shows \"Pages project\" error:**\n- This happens when wrangler picks up the root `wrangler.toml` (configured for Pages)\n- Always use `--config worker/wrangler.toml` or `npm run dev:worker` which includes this flag\n\n## 🤝 **Contributing**\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Submit a pull request\n\n## 📄 **License**\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n**Built with ❤️ using Cloudflare Workers AI and Preact**\n\nSat Feb 21, 2026\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblawby%2Fblawby-ai-chatbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblawby%2Fblawby-ai-chatbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblawby%2Fblawby-ai-chatbot/lists"}