ChatKcal Documentation
What is this?
ChatKcal is an AI-first calorie tracker designed to simplify nutrition logging by leveraging the power of Large Language Models (LLMs). This documentation serves as the central source of truth for our architecture, development standards, and project roadmap.
Links Command Center
| Service | Environment / Details | Link |
|---|---|---|
| Production | chatkcal.app | Open |
| Development | Amplify Dev App | Open |
| Live Docs | Cloudflare Pages | Open |
| Local App | Vite Dev Server | localhost:5173 |
| Local Docs | MkDocs Serve | localhost:8010 |
| AWS Console | 051997448445 (ben-admin) |
Login |
| DynamoDB | Tables (ap-southeast-2) | Manage |
| Cognito | User Pool ap-southeast-2_JzQaTK8eY |
View |
| Cloudflare | Pages Dashboard | Dash |
🏗️ Architecture
Deep dives into the system design, including our offline-first approach and testing philosophy.
- Data Model: Single Table Design and aggregation logic.
- Frontend & Offline: PWA and TanStack Query persistence.
- Testing Strategy: Our "Testing Trophy" approach and CI/CD gates.
- Auth & Security: Cognito integration and social sign-in.
📝 Development Notes
Guides, patterns, and best practices for building and maintaining ChatKcal.
- Setup & Installation: Get the project running locally.
- Best Practices:
- Patterns:
- Learnings:
📈 Project Management
Tracking our progress from foundation to friction-zero UX.
- Master Plan & Roadmap: The high-level goals.
- Incident Reports: Post-mortems and learnings (e.g., Settings Race Condition).
- Recent Logs:
🚀 Quick Start (Development)
To serve this documentation locally:
To start the frontend development server:
To start the frontend and docs together with repository-local PM2:
The PM2 session keeps the app on http://127.0.0.1:5173 and serves docs on http://127.0.0.1:8010.
To build the backend: