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.

Getting Started

• Git Workflow & Branching — Branch strategy (staging → main), PR process, commit guidelines, and conventional commits.
• Merge Strategy — How to promote code from staging → main (and sync main → staging) using merge commits.
• Expo Updates & Runtime Versioning — How OTA updates work, runtime version strategy, and the relationship between conventional commits and deployment types (OTA vs native builds).
• Web Debugging — Live debugging with Metro + VS Code browser tools; React Native Web style pitfalls (gap, style arrays, animationType) that crash Chrome.

State Management

• State management architecture — Layer overview (xState / TanStack Query / SQLite), when and how to add new xState machines, inter-machine coordination via AppOrchestrator, and how useCurrentPlan derives plan tier from the auth machine.

Architecture & Auth

• Auth flow (concise) — Step-by-step: Firebase Auth → exchangeToken cloud function → Cloud SQL bootstrap payload.
• Auth source-of-truth — Why Firebase is the canonical identity provider and how Cloud SQL bootstrap state is used downstream.
• Auth provider name sync — How Apple/Google names are captured and synced to profile display data.
• Bootstrap event-driven refresh — How auth bootstrap reconciliation now works without interval polling, including refresh reason semantics, lifecycle triggers, and usage snapshot updates.
• Firebase setup — How to configure mobile Firebase app files for EAS builds and local builds.
• Firebase Cloud Functions — How backend functions (exchangeToken, purchasePackageStripe) are managed and deployed.
• Callable error normalization — How callable handlers map bootstrap/config errors to stable HttpsError codes without leaking internals.
• Chat response function — Secure callable architecture for server-side text generation, auth checks, and credit billing.
• Image generation function — Server-side image generation with auth, billing, and abuse controls.
• Firebase Functions testing — Test strategy and local commands for callable and webhook function coverage in functions/.
• Navigation structure — Overview of app navigation, including Drawer, Tab, and Stack navigators.
• Admin dashboard — Web-only admin UX architecture, route guards, and mandatory confirmation behavior for privileged actions.
• Admin functions — Callable contracts, authorization model, validation rules, and audit logging schema.
• Admin runbook — Operational procedures and safety checklists for reset/delete workflows.

Data & Features

• Image generation — Callable-based image generation flow with local SQLite avatar storage.
• Avatar gallery upload — Photo-library avatar upload flow with local WebP conversion and SQLite-only storage.
• Chat memory summarization — Background conversation summarization every 20 messages with SQLite pruning and context compaction.
• LLM Wiki Memory — Structured, queryable memory with facts, tasks, and episodic events for premium users; FTS5-based search with multi-layer query preprocessing and optional Cloud SQL sync.
• Wiki state machine architecture — XState-based per-character wiki orchestration: state machine design, orchestrator API, data flow, and key design decisions.
• First-login credits — How first-login users are provisioned to 50 free credits.
• Cloud character save + share — Subscription-gated cloud save toggles, shareable character links, and deep-link import flow.
• Cloud SQL design — Current PostgreSQL schema and service-layer architecture for all 8 tables: users, subscriptions, characters, messages, credit_transactions, wiki_entries, agent_tasks, and memory_events.
• Cloud SQL migrations — How to generate and apply schema migrations to production using the Cloud SQL Auth Proxy.

Payments & Subscriptions

• Payment API reference — Transaction manager, webhook endpoints, and auth requirements.
• Payment integration — Client-side integration patterns for payments and subscriptions.
• Payment system design — Architecture and billing flow for multi-tenant subscriptions.
• Payment troubleshooting — Common webhook and billing errors with fixes.
• Multi-tab checkout robustness — How Stripe return-tab recovery works using localStorage, BroadcastChannel, per-product locks, and event-driven refresh without polling.

Policies & Compliance

• Privacy integration — How privacy policy and user consent are handled.
• Cookie consent (web) — Lower-right banner with Accept/Reject parity, granular preferences, and canUse() gating for non-essential cookies, satisfying GDPR + Quebec Law 25.
• Terms integration — Legacy terms flow vs subscription-driven access control.
• Apple subscription consent — Paywall legal-link requirements, Terms + Apple EULA hosting, and safe custom-consent scope for auto-renewable subscriptions.
• Support page — Public support route and FAQ content used for App Store support URL compliance.
• Accessibility guide — Conventions for accessibilityLabel, accessibilityRole, accessibilityHint, live regions, and skip links. Covers both web and native.

🏗️ 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
• 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 info@equationalapplications.com. 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

• Built with Expo
• UI components from React Native Paper
• Chat interface powered by React Native Gifted Chat
• AI capabilities provided by Google Cloud Vertex AI

📞 Support

• Documentation: Check the /docs folder for detailed guides
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: info@equationalapplications.com

---

Made with ❤️ by Equational Applications LLC