Clanker
An AI chatbot Expo app with Firebase + Cloud SQL architecture. Users create custom characters and chat with them using Vertex AI, with subscription-based access control.
Documentation Deep Dives
Authentication
- Authentication — Source of truth, Firebase → Cloud SQL bootstrap flow, auth cache management, provider name sync, event-driven refresh, cookie consent, and optimistic terms acceptance — all in one place.
AI & Chat
- AI & Chat — Chat response pipeline (
generateReply), chat memory summarization, LLM Wiki Memory (structured facts/tasks/events), wiki state machine architecture, image generation (generateImage), and local cloud-agent dev (local Postgres + Vertex via ADC; see docker-compose.local.yml and ./scripts/migrate-dev.sh).
- Browser Bridge — Clanker Desktop Bridge MV3 extension: cross-device web tasks via
browser_action, Wake-and-Connect lifecycle, Firestore coordination, approval flow, pairing, and billing.
- Desktop Vault Bridge —
/agent/desktop persistent WebSocket, pairing tokens, vault_* tools querying the Curated Thoughts home vault.
- Real-Time Voice Chat — Talk tab live voice calls via Gemini Live (
/agent/live WebSocket), XState session lifecycle, audio I/O, pre-flight checks, and native build requirements.
- Edge Agent — On-device tool orchestration loop (BYOI proxy via
generateReply), escalation paths, per-round billing, and security policy.
- OKF Import & Export — Restore or clone a character's memory from a portable backup
Billing & Credits
- Billing & Credits — First-login credits, Stripe and RevenueCat webhook event mappings, web checkout flow, Apple auto-renewable subscription consent, and multi-tab checkout robustness (localStorage + BroadcastChannel).
Admin Operations
- Admin Operations — Web-only admin dashboard UX, callable function contracts (list/set/reset/delete), authorization model, audit logging, and runbook with action procedures.
Architecture & Data
- Architecture & Data — State management (xState / TanStack Query / SQLite), navigation (Expo Router), offline support architecture, Cloud SQL schema design & migrations, cloud character save/share, avatar upload, and support page.
ADRs
Workflows & Debugging
- Contributing Guide — Git workflow, merge strategy, coding standards, commit guidelines (Conventional Commits), testing (root + functions), web debugging, and PR process — all in one place.
Other Reference
- Accessibility Guide — Conventions for
accessibilityLabel, accessibilityRole, accessibilityHint, live regions, and skip links.
- Architecture Charts — Auto-generated Mermaid dependency charts per module, plus C4 system context and container diagrams.
- Web Root Landing — Production
/ serves the generated static landing page (landing/index.html); in-app / routes signed-in users to /chat and others to /sign-in.
🏗️ Tech Stack
- Frontend: React Native 0.81, Expo SDK 54, TypeScript 5.9
- Navigation: Expo Router (file-based routing)
- Authentication: Firebase Auth
- Backend: Firebase Functions + Cloud SQL (PostgreSQL)
- AI: Google Cloud Vertex AI
- State Management: React Query (TanStack Query)
- Payments: Stripe (web) + RevenueCat (iOS/Android)
- UI Components: React Native Paper, Gifted Chat
🤝 Contributing
We welcome contributions! Please see our Contributing Guidelines for details on:
- How to set up your development environment
- Our code style and conventions
- How to submit pull requests
- Our commit message format
Please read our Code of Conduct before contributing.
🔒 Security
If you discover a security vulnerability, please email [email protected]. Do not create a public issue. See SECURITY.md for more details.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
📞 Support
Made with ❤️ by Equational Applications LLC
